ZiB Network

<script src="https://app.zibnetwork.com/sdk/zib-sdk.js"></script>

Authorization: Bearer <access_key>:<secret_key>

// Server: initiate the upload (credentials stay on your server)
const initRes = await fetch('https://api.zibnetwork.com/v1/api/upload/initiate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ZIB_ACCESS_KEY}:${process.env.ZIB_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    bucket: 'my-bucket',
    key: 'videos/intro.mp4',
    file_size: fileBuffer.length,
    content_type: 'video/mp4',  // forwarded to the CDN's Content-Type header
  }),
});
const registration = await initRes.json();
// registration = { type, file_id, upload_url?, upload_id?, ... }
// (Additional opaque fields are returned — pass the entire object straight to the SDK.)

// Return 'registration' to the browser for ZiBStorage.uploadDirect()
// or use the SDK on the server side if you need a non-browser upload path.

import requests

headers = {"Authorization": f"Bearer {ZIB_ACCESS_KEY}:{ZIB_SECRET_KEY}"}

# List buckets
buckets = requests.get("https://s3.zibnetwork.com/s3/", headers=headers)

# List objects
objects = requests.get("https://s3.zibnetwork.com/s3/my-bucket", headers=headers)

# Start encoding
res = requests.post(
    "https://api.zibnetwork.com/v1/api/encoding/jobs",
    headers={**headers, "Content-Type": "application/json"},
    json={"object_key": file_id, "transcription": "recommended"},
)
job = res.json()  # { encoding_id, status, progress, ... }

{
  "encode": true,
  "transcription": "fastest" | "recommended" | "accurate",
  "vision": "standard" | "hq",
  "webhook_url": "https://yourapp.com/api/zib-pipeline-event",
  "webhook_secret": "whsec_..."
}

// server route — e.g. /api/upload-initiate
const res = await fetch('https://api.zibnetwork.com/v1/api/upload/initiate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${ACCESS_KEY}:${SECRET_KEY}`,
  },
  body: JSON.stringify({
    bucket: 'video',
    key: `videos/${contentId}/${videoType}-${Date.now()}-${fileName}`,
    file_size: fileSize,
    pipeline: {
      encode: true,
      transcription: 'recommended',
      vision: 'standard',
      // Thumbnails are ON by default — omit the field for defaults.
      // thumbnails: false  → opt out
      // thumbnails: { poster: { at: '10%' }, sprite: { interval: 5, width: 160 } }
      //                     → override individual fields
      // Vertical aspect-variant renditions for short-form / Shorts feeds.
      // OFF by default — omit the field for none. Current v1 accepts only ["9:16"].
      // aspect_variants: ['9:16']  → enable a 9:16 vertical rendition alongside
      //                              the main HLS. See "Aspect variants" below.
      webhook_url: 'https://yourapp.com/api/zib-pipeline-event',
      webhook_secret: process.env.WEBHOOK_SECRET,
    },
  }),
})

const registration = await res.json()
// Return registration to browser — credentials stay on the server
return Response.json(registration)

{
  "file_id": "a1b2c3d4-...",
  "status": "ai_processing",
  "cdn_url": "https://cdn.zibnetwork.com/objects/a1b2c3d4-...",
  "declared": { "encode": true, "transcription": "recommended", "vision": "standard" },
  "stages": {
    "upload":        { "status": "complete",
                       "phase": "distributed",
                       "replication_safe_at": null },
    "encoding":      { "status": "completed", "encoding_id": "...", "progress": 100,
                       "hls_manifest_url": "https://cdn.zibnetwork.com/...m3u8" },
    "transcription": { "status": "running", "tier": "recommended", "progress": 40,
                       "output_file_id": null },
    "vision":        { "status": "queued", "tier": "standard", "progress": 0,
                       "output_file_id": null }
  },
  "error": null
}

// Server-side only — your master Bearer credentials never reach the browser.
const res = await fetch('https://api.zibnetwork.com/v1/api/upload/pin/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.ZIB_ACCESS_KEY}:${process.env.ZIB_SECRET_KEY}`,
  },
  body: JSON.stringify({
    bucket: 'video',
    key: 'videos/abc-123/main.mp4',
    pipeline: {
      encode: true,
      webhook_url: 'https://yourapp.com/api/zib-webhook',
      webhook_secret: process.env.ZIB_WEBHOOK_SECRET,
    },
  }),
});

const { pin, session_id, expires_at } = await res.json();
// pin → "mosaic-trinket-blanket"
// session_id → "5a6b862f-9bb6-4c5a-b5f3-df22bb9da959"
// expires_at → "2026-04-10T15:47:03Z"  (24 hours from creation)

// Poll until phase is 'ready' or 'failed'. The status endpoint returns
// a full lifecycle rollup so you can render byte-level upload progress,
// then encoding %, then analysis %, all from the same poll.
async function waitForCompletion(sessionId, onProgress) {
  while (true) {
    const res = await fetch(
      `https://api.zibnetwork.com/v1/api/upload/pin/status/${sessionId}`,
      {
        headers: { 'Authorization': `Bearer ${ACCESS_KEY}:${SECRET_KEY}` },
      }
    );
    const s = await res.json();

    // Surface live progress to the UI. `phase` walks through:
    //   pending → redeemed → uploading → encoding → analyzing → ready
    // Each phase populates its own sub-block (defensive read with ?? null
    // so you don't break if a future phase is added).
    onProgress?.({
      phase: s.phase,
      uploadPercent:    s.upload?.progress_percent      ?? null,
      encodingPercent:  s.encoding?.progress_percent    ?? null,
      analysisStage:    s.analysis?.current_stage       ?? null,
      transcriptionPct: s.analysis?.transcription_progress ?? null,
      visionPct:        s.analysis?.vision_progress     ?? null,
    });

    if (s.phase === 'ready')   return { file_id: s.file_id };
    if (s.phase === 'failed' || s.phase === 'expired') {
      throw new Error(`Upload ${s.phase}: ${s.error_message ?? 'no detail'}`);
    }

    await new Promise(r => setTimeout(r, 2000));  // poll every 2s
  }
}

{
  // Top-level rollup
  "phase": "encoding",                      // pending | redeemed | uploading | encoding | analyzing | ready | failed | expired
  "status": "uploading",                    // legacy field — keep reading 'phase' instead
  "redeemed_by_node_id": "ZB-899233",
  "file_id": "0c8e3765-9b2b-4a29-82cb-2f1911fe750c",
  "file_size_bytes": 1823450000,
  "error_message": null,
  "expires_at": "2026-04-15T15:47:03Z",

  // Populated while phase === "uploading" (omitted if no progress
  // report has landed in the last 30 seconds — node may have stalled)
  "upload": {
    "bytes_uploaded": 412300123,
    "total_bytes": 1823450000,
    "progress_percent": 22.6
  },

  // Populated when the pipeline declares encode: true
  "encoding": {
    "status": "encoding",                   // queued | encoding | complete | failed
    "progress_percent": 47.3
  },

  // Populated when the pipeline declares transcription and/or vision.
  // current_stage tracks the slowest path so a single bar reflects the
  // overall analysis progress.
  "analysis": {
    "current_stage": "transcription",       // "transcription" | "vision"
    "transcription_status": "running",      // null if not declared
    "transcription_progress": 42,           // 0–100, null if not declared
    "vision_status": "queued",              // null if not declared
    "vision_progress": 0                    // 0–100, null if not declared
  }
}

// After uploadDirect() completes, pass file_id to startEncoding
const job = await storage.startEncoding(result.file_id);
console.log(job.encoding_id); // use this to poll status

// Poll until complete
const status = await storage.getEncodingStatus(job.encoding_id);
// status.hls_manifest_url — AES-128 encrypted HLS, plays in any HLS player

// Webhook handler — store the progress value, render in your UI
app.post('/api/zib-webhook', (req, res) => {
  const { event, file_id, progress, stage } = req.body;

  if (event === 'encoding.progress') {
    // progress is an integer 0–100
    // stage is "encoding" or "sharding"
    await db.update('videos', { encoding_progress: progress }, { where: { file_id } });
  }

  if (event === 'encoding.complete') {
    // Final state — manifest URLs are now live
    await db.update('videos', {
      encoding_progress: 100,
      encoding_status: 'complete',
      hls_url: req.body.hls_manifest_url,
    }, { where: { file_id } });
  }

  res.sendStatus(200);
});

async function waitForEncode(fileId, { timeoutMs = 10 * 60_000, intervalMs = 3_000 } = {}) {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const res = await fetch(`https://api.zibnetwork.com/v1/api/pipeline/${fileId}`, {
      headers: { Authorization: `Bearer ${process.env.ZIB_ACCESS_KEY}:${process.env.ZIB_SECRET_KEY}` },
    });
    if (!res.ok) {
      // Transient network / backend error — log and retry next tick.
      await sleep(intervalMs);
      continue;
    }
    const data = await res.json();

    // 1. Null-guard: data or stages.encoding might be missing during the
    //    brief window between request and job-row creation.
    const phase = data?.stages?.encoding?.phase ?? data?.phase;
    if (!phase) {
      await sleep(intervalMs);
      continue;
    }

    // 2. Terminal: success.
    if (phase === 'safe') {
      return { ok: true, manifestUrl: data.cdn_url };
    }

    // 3. Terminal: hard failure (retry budget exhausted).
    if (phase === 'failed_user_action') {
      return { ok: false, error: data.error ?? 'Encoding failed after retries' };
    }

    // 4. Terminal: superseded by a re-upload.
    if (phase === 'cancelled') {
      return { ok: false, error: 'Upload superseded; check for the new file_id' };
    }

    // Anything else (queued, encoding, sharding, failed-transient,
    // local_complete, replicating) — keep polling.
    await sleep(intervalMs);
  }
  return { ok: false, error: 'Timed out waiting for encode' };
}

const sleep = ms => new Promise(r => setTimeout(r, ms));

<!-- hls.js (browser) -->
<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<video id="video" controls></video>
<script>
  const hls = new Hls();
  hls.loadSource('https://cdn.zibnetwork.com/stream/<file_id>/master.m3u8');
  hls.attachMedia(document.getElementById('video'));
</script>

<!-- Native HLS (Safari / iOS) -->
<video controls src="https://cdn.zibnetwork.com/stream/<file_id>/master.m3u8"></video>

// Response when the file is already encoded
{
  "encoding_id": "771a1e5e-5e29-470a-9f1f-5ad8b999efc4",
  "status": "already_encoded",
  "file_id": "01846192-315c-4f0a-b766-12b18a26b209",
  "cdn_url": "https://cdn.zibnetwork.com/stream/01846192-315c-4f0a-b766-12b18a26b209/master.m3u8",
  "message": "File is already encoded by an existing job. Pass { \"force\": true } in the request body to deliberately re-encode."
}

await fetch('https://api.zibnetwork.com/v1/api/encoding/request', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${ZIB_ACCESS_KEY}:${ZIB_SECRET_KEY}`,
  },
  body: JSON.stringify({
    object_key: fileId,        // existing file_id
    force: true,               // override the idempotency gate
    webhook_url: WEBHOOK_URL,  // optional
  }),
});

// All four shapes are valid on POST /v1/api/encoding/request:

// 1. Omit the field — thumbnails generated with defaults.
{ object_key: fileId }

// 2. Explicit defaults.
{ object_key: fileId, thumbnails: true }

// 3. Opt out entirely.
{ object_key: fileId, thumbnails: false }

// 4. Override individual fields (any subset; missing keys fall back to defaults).
{
  object_key: fileId,
  thumbnails: {
    poster: { at: "10%" },            // or "5s" / "Ns" for an absolute timestamp
    sprite: { interval: 5, width: 160 }
  }
}

// thumbnails block — same shape on webhook + both polling endpoints.
// Omitted (or null) when the tenant opted out or before registration completes.
{
  "thumbnails": {
    "poster_url":     "https://cdn.zibnetwork.com/objects/<poster_file_id>",
    "sprite_url":     "https://cdn.zibnetwork.com/objects/<first_sprite_sheet_file_id>",
    "sprite_vtt_url": "https://cdn.zibnetwork.com/objects/<sprite_vtt_file_id>"
  }
}

// Bitmovin
player.load({
  hls: hlsManifestUrl,
  poster: thumbnails.poster_url,
  tracks: {
    thumbnailTrack: {
      file: thumbnails.sprite_vtt_url
    }
  }
});

// hls.js — load the VTT yourself and feed it to your seekbar component:
const vtt = await fetch(thumbnails.sprite_vtt_url).then(r => r.text());
// Each cue body is "<sprite_sheet_url>#xywh=x,y,w,h" — render that tile into your scrubber.

// Video.js (vtt-thumbnails plugin)
player.vttThumbnails({ src: thumbnails.sprite_vtt_url });

// 1. Inline mode — declared at upload time, runs alongside the main encode.
//    Add to the same `pipeline` block you pass to /v1/api/upload/initiate.
{
  bucket: 'video',
  key: 'videos/abc.mp4',
  file_size: 1234567,
  pipeline: {
    encode: true,
    aspect_variants: ['9:16'],          // ← new
    webhook_url: 'https://...',
    webhook_secret: process.env.WEBHOOK_SECRET,
  }
}

// 2. Inline mode via /v1/api/encoding/request (same root-level field).
{ object_key: fileId, aspect_variants: ['9:16'] }

// 3. Backfill mode — produce variants for a file that already has a complete
//    horizontal encode, WITHOUT re-running the main pass. Cheaper than force:true.
{ object_key: fileId, aspect_variants_only: ['9:16'] }
//
// Response: { status: 'queued', mode: 'aspect_variants_only',
//             parent_encoding_job_id: '...', child_encoding_job_ids: ['...'] }
//
// Mutually exclusive with force:true and with aspect_variants on the same call.

// aspect_variants block — same shape on webhook + both polling endpoints.
{
  "aspect_variants": {
    "9:16": {
      "hls_manifest_url": "https://cdn.zibnetwork.com/stream/<vertical_file_id>/master.m3u8",
      "poster_url":       "https://cdn.zibnetwork.com/objects/<vertical_poster_id>"
    }
  }
}

// Bitmovin — switch between horizontal and vertical based on viewport
const horizontal = encodingResult.hls_manifest_url;
const vertical   = encodingResult.aspect_variants?.['9:16']?.hls_manifest_url;
const verticalPoster = encodingResult.aspect_variants?.['9:16']?.poster_url;

player.load({
  hls: window.innerHeight > window.innerWidth ? (vertical || horizontal) : horizontal,
  poster: window.innerHeight > window.innerWidth
    ? (verticalPoster || encodingResult.thumbnails?.poster_url)
    : encodingResult.thumbnails?.poster_url,
});

// React Native / iOS-native — pick the vertical rendition directly for a portrait feed.
const shortsUrl = videoRow.aspect_variants?.['9:16']?.hls_manifest_url;
if (shortsUrl) {
  // Render a vertical scrolling feed using AVPlayer / ExoPlayer.
}

// app/api/zib-file-ready/route.ts (Next.js App Router style)

export async function POST(req: Request) {
  const event = await req.json();

  // 1. Verify the webhook signature (mandatory — see Webhooks).
  if (!verifyZibSignature(req.headers.get('x-zib-signature'), event)) {
    return new Response('invalid signature', { status: 401 });
  }

  if (event.event !== 'file.ready') {
    return Response.json({ received: true, ignored: true });
  }
  const { file_id, bucket, object_key } = event;

  // 2. Look up your local row by the STABLE identifier — (bucket, object_key).
  //
  //    Do NOT look up by file_id. A re-upload to the same key produces a
  //    NEW file_id, so the row you stored against the prior file_id will
  //    not match and your handler will silently no-op while the user's
  //    UI sits at "Queued — waiting for an encoder" forever.
  const creative = await db.creatives.findUnique({
    where: { bucket_object_key: { bucket, object_key } },
  });
  if (!creative) return Response.json({ received: true, matched: false });

  // 3. Idempotency keyed on file_id — NOT on encoding_status.
  //
  //    - If creative.zib_file_id === event.file_id and we already stored an
  //      encoding_id for it, this is a duplicate webhook delivery → skip.
  //    - If they differ, the user re-uploaded. The stored encoding belongs
  //      to the OLD file and is now cancelled by ZiB; we must fire a fresh
  //      encoding request for the NEW file_id.
  //
  //    A common bug — and the one that causes "Queued forever" deadlocks —
  //    is keying this check on `encoding_status !== 'ERROR'`. That returns
  //    "already handled" for every re-upload whose previous encode succeeded,
  //    so the new upload is never encoded. The user sees their re-upload
  //    "queued" indefinitely and ZiB never receives an encoding request.
  if (creative.zib_file_id === file_id && creative.zib_encoding_id) {
    return Response.json({ received: true, matched: true, deduped: true });
  }

  // 4. Fire encoding request. ZiB is also idempotent server-side — if
  //    another code path already fired for this file_id you'll receive
  //    status: 'already_queued' (in-flight job exists) or
  //    status: 'already_encoded' (completed job exists). Treat both the
  //    same — record the encoding_id and trust webhooks for the rest.
  const res = await fetch('https://api.zibnetwork.com/v1/api/encoding/request', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.ZIB_ACCESS_KEY}:${process.env.ZIB_SECRET_KEY}`,
    },
    body: JSON.stringify({
      object_key,                 // stable key — NOT file_id
      bucket,
      // webhook_url and webhook_secret are optional here — if you've
      // configured them once on your customer profile, ZiB uses those.
    }),
  });
  if (!res.ok) {
    return new Response(`ZiB encode request failed: ${res.status}`, { status: 502 });
  }
  const job = await res.json();

  // 5. Persist the new file_id AND the new encoding_id together. Writing
  //    file_id is the critical step that lets future webhook deliveries
  //    recognise this row as up to date — without it, the next file.ready
  //    for this key will look like another re-upload and you'll loop.
  await db.creatives.update({
    where: { id: creative.id },
    data: {
      zib_file_id:     file_id,                  // overwrite prior file_id
      zib_encoding_id: job.encoding_id,
      cdn_url:         job.cdn_url ?? job.hls_manifest_url ?? null,
      encoding_status:
        job.status === 'already_encoded' ? 'COMPLETE' : 'ENCODING',
    },
  });

  return Response.json({
    received: true,
    matched: true,
    encoding_id: job.encoding_id,
    status: job.status,
  });
}

// app/api/re-encode/route.ts

import { getServerSession } from '@/lib/auth';

export async function POST(req: Request) {
  // 1. Authentication. Refuse anonymous callers.
  const session = await getServerSession(req);
  if (!session?.user) {
    return new Response('unauthenticated', { status: 401 });
  }

  const { content_id, video_type } = await req.json();
  //    video_type: 'main' | 'trailer'

  // 2. Authorization. Caller must own this content (or be admin).
  const content = await db.content.findUnique({ where: { id: content_id } });
  if (!content) return new Response('not found', { status: 404 });
  if (content.owner_id !== session.user.id && !session.user.isAdmin) {
    return new Response('forbidden', { status: 403 });
  }

  const statusKey = `${video_type}_encoding_status`;
  const idKey     = `${video_type}_zib_encoding_id`;
  const fileKey   = `${video_type}_source_file_id`;

  // 3. Server-side dedup. Refuse if an encode is already in flight for
  //    this content+video_type. The UI lock isn't enough — page reload
  //    clears it, a second tab bypasses it, a scripted POST loop wouldn't
  //    even render the UI.
  if (['QUEUED', 'ENCODING'].includes(content[statusKey])) {
    return Response.json(
      { error: 'already_in_progress', encoding_id: content[idKey] },
      { status: 409 },
    );
  }

  // 4. Fire ZiB with force=true. The old encoded segments keep serving
  //    the CDN URL until the new encode completes, so playback isn't
  //    interrupted. Do NOT delete the prior encoded data first — that
  //    creates a window where the file has no playable output if the
  //    new encode never starts (e.g. ZiB returns an error). Let ZiB
  //    do the cutover atomically once segments land.
  const res = await fetch('https://api.zibnetwork.com/v1/api/encoding/request', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.ZIB_ACCESS_KEY}:${process.env.ZIB_SECRET_KEY}`,
    },
    body: JSON.stringify({
      object_key: content[fileKey],
      force: true,
    }),
  });
  if (!res.ok) {
    return new Response(`ZiB encode request failed: ${res.status}`, { status: 502 });
  }
  const job = await res.json();

  // 5. Record new encoding_id. The cdn_url field on your record does
  //    NOT change — the CDN URL is keyed by file_id, not encoding_id.
  await db.content.update({
    where: { id: content_id },
    data: {
      [idKey]: job.encoding_id,
      [statusKey]: 'ENCODING',
    },
  });

  return Response.json({
    encoding_id: job.encoding_id,
    status: job.status,
  });
}

<script src="https://app.zibnetwork.com/sdk/zib-sdk.js"></script>
<script>
  // Anywhere on a watch page, after the SDK script loads.
  // Idempotent — calling twice is harmless.
  ZiBStorage.startTelemetry();
</script>

// === bitmovin player (8.x — verified against 8.241.0) ===
// IMPORTANT: use SegmentRequestFinished, not SegmentPlayback.
//   - SegmentPlayback fires when a segment starts playing (no timing data)
//   - SegmentRequestFinished fires after download with downloadTime,
//     timeToFirstByte, size, success, httpStatus, url
//
// SegmentRequestFailed does NOT exist in 8.x — failures arrive on
// Finished with event.success === false. httpStatus === 0 means network
// error / CORS reject / abort.
//
// Time units: bitmovin's TypeScript type doc says seconds for downloadTime
// and timeToFirstByte. Multiply by 1000 to get ms. Verify against the DB
// once samples flow — if avg ttfb_ms ends up in the 50,000+ range, the
// runtime actually emitted ms and the multiplier should be removed.
player.on(bitmovin.player.PlayerEvent.SegmentRequestFinished, (event) => {
  // Clamp the -1 "cancelled before headers" sentinel.
  const ttfbSec = Math.max(0, event.timeToFirstByte || 0);
  ZiBStorage.recordFetch({
    url: event.url,
    ttfb_ms: Math.round(ttfbSec * 1000),
    total_ms: Math.round((event.downloadTime || 0) * 1000),
    size_bytes: event.size || 0,
    status: event.success === false
      ? (event.httpStatus === 0 ? 'network_error' : String(event.httpStatus))
      : (event.httpStatus ? String(event.httpStatus) : '200'),
  });
});

// === hls.js (any version) ===
hls.on(Hls.Events.FRAG_LOADED, (_, data) => {
  const stats = data.frag.stats || data.stats;  // hls.js v1 vs v0 paths
  ZiBStorage.recordFetch({
    url: data.frag.url,
    ttfb_ms: Math.round(stats.tfirst - stats.trequest),
    total_ms: Math.round(stats.tload - stats.trequest),
    size_bytes: stats.total,
    status: '200',
  });
});

// === shaka player ===
player.addEventListener('downloadcompleted', (event) => {
  ZiBStorage.recordFetch({
    url: event.request.uris[0],
    ttfb_ms: Math.round(event.response.headers['x-firstbyte-ms'] || event.response.timeMs),
    total_ms: Math.round(event.response.timeMs),
    size_bytes: event.response.data.byteLength,
    status: '200',
  });
});

// On player init, after the <video> element is in the DOM
const detach = ZiBStorage.attachToVideo(videoEl, { fileId: '<file-uuid>' });

// On player teardown
detach();

const zib = new ZiBStorage({
  accessKey: '...',
  secretKey: '...',
  telemetry: { enabled: true },   // <-- one extra option
});

// Optional — bring your own session ID if you already have one
// (e.g. tied to a playback session in your analytics).
new ZiBStorage({
  accessKey: '...',
  secretKey: '...',
  telemetry: { enabled: true, viewerSessionId: '...' },
});

// app/layout.tsx — Server Component is fine
import Script from 'next/script';
import { ZiBTelemetry } from '@/components/ZiBTelemetry';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {/* Loads on every page; next/script dedupes by src so it's safe to
            keep any per-page <Script> tags in upload flows that need a hard
            guarantee the SDK is present. */}
        <Script src="https://app.zibnetwork.com/sdk/zib-sdk.js" strategy="afterInteractive" />
        <ZiBTelemetry />
        {children}
      </body>
    </html>
  );
}

// components/ZiBTelemetry.tsx — small client wrapper
'use client';
import { useEffect } from 'react';

export function ZiBTelemetry() {
  useEffect(() => {
    let tele: { stop: () => void } | undefined;
    let cancelled = false;

    // Poll for the SDK global — handles the race where <Script
    // strategy="afterInteractive"> hasn't finished loading yet.
    const tick = () => {
      if (cancelled) return;
      // @ts-ignore — global injected by the SDK <script>
      const ZiBStorage = (window as any).ZiBStorage;
      if (ZiBStorage?.startTelemetry) {
        tele = ZiBStorage.startTelemetry();
        return;
      }
      setTimeout(tick, 100);
    };
    tick();

    return () => {
      cancelled = true;
      tele?.stop();   // fires final navigator.sendBeacon flush
    };
  }, []);

  return null;
}

Content-Type:    application/json
X-ZiB-Event:     <event name>            e.g. encoding.complete
X-ZiB-Job-ID:    <uuid>                  on encoding.* and {transcription,vision}.complete
X-ZiB-Signature: sha256=<hex>            HMAC-SHA256 over the raw request body

// file.ready — fired the moment shard count reaches the redundancy target
{
  "event":       "file.ready",
  "file_id":     "a1b2c3d4-...",
  "bucket":      "my-bucket",
  "object_key":  "videos/2026-04/film.mp4",
  "size_bytes":  524288000,
  "customer_id": "c0ffee...",
  "timestamp":   "2026-04-08T17:30:00.000Z"
}

// encoding.queued | encoding.started | encoding.sharding | encoding.complete | encoding.failed
// All five share the same shape — only the "event" and "status" fields change.
{
  "event":               "encoding.complete",
  "job_id":              "<encoding_jobs.id>",
  "status":              "complete",          // queued | encoding | sharding | complete | failed
  "file_id":             "a1b2c3d4-...",
  "customer_id":         "c0ffee...",
  "hls_manifest_url":    "https://cdn.zibnetwork.com/<file_id>/master.m3u8",  // null until "complete"
  "error_message":       null,                // populated on "failed"
  "transcription_model": "recommended",       // null if transcription not requested
  "vision_model":        "standard",          // null if vision not requested
  "thumbnails": {                              // null if tenant opted out; see "Thumbnails" above
    "poster_url":     "https://cdn.zibnetwork.com/objects/<poster_file_id>",
    "sprite_url":     "https://cdn.zibnetwork.com/objects/<first_sprite_sheet_file_id>",
    "sprite_vtt_url": "https://cdn.zibnetwork.com/objects/<sprite_vtt_file_id>"
  },
  "aspect_variants": {                         // omitted if tenant didn't opt in; see "Aspect variants" above
    "9:16": {
      "hls_manifest_url": "https://cdn.zibnetwork.com/stream/<vertical_file_id>/master.m3u8",
      "poster_url":       "https://cdn.zibnetwork.com/objects/<vertical_poster_id>"
    }
  },
  "timestamp":           "2026-04-08T17:32:14.000Z"
}

// encoding.progress — throttled mid-encode update
// Fires periodically while encoding is running so your UI can render a real
// progress bar instead of sitting at 0% from encoding.started until
// encoding.complete. Throttle policy: at most every 10s OR every 5% delta,
// whichever comes first. Idempotent — replays of the same percent are safe.
//
// You don't need this event to know the job will eventually finish — the
// existing encoding.complete event still fires. encoding.progress is purely
// for UI feedback.
{
  "event":     "encoding.progress",
  "job_id":    "<encoding_jobs.id>",
  "file_id":   "a1b2c3d4-...",
  "progress":  47,                 // integer 0–100
  "stage":     "encoding",         // "encoding" | "sharding"
  "timestamp": "2026-04-08T17:31:08.000Z"
}

// transcription.complete — fires when the SRT/WebVTT artefact has been
// produced and stored. Fetch via https://cdn.zibnetwork.com/objects/<srt_file_id>
{
  "event":        "transcription.complete",
  "job_id":       "<encoding_jobs.id OR compute_jobs.id>",
  "file_id":      "a1b2c3d4-...",
  "srt_file_id":  "f00d...",
  "timestamp":    "2026-04-08T17:34:02.000Z"
}

// vision.complete — fires when the ZibSidecar JSON has been produced and
// stored. Fetch via https://cdn.zibnetwork.com/objects/<sidecar_file_id>
// and parse as JSON for the full sidecar (scenes, IAB categories, etc.).
{
  "event":            "vision.complete",
  "job_id":           "<encoding_jobs.id OR compute_jobs.id>",
  "file_id":          "a1b2c3d4-...",
  "sidecar_file_id":  "ba11...",
  "timestamp":        "2026-04-08T17:36:48.000Z"
}

import crypto from 'crypto';

export async function POST(req) {
  // Read raw body before JSON parsing — signature is over raw bytes
  const body = await req.text();
  const sig = req.headers.get('x-zib-signature'); // "sha256=<hex>"

  const expected =
    'sha256=' +
    crypto
      .createHmac('sha256', process.env.ZIB_WEBHOOK_SECRET)
      .update(body)
      .digest('hex');

  if (sig !== expected) {
    return new Response('Unauthorized', { status: 401 });
  }

  const payload = JSON.parse(body);

  if (payload.event === 'file.ready') {
    // update your DB with cdn_url, mark upload complete, etc.
  }

  if (payload.event === 'encoding.complete') {
    // store hls_manifest_url, notify your users, etc.
  }

  return new Response('OK');
}

# Form A — by file_id (preferred)
curl -X DELETE \
  -H "Authorization: Bearer $ZIB_ACCESS_KEY:$ZIB_SECRET_KEY" \
  https://api.zibnetwork.com/v1/api/file/01846192-315c-4f0a-b766-12b18a26b209

# Form B — by bucket + object_key (S3-shaped)
curl -X DELETE \
  -H "Authorization: Bearer $ZIB_ACCESS_KEY:$ZIB_SECRET_KEY" \
  https://api.zibnetwork.com/v1/api/storage/posters/abc123/poster.card.webp

{
  "success": true,
  "file_id": "01846192-315c-4f0a-b766-12b18a26b209",
  "bucket": "posters",
  "key": "abc123/poster.card.webp",
  "deleted": {
    "video_segments": 0,
    "encoding_jobs": 0,
    "shards": 12,
    "s3_objects": 1,
    "files": 1
  },
  "node_cleanup": {
    "ok": 12,
    "failed": 0,
    "queued_for_offline": 4
  },
  "encoding_jobs_cancelled": 0
}

// Repeat call after the file is gone
{
  "success": true,
  "already_deleted": true,
  "file_id": "01846192-315c-4f0a-b766-12b18a26b209"
}

{
  "event": "file.deleted",
  "file_id": "01846192-315c-4f0a-b766-12b18a26b209",
  "bucket": "posters",
  "key": "abc123/poster.card.webp",
  "timestamp": "2026-05-14T03:21:09.482Z"
}

// app/api/content/[id]/delete/route.ts
import { NextResponse } from 'next/server';

export async function DELETE(req: Request, { params }: { params: { id: string } }) {
  const content = await db.content.findUnique({ where: { id: params.id } });
  if (!content) return NextResponse.json({ ok: true }, { status: 200 });

  // 1. Collect every ZiB file_id this row references.
  const fileIds = [
    content.video_file_id,
    content.poster_thumb_id,
    content.poster_card_id,
    content.poster_hero_id,
  ].filter(Boolean);

  // 2. Delete from ZiB in parallel — the endpoint is idempotent so retries are safe.
  await Promise.all(
    fileIds.map((id) =>
      fetch(`https://api.zibnetwork.com/v1/api/file/${id}`, {
        method: 'DELETE',
        headers: { Authorization: `Bearer ${process.env.ZIB_ACCESS_KEY}:${process.env.ZIB_SECRET_KEY}` },
      }).catch((e) => console.warn(`ZiB delete failed for ${id}`, e))
    )
  );

  // 3. Delete the local row last — if step 2 partially fails, your DB still
  //    holds the file_ids so a cleanup job can retry.
  await db.content.delete({ where: { id: params.id } });
  return NextResponse.json({ ok: true });
}

async function replacePoster(contentId: string, newFile: File) {
  // 1. Upload the new poster to the same object_key. ZiB detects the
  //    existing row at (bucket, object_key), cancels any in-flight
  //    encoding on the prior file_id, fires file.failed for it, and
  //    evicts the prior bytes from every holding node in the background.
  const init = await fetch('/api/posters/upload-initiate', { method: 'POST', body: JSON.stringify({ contentId }) });
  const registration = await init.json();
  const { file_id: newFileId } = await ZiBStorage.uploadDirect(newFile, registration);

  // 2. Write the new file_id to your row. The supersede flow has already
  //    taken care of evicting the prior bytes — no follow-up DELETE needed.
  await db.content.update({ where: { id: contentId }, data: { poster_card_id: newFileId } });
}

curl -s https://api.zibnetwork.com/v1/api/my-jobs \
  -H "Authorization: Bearer ${ACCESS_KEY}:${SECRET_KEY}"

# Filter:
curl -s "https://api.zibnetwork.com/v1/api/my-jobs?status=all" \
  -H "Authorization: Bearer ${ACCESS_KEY}:${SECRET_KEY}"

{
  "jobs": [
    {
      "file_id": "0c8e3765-9b2b-4a29-82cb-2f1911fe750c",
      "title": "trailer-final.mp4",
      "phase": "replicating",
      "phase_progress_pct": 66.7,
      "phase_detail": "peer 2 of 3 verified",
      "phase_updated_at": "2026-04-24T05:12:04Z",
      "replication_peer_count": 2,
      "replication_target_count": 3,
      "replication_safe_at": null,
      "retry_count": 0,
      "last_error": null,
      "cancellable": true,
      "retriable": false,
      "created_at": "2026-04-24T04:58:12Z",
      "node_id": "ZB-899233"
    }
  ]
}

curl -X DELETE https://api.zibnetwork.com/v1/api/my-jobs/${FILE_ID} \
  -H "Authorization: Bearer ${ACCESS_KEY}:${SECRET_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"reason":"user_abandoned_upload"}'

curl -X POST https://api.zibnetwork.com/v1/api/my-jobs/${FILE_ID}/retry \
  -H "Authorization: Bearer ${ACCESS_KEY}:${SECRET_KEY}"

const { encoding_id } = await zib.startEncoding(fileId, {
  transcription: 'recommended',  // 'fastest' | 'recommended' | 'accurate'
  vision: 'standard'             // 'standard' | 'hq'
});

// Poll until complete
const status = await zib.getEncodingStatus(encoding_id);
// status.srt_file_id    → WebVTT file (auto-injected into HLS manifest)
// status.sidecar_file_id → ZibSidecar JSON

// Standalone transcription
const { job_id } = await zib.submitTranscription(fileId, 'recommended');

// Standalone vision AI
const { job_id } = await zib.submitVisionAI(fileId, 'standard');

// Poll job status
const result = await zib.getComputeStatus(job_id);
// result.status          → 'queued' | 'processing' | 'complete' | 'failed'
// result.srt_file_id     → WebVTT file ID (when complete)
// result.sidecar_file_id → ZibSidecar file ID (when complete)

// Get the sidecar CDN URL from job status
const status = await zib.getComputeStatus(job_id);
const sidecarUrl = zib.getCdnUrl(status.sidecar_file_id);

// Fetch and parse
const sidecar = await fetch(sidecarUrl).then(r => r.json());

// Key fields:
sidecar.scene_understanding.executive_summary        // 150-200 word summary
sidecar.content_classification.garm.brand_safety_score  // 0.0–1.0
sidecar.clip_suggestions[0].virality_score           // 0.0–1.0
sidecar.chapters_youtube_format                      // paste into YouTube description
sidecar.transcript.full_text                         // full transcript string
sidecar.transcript.segments[0].intent               // hook / payoff / cta / ...
sidecar.content_classification.iab_categories[0].name  // IAB 3.0 taxonomy