@puppetry.com/sdk 0.1.0

package/dist/chunk-IP47SEN7.mjs

@@ -0,0 +1,1638 @@
+import {
+  PuppetryAuthError,
+  PuppetryError,
+  PuppetryNetworkError,
+  PuppetryRateLimitError,
+  PuppetryTimeoutError,
+  puppetryErrorData
+} from "./chunk-QK5VPBL7.mjs";
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://www.puppetry.com/api/v1";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 2;
+var DEFAULT_RETRY_DELAY_MS = 500;
+var SDK_VERSION = "0.1.0";
+var IDEMPOTENCY_KEY_MAX_LENGTH = 200;
+var EMPTY_HEADERS = { get: () => null };
+var VIDEO_STATUS_ALIASES = {
+  active: "processing",
+  complete: "completed",
+  completed: "completed",
+  delayed: "queued",
+  done: "completed",
+  error: "failed",
+  errored: "failed",
+  failed: "failed",
+  failure: "failed",
+  finished: "completed",
+  "in-progress": "processing",
+  in_progress: "processing",
+  paused: "queued",
+  prioritized: "queued",
+  process: "processing",
+  processing: "processing",
+  queued: "queued",
+  rendering: "processing",
+  retrying: "processing",
+  running: "processing",
+  started: "processing",
+  success: "completed",
+  succeeded: "completed",
+  wait: "queued",
+  waiting: "queued",
+  "waiting-children": "queued"
+};
+function normalizeVideoStatusAlias(status) {
+  if (typeof status !== "string") return void 0;
+  return VIDEO_STATUS_ALIASES[status.trim().toLowerCase()];
+}
+function normalizeVideoJobSource(source) {
+  return source === "text" || source === "audio" ? source : void 0;
+}
+var Puppetry = class {
+  constructor(config) {
+    // ── Videos ─────────────────────────────────────────────────────────
+    /**
+     * Create a video from text (text-to-speech + lip sync).
+     *
+     * @example
+     * ```ts
+     * const job = await puppetry.videos.createFromText({
+     *   text: "Hello, world!",
+     *   image_url: "https://example.com/photo.jpg",
+     *   voice_id: "puppetry-af_heart",
+     * });
+     * ```
+     */
+    this.videos = {
+      createFromText: async (params) => this.requestWithResponse(
+        "POST",
+        "/videos/text",
+        this.textVideoBody(params),
+        {
+          idempotencyKey: this.idempotencyKeyFromParams(params)
+        }
+      ).then(({ data, headers }) => this.normalizeVideoJob(data, headers)),
+      createFromAudio: async (params) => this.requestWithResponse(
+        "POST",
+        "/videos/audio",
+        this.audioVideoBody(params),
+        {
+          idempotencyKey: this.idempotencyKeyFromParams(params)
+        }
+      ).then(({ data, headers }) => this.normalizeVideoJob(data, headers)),
+      get: async (jobId) => this.getWithResponse(this.videoJobPath(jobId)).then(
+        ({ data, headers }) => this.normalizeVideoJob(data, headers)
+      ),
+      /**
+       * Return the current Developer API video readiness contract.
+       *
+       * Use this before reserving uploads or queueing a video when an agent needs
+       * to fail fast on credits or active slot limits.
+       */
+      getReadiness: () => this.getVideoGenerationReadiness(),
+      /**
+       * Assert that this API key can create a video right now.
+       *
+       * Throws PuppetryRateLimitError with retryAfter for active-slot blockers,
+       * and PuppetryError(402) for credit blockers.
+       */
+      ensureReady: () => this.ensureVideoGenerationReady(),
+      /**
+       * Wait for a video job to complete, polling at the given interval.
+       *
+       * @param jobId - The job ID to watch
+       * @param options.intervalMs - Polling interval (default: 2000)
+       * @param options.timeoutMs - Max wait time (default: 300000 = 5 min)
+       * @returns The completed VideoJob
+       * @throws PuppetryTimeoutError if the job doesn't complete in time
+       */
+      waitForCompletion: async (jobId, options) => {
+        const interval = options?.intervalMs ?? 2e3;
+        const timeout = options?.timeoutMs ?? 3e5;
+        const deadline = Date.now() + timeout;
+        const initialDelayMs = this.optionDelayMs(options?.initialDelayMs);
+        let currentJobId = jobId;
+        if (initialDelayMs !== void 0 && initialDelayMs > 0) {
+          await this.sleepWithinDeadline(initialDelayMs, deadline);
+        }
+        while (Date.now() < deadline) {
+          try {
+            const { data: job, headers } = await this.getWithResponse(
+              this.videoJobPath(currentJobId)
+            );
+            const normalizedJob = this.normalizeVideoJob(job, headers);
+            currentJobId = this.videoJobIdFromStatusUrl(
+              normalizedJob.statusUrl ?? normalizedJob.status_url
+            ) ?? normalizedJob.id;
+            await options?.onPoll?.(normalizedJob);
+            if (normalizedJob.status === "completed" || normalizedJob.status === "failed") {
+              return normalizedJob;
+            }
+            const delayMs = this.pollingDelayMs(normalizedJob, headers, interval);
+            await this.sleep(
+              Math.min(delayMs, Math.max(deadline - Date.now(), 0))
+            );
+          } catch (err) {
+            if (!(err instanceof PuppetryError)) throw err;
+            const delayMs = this.retryableStatusErrorDelayMs(err, interval);
+            if (delayMs === void 0) throw err;
+            const retryingEvent = this.videoRetryingEvent(err, currentJobId);
+            currentJobId = retryingEvent.jobId;
+            await options?.onRetrying?.(retryingEvent);
+            await this.sleepWithinDeadline(delayMs, deadline);
+          }
+        }
+        throw new PuppetryTimeoutError(timeout);
+      },
+      /**
+       * Stream progress-like events by polling the live v1 job status endpoint.
+       *
+       * @param jobId - The job ID to stream
+       * @param options.intervalMs - Polling interval (default: 2000)
+       * @param options.timeoutMs - Max stream time (default: 300000 = 5 min)
+       * @returns AsyncGenerator yielding VideoEvent objects
+       *
+       * @example
+       * ```ts
+       * for await (const event of puppetry.videos.stream("job-123")) {
+       *   console.log(`${event.type}: ${event.progress}%`);
+       *   if (event.type === "completed") break;
+       * }
+       * ```
+       */
+      stream: (jobId, options) => this.streamPolledVideoEvents(jobId, options)
+    };
+    // ── Jobs ───────────────────────────────────────────────────────────
+    this.jobs = {
+      /**
+       * Fetch a generated video job by ID.
+       *
+       * This is an alias for `videos.get()` because Puppetry's public v1 API
+       * exposes generated video job state under `/videos/{jobId}`.
+       */
+      get: (jobId) => this.videos.get(jobId),
+      /**
+       * Wait for a generated video job to complete, polling at the given interval.
+       */
+      waitForCompletion: (jobId, options) => this.videos.waitForCompletion(jobId, options)
+    };
+    // ── Voices ─────────────────────────────────────────────────────────
+    this.voices = {
+      list: (params) => {
+        const query = new URLSearchParams();
+        if (params?.language) query.set("language", params.language);
+        if (params?.gender) query.set("gender", params.gender);
+        if (params?.cursor) query.set("cursor", params.cursor);
+        if (params?.limit) query.set("limit", String(params.limit));
+        const qs = query.toString();
+        return this.get(`/voices${qs ? "?" + qs : ""}`);
+      },
+      listPuppetry: () => this.get("/voices/puppetry")
+    };
+    // ── Text to Speech ───────────────────────────────────────────────────
+    this.tts = {
+      createPuppetry: (params) => this.post(
+        "/tts/puppetry",
+        params
+      )
+    };
+    // ── Uploads ───────────────────────────────────────────────────────────
+    this.uploads = {
+      /**
+       * Create a signed PUT URL for hosting audio that can be used by Puppetry API
+       * workflows.
+       */
+      createAudioUrl: async (params) => this.post(
+        "/uploads/audio-url",
+        this.compactBody({
+          mime_type: this.resolveUploadStringAliases([
+            { name: "mime_type", value: params.mime_type },
+            { name: "mimeType", value: params.mimeType },
+            { name: "contentType", value: params.contentType }
+          ]),
+          content_length: this.resolveNumberAliases([
+            { name: "content_length", value: params.content_length },
+            { name: "contentLength", value: params.contentLength },
+            { name: "sizeBytes", value: params.sizeBytes },
+            { name: "file_size", value: params.file_size },
+            { name: "fileSize", value: params.fileSize }
+          ]),
+          require_video_readiness: params.require_video_readiness ?? params.requireVideoReadiness
+        }),
+        { idempotencyKey: this.idempotencyKeyFromParams(params) }
+      ).then((upload) => this.normalizeAudioUpload(upload)),
+      /**
+       * Create a signed audio upload URL and PUT the provided bytes to it.
+       *
+       * The returned `read_url` can be passed to `videos.createFromAudio()`.
+       */
+      uploadAudio: async (params) => {
+        const upload = await this.uploads.createAudioUrl(params);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+          const res = await this.fetchFn(upload.upload_url, {
+            method: upload.method,
+            headers: upload.headers,
+            body: params.body,
+            signal: controller.signal
+          });
+          if (!res.ok) {
+            throw new PuppetryError(
+              res.status,
+              "upload_failed",
+              res.statusText || "Failed to upload audio bytes"
+            );
+          }
+        } catch (err) {
+          if (err instanceof PuppetryError) throw err;
+          if (this.isAbortError(err)) {
+            throw new PuppetryTimeoutError(this.timeout);
+          }
+          if (this.isNetworkError(err)) {
+            throw new PuppetryNetworkError(this.transportErrorMessage(err));
+          }
+          throw err;
+        } finally {
+          clearTimeout(timer);
+        }
+        return this.normalizeAudioUpload(upload);
+      }
+    };
+    // ── Puppets ────────────────────────────────────────────────────────
+    this.puppets = {
+      list: (params) => {
+        const query = new URLSearchParams();
+        if (params?.cursor) query.set("cursor", params.cursor);
+        if (params?.limit) query.set("limit", String(params.limit));
+        const qs = query.toString();
+        return this.get(
+          `/puppets${qs ? "?" + qs : ""}`
+        );
+      },
+      create: (params) => this.post(
+        "/puppets",
+        params
+      ),
+      delete: (puppetId) => this.delete(`/puppets/${encodeURIComponent(puppetId)}`)
+    };
+    // ── Usage ──────────────────────────────────────────────────────────
+    this.usage = {
+      get: async () => this.normalizeUsage(await this.get("/usage"))
+    };
+    // ── Quota ──────────────────────────────────────────────────────────
+    this.quota = {
+      get: () => this.usage.get()
+    };
+    const apiKey = config.apiKey.trim();
+    if (!apiKey) {
+      throw new PuppetryAuthError("apiKey is required");
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeout = config.timeout || DEFAULT_TIMEOUT;
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.retryDelayMs = config.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+    this.onRetry = config.onRetry;
+    this.fetchFn = config.fetch || globalThis.fetch;
+  }
+  // ── HTTP Layer ─────────────────────────────────────────────────────
+  async requestWithResponse(method, path, body, options) {
+    const url = `${this.baseUrl}${path}`;
+    const requestBody = body ? JSON.stringify(body) : void 0;
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      "User-Agent": `@puppetry.com/sdk/${SDK_VERSION}`
+    };
+    const idempotencyKey = this.normalizeIdempotencyKey(
+      options?.idempotencyKey
+    );
+    if (idempotencyKey) {
+      headers["Idempotency-Key"] = idempotencyKey;
+    }
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const res = await this.fetchFn(url, {
+          method,
+          headers,
+          body: requestBody,
+          signal: controller.signal
+        });
+        if (!res.ok) {
+          const errorBody = await res.json().catch(() => ({
+            error: "unknown",
+            message: res.statusText
+          }));
+          const responseHeaders = this.responseHeaders(res);
+          const retryAfter = this.responseRetryAfter(res.headers, errorBody);
+          const errorOptions = {
+            ...this.videoCreditErrorOptions(responseHeaders),
+            ...this.videoStatusErrorOptions(
+              method,
+              path,
+              responseHeaders,
+              retryAfter
+            )
+          };
+          const isVideoStatusRetry = this.isRetryableVideoStatusError(
+            method,
+            path,
+            errorBody
+          );
+          if (!isVideoStatusRetry && this.shouldRetry(method, res.status, Boolean(idempotencyKey)) && attempt < this.maxRetries) {
+            const delayMs = this.retryDelay(attempt, retryAfter);
+            const retryError = res.status === 429 ? PuppetryRateLimitError.fromRateLimitResponse(errorBody, {
+              ...errorOptions
+            }) : PuppetryError.fromResponse(
+              res.status,
+              errorBody,
+              errorOptions
+            );
+            await this.notifyRetry(
+              this.requestRetryEvent(
+                method,
+                path,
+                url,
+                idempotencyKey,
+                attempt,
+                delayMs,
+                retryError
+              )
+            );
+            await this.sleep(delayMs);
+            continue;
+          }
+          if (res.status === 401)
+            throw new PuppetryAuthError(errorBody.message);
+          if (res.status === 429) {
+            throw PuppetryRateLimitError.fromRateLimitResponse(errorBody, {
+              ...errorOptions
+            });
+          }
+          throw PuppetryError.fromResponse(res.status, errorBody, errorOptions);
+        }
+        if (res.status === 204) {
+          return { data: void 0, headers: this.responseHeaders(res) };
+        }
+        return {
+          data: await res.json(),
+          headers: this.responseHeaders(res)
+        };
+      } catch (err) {
+        if (err instanceof PuppetryError) throw err;
+        if (this.isAbortError(err)) {
+          if (this.shouldRetryTransport(method, Boolean(idempotencyKey), attempt)) {
+            const delayMs = this.retryDelay(attempt);
+            await this.notifyRetry(
+              this.requestRetryEvent(
+                method,
+                path,
+                url,
+                idempotencyKey,
+                attempt,
+                delayMs,
+                new PuppetryTimeoutError(this.timeout)
+              )
+            );
+            await this.sleep(delayMs);
+            continue;
+          }
+          throw new PuppetryTimeoutError(this.timeout);
+        }
+        if (this.isNetworkError(err)) {
+          if (this.shouldRetryTransport(method, Boolean(idempotencyKey), attempt)) {
+            const delayMs = this.retryDelay(attempt);
+            await this.notifyRetry(
+              this.requestRetryEvent(
+                method,
+                path,
+                url,
+                idempotencyKey,
+                attempt,
+                delayMs,
+                new PuppetryNetworkError(this.transportErrorMessage(err))
+              )
+            );
+            await this.sleep(delayMs);
+            continue;
+          }
+          throw new PuppetryNetworkError(this.transportErrorMessage(err));
+        }
+        throw err;
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    throw new PuppetryError(
+      500,
+      "retry_exhausted",
+      "Request retries exhausted"
+    );
+  }
+  requestRetryEvent(method, path, url, idempotencyKey, attempt, delayMs, err) {
+    return {
+      method,
+      path,
+      url,
+      ...idempotencyKey ? {
+        idempotency_key: idempotencyKey,
+        idempotencyKey
+      } : {},
+      attempt: attempt + 1,
+      maxRetries: this.maxRetries,
+      delayMs,
+      ...puppetryErrorData(err)
+    };
+  }
+  async notifyRetry(event) {
+    if (!this.onRetry) return;
+    try {
+      await this.onRetry(event);
+    } catch {
+    }
+  }
+  async request(method, path, body, options) {
+    return (await this.requestWithResponse(method, path, body, options)).data;
+  }
+  get(path) {
+    return this.request("GET", path);
+  }
+  getWithResponse(path) {
+    return this.requestWithResponse("GET", path);
+  }
+  post(path, body, options) {
+    return this.request("POST", path, body, options);
+  }
+  delete(path) {
+    return this.request("DELETE", path);
+  }
+  shouldRetry(method, status, hasIdempotencyKey) {
+    if (status !== 429 && status < 500) return false;
+    return this.isRetrySafeRequest(method, hasIdempotencyKey);
+  }
+  isRetryableVideoStatusError(method, path, body) {
+    if (!this.isVideoStatusRequest(method, path)) return false;
+    return body.retryable === true || body.details?.retryable === true;
+  }
+  isVideoStatusRequest(method, path) {
+    if (method.toUpperCase() !== "GET") return false;
+    const pathname = path.split("?")[0];
+    return /^\/videos\/[^/]+\/?$/.test(pathname);
+  }
+  shouldRetryTransport(method, hasIdempotencyKey, attempt) {
+    return attempt < this.maxRetries && this.isRetrySafeRequest(method, hasIdempotencyKey);
+  }
+  isRetrySafeRequest(method, hasIdempotencyKey) {
+    const normalizedMethod = method.toUpperCase();
+    if (normalizedMethod === "GET" || normalizedMethod === "HEAD" || normalizedMethod === "OPTIONS") {
+      return true;
+    }
+    return hasIdempotencyKey;
+  }
+  isAbortError(err) {
+    return typeof err === "object" && err !== null && "name" in err && err.name === "AbortError";
+  }
+  isNetworkError(err) {
+    return err instanceof TypeError;
+  }
+  transportErrorMessage(err) {
+    if (err instanceof Error && err.message) return err.message;
+    return "Network request failed";
+  }
+  parseRetryAfter(value) {
+    if (!value) return void 0;
+    const trimmedValue = value.trim();
+    if (/^\d+$/.test(trimmedValue)) {
+      const seconds = Number(trimmedValue);
+      return Number.isSafeInteger(seconds) ? seconds : void 0;
+    }
+    const retryAtMs = Date.parse(trimmedValue);
+    if (!Number.isFinite(retryAtMs)) return void 0;
+    return Math.max(0, Math.ceil((retryAtMs - Date.now()) / 1e3));
+  }
+  responseRetryAfter(headers, body) {
+    return this.parseRetryAfter(this.readHeader(headers, "Retry-After")) ?? this.retryAfterFromErrorBody(body) ?? this.retryAfterFromDetails(body.details);
+  }
+  retryAfterFromErrorBody(body) {
+    return this.normalizeRetryAfterSeconds(
+      body.retry_after_seconds ?? body.retryAfterSeconds ?? body.retryAfter
+    );
+  }
+  retryAfterFromDetails(details) {
+    const directRetryAfter = this.normalizeRetryAfterSeconds(
+      details?.retry_after_seconds ?? details?.retryAfterSeconds ?? details?.retryAfter
+    );
+    if (directRetryAfter !== void 0) return directRetryAfter;
+    const nestedReadiness = details && typeof details === "object" ? details.video_generation ?? details.videoGeneration : void 0;
+    if (!nestedReadiness || typeof nestedReadiness !== "object") {
+      return void 0;
+    }
+    const readiness = nestedReadiness;
+    return this.normalizeRetryAfterSeconds(
+      readiness.retry_after_seconds ?? readiness.retryAfterSeconds ?? readiness.retryAfter
+    );
+  }
+  normalizeRetryAfterSeconds(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+      return void 0;
+    }
+    return value;
+  }
+  retryDelay(attempt, retryAfterSeconds) {
+    if (retryAfterSeconds !== void 0) {
+      return retryAfterSeconds * 1e3;
+    }
+    return this.retryDelayMs * 2 ** attempt;
+  }
+  sleep(ms) {
+    if (ms <= 0) return Promise.resolve();
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  responseHeaders(response) {
+    return response.headers ?? EMPTY_HEADERS;
+  }
+  readHeader(headers, name) {
+    const reader = headers;
+    return reader?.get?.(name) ?? reader?.get?.(name.toLowerCase()) ?? null;
+  }
+  readResponseHeader(headers, name) {
+    return headers?.get?.(name) ?? headers?.get?.(name.toLowerCase()) ?? null;
+  }
+  compactBody(body) {
+    return Object.fromEntries(
+      Object.entries(body).filter(([, value]) => value !== void 0)
+    );
+  }
+  normalizeIdempotencyKey(value) {
+    if (value === void 0) return void 0;
+    const key = value.trim();
+    if (!key) {
+      throw new PuppetryError(
+        400,
+        "invalid_request",
+        "Idempotency-Key must not be blank"
+      );
+    }
+    if (key.length > IDEMPOTENCY_KEY_MAX_LENGTH) {
+      throw new PuppetryError(
+        400,
+        "invalid_request",
+        `Idempotency-Key must be ${IDEMPOTENCY_KEY_MAX_LENGTH} characters or fewer`
+      );
+    }
+    return key;
+  }
+  idempotencyKeyFromParams(params) {
+    const aliases = [
+      { name: "idempotencyKey", value: params.idempotencyKey },
+      { name: "idempotency_key", value: params.idempotency_key }
+    ];
+    const provided = aliases.filter((alias) => alias.value !== void 0 && alias.value !== null).map((alias) => {
+      if (typeof alias.value !== "string") {
+        throw new PuppetryError(
+          400,
+          "invalid_request",
+          `${alias.name} must be a string`
+        );
+      }
+      return { ...alias, value: alias.value };
+    });
+    const first = provided[0];
+    if (!first) return void 0;
+    const conflictingAlias = provided.find(
+      (alias) => alias.value !== first.value
+    );
+    if (conflictingAlias) {
+      throw new PuppetryError(
+        400,
+        "invalid_request",
+        `Pass one of ${aliases.map((alias) => alias.name).join(", ")}, not conflicting values`
+      );
+    }
+    return first.value;
+  }
+  resolveAlias(preferred, alias, preferredName, aliasName) {
+    if (preferred && alias && preferred !== alias) {
+      throw new PuppetryError(
+        400,
+        "invalid_request",
+        `Pass either ${preferredName} or ${aliasName}, not conflicting values`
+      );
+    }
+    return preferred ?? alias;
+  }
+  resolveRequiredStringAliases(aliases) {
+    const provided = aliases.flatMap((alias) => {
+      if (alias.value === void 0 || alias.value === null) return [];
+      if (typeof alias.value !== "string") {
+        throw new PuppetryError(
+          400,
+          "invalid_request",
+          `${alias.name} must be a string`
+        );
+      }
+      const value = alias.value.trim();
+      if (!value) {
+        throw new PuppetryError(
+          400,
+          "invalid_request",
+          `${alias.name} must not be blank`
+        );
+      }
+      return [{ name: alias.name, value }];
+    });
+    const first = provided[0];
+    if (!first) return void 0;
+    const conflictingAlias = provided.find(
+      (alias) => alias.value !== first.value
+    );
+    if (conflictingAlias) {
+      throw new PuppetryError(
+        400,
+        "invalid_request",
+        `Pass one of ${aliases.map((alias) => alias.name).join(", ")}, not conflicting values`
+      );
+    }
+    return first.value;
+  }
+  resolveOptionalStringAliases(aliases) {
+    const provided = aliases.flatMap((alias) => {
+      if (alias.value === void 0 || alias.value === null) return [];
+      if (typeof alias.value !== "string") {
+        throw new PuppetryError(
+          400,
+          "invalid_request",
+          `${alias.name} must be a string`
+        );
+      }
+      const value = alias.value.trim();
+      return value ? [{ name: alias.name, value }] : [];
+    });
+    const first = provided[0];
+    if (!first) return void 0;
+    const conflictingAlias = provided.find(
+      (alias) => alias.value !== first.value
+    );
+    if (conflictingAlias) {
+      throw new PuppetryError(
+        400,
+        "invalid_request",
+        `Pass one of ${aliases.map((alias) => alias.name).join(", ")}, not conflicting values`
+      );
+    }
+    return first.value;
+  }
+  resolveUploadStringAliases(aliases) {
+    const provided = aliases.flatMap((alias) => {
+      if (alias.value === void 0 || alias.value === null) return [];
+      if (typeof alias.value !== "string") {
+        throw new PuppetryError(
+          400,
+          "invalid_request",
+          `${alias.name} must be a string`
+        );
+      }
+      const value = alias.value.trim();
+      return value ? [{ name: alias.name, value }] : [];
+    });
+    const first = provided[0];
+    if (!first) return void 0;
+    const conflictingAlias = provided.find(
+      (alias) => alias.value !== first.value
+    );
+    if (conflictingAlias) {
+      throw new PuppetryError(
+        400,
+        "invalid_request",
+        `Pass one of ${aliases.map((alias) => alias.name).join(", ")}, not conflicting values`
+      );
+    }
+    return first.value;
+  }
+  resolveNumberAliases(aliases) {
+    const provided = aliases.flatMap((alias) => {
+      if (alias.value === void 0 || alias.value === null) return [];
+      if (typeof alias.value === "string" && alias.value.trim() === "") {
+        return [];
+      }
+      if (typeof alias.value !== "number") {
+        throw new PuppetryError(
+          400,
+          "invalid_request",
+          `${alias.name} must be a number`
+        );
+      }
+      return [{ name: alias.name, value: alias.value }];
+    });
+    const first = provided[0];
+    if (!first) return void 0;
+    const conflictingAlias = provided.find(
+      (alias) => alias.value !== first.value
+    );
+    if (conflictingAlias) {
+      throw new PuppetryError(
+        400,
+        "invalid_request",
+        `Pass one of ${aliases.map((alias) => alias.name).join(", ")}, not conflicting values`
+      );
+    }
+    return first.value;
+  }
+  firstDefinedNullable(...values) {
+    for (const value of values) {
+      if (value !== void 0 && value !== null) return value;
+    }
+    return values.some((value) => value === null) ? null : void 0;
+  }
+  textVideoBody(params) {
+    return this.compactBody({
+      image_url: this.resolveRequiredStringAliases([
+        { name: "image_url", value: params.image_url },
+        { name: "imageUrl", value: params.imageUrl },
+        { name: "image", value: params.image },
+        { name: "portrait", value: params.portrait },
+        { name: "portrait_url", value: params.portrait_url },
+        { name: "portraitUrl", value: params.portraitUrl },
+        { name: "avatar", value: params.avatar },
+        { name: "avatarUrl", value: params.avatarUrl },
+        { name: "avatar_url", value: params.avatar_url },
+        { name: "photo", value: params.photo },
+        { name: "photoUrl", value: params.photoUrl },
+        { name: "photo_url", value: params.photo_url }
+      ]),
+      text: this.resolveRequiredStringAliases([
+        { name: "text", value: params.text },
+        { name: "script", value: params.script },
+        { name: "prompt", value: params.prompt }
+      ]),
+      voice_id: this.resolveOptionalStringAliases([
+        { name: "voice_id", value: params.voice_id },
+        { name: "voiceId", value: params.voiceId },
+        { name: "voice", value: params.voice }
+      ]),
+      language: params.language,
+      expressiveness: params.expressiveness
+    });
+  }
+  audioVideoBody(params) {
+    return this.compactBody({
+      image_url: this.resolveRequiredStringAliases([
+        { name: "image_url", value: params.image_url },
+        { name: "imageUrl", value: params.imageUrl },
+        { name: "image", value: params.image },
+        { name: "portrait", value: params.portrait },
+        { name: "portrait_url", value: params.portrait_url },
+        { name: "portraitUrl", value: params.portraitUrl },
+        { name: "avatar", value: params.avatar },
+        { name: "avatarUrl", value: params.avatarUrl },
+        { name: "avatar_url", value: params.avatar_url },
+        { name: "photo", value: params.photo },
+        { name: "photoUrl", value: params.photoUrl },
+        { name: "photo_url", value: params.photo_url }
+      ]),
+      audio_url: this.resolveRequiredStringAliases([
+        { name: "audio_url", value: params.audio_url },
+        { name: "audioUrl", value: params.audioUrl },
+        { name: "audio", value: params.audio }
+      ]),
+      expressiveness: params.expressiveness
+    });
+  }
+  videoJobPath(jobId) {
+    return `/videos/${encodeURIComponent(jobId)}`;
+  }
+  normalizeVideoJob(job, headers) {
+    const jobId = job.id ?? job.jobId ?? job.job_id ?? job.task_id ?? job.taskId;
+    if (!jobId) {
+      throw new PuppetryError(
+        502,
+        "invalid_response",
+        "Puppetry API returned a video job without an id"
+      );
+    }
+    const retryAfter = job.retryAfter ?? job.retryAfterSeconds ?? job.retry_after_seconds ?? this.parseRetryAfter(this.readResponseHeader(headers, "Retry-After"));
+    const nextPollAt = job.nextPollAt ?? job.next_poll_at ?? this.videoNextPollAtHeader(headers);
+    const videoUrl = this.firstDefinedNullable(
+      job.videoUrl,
+      job.video_url,
+      job.resultUrl,
+      job.result_url,
+      job.downloadUrl,
+      job.download_url,
+      job.outputUrl,
+      job.output_url,
+      job.url
+    );
+    const durationSeconds = this.firstDefinedNullable(
+      job.durationSeconds,
+      job.duration_seconds,
+      job.duration
+    );
+    const retryable = typeof job.retryable === "boolean" ? job.retryable : void 0;
+    const retryBlockedReason = job.retryBlockedReason ?? job.retry_blocked_reason;
+    const retryBlockCode = job.retryBlockCode ?? job.retry_block_code;
+    const diagnostics = job.diagnostics ?? this.videoJobResultDiagnostics(job.result);
+    const createdAt = job.createdAt ?? job.created_at;
+    const expiresAt = job.expiresAt ?? job.expires_at;
+    const completedAt = this.firstDefinedNullable(
+      job.completedAt,
+      job.completed_at
+    );
+    const thumbnailUrl = this.firstDefinedNullable(
+      job.thumbnailUrl,
+      job.thumbnail_url
+    );
+    const { statusUrl, contentLocation } = this.videoJobPollLocationAliases(job, headers);
+    const statusCredits = this.videoStatusCredits(job.credits);
+    const creationCredits = this.videoCreationCredits(job, headers);
+    const operationId = job.operationId ?? job.operation_id ?? this.videoOperationIdHeader(headers);
+    const requestId = job.requestId ?? job.request_id ?? this.videoRequestIdHeader(headers);
+    const idempotentReplay = job.idempotentReplay ?? job.idempotent_replay;
+    const source = normalizeVideoJobSource(job.source) ?? normalizeVideoJobSource(job.request_source) ?? normalizeVideoJobSource(job.requestSource);
+    const status = normalizeVideoStatusAlias(job.status) ?? normalizeVideoStatusAlias(job.state) ?? normalizeVideoStatusAlias(job.task_status) ?? normalizeVideoStatusAlias(job.taskStatus) ?? "processing";
+    const progress = this.videoProgress(job);
+    const {
+      credits: _credits,
+      creation_credits: _creationCredits,
+      creationCredits: _creationCreditsCamel,
+      ...jobWithoutCreditAliases
+    } = job;
+    return this.attachVideoJobHelpers({
+      ...jobWithoutCreditAliases,
+      id: jobId,
+      job_id: job.job_id ?? jobId,
+      jobId: job.jobId ?? jobId,
+      operation_id: job.operation_id ?? operationId ?? jobId,
+      operationId: job.operationId ?? operationId ?? jobId,
+      ...requestId !== void 0 ? { request_id: requestId, requestId } : {},
+      task_id: job.task_id ?? jobId,
+      taskId: job.taskId ?? jobId,
+      status,
+      state: normalizeVideoStatusAlias(job.state) ?? status,
+      task_status: normalizeVideoStatusAlias(job.task_status) ?? status,
+      taskStatus: normalizeVideoStatusAlias(job.taskStatus) ?? status,
+      ...source !== void 0 ? { source, request_source: source, requestSource: source } : {},
+      ...progress !== void 0 ? {
+        progress,
+        percent: job.percent ?? progress,
+        percentage: job.percentage ?? progress,
+        progress_percent: job.progress_percent ?? progress,
+        progressPercent: job.progressPercent ?? progress
+      } : {},
+      ...createdAt !== void 0 ? { created_at: createdAt, createdAt } : {},
+      ...expiresAt !== void 0 ? { expires_at: expiresAt, expiresAt } : {},
+      ...completedAt !== void 0 ? { completed_at: completedAt, completedAt } : {},
+      ...videoUrl !== void 0 ? {
+        url: videoUrl,
+        video_url: videoUrl,
+        videoUrl,
+        result_url: videoUrl,
+        resultUrl: videoUrl,
+        download_url: videoUrl,
+        downloadUrl: videoUrl,
+        output_url: videoUrl,
+        outputUrl: videoUrl
+      } : {},
+      ...thumbnailUrl !== void 0 ? { thumbnail_url: thumbnailUrl, thumbnailUrl } : {},
+      duration: job.duration ?? durationSeconds,
+      duration_seconds: job.duration_seconds ?? durationSeconds,
+      durationSeconds,
+      ...statusUrl !== void 0 ? { status_url: statusUrl, statusUrl } : {},
+      ...contentLocation !== void 0 ? { content_location: contentLocation, contentLocation } : {},
+      ...statusCredits !== void 0 ? { credits: statusCredits } : {},
+      ...creationCredits !== void 0 ? { creation_credits: creationCredits, creationCredits } : {},
+      ...idempotentReplay !== void 0 ? { idempotent_replay: idempotentReplay, idempotentReplay } : {},
+      ...retryable !== void 0 ? { retryable } : {},
+      ...retryBlockedReason ? {
+        retry_blocked_reason: retryBlockedReason,
+        retryBlockedReason
+      } : {},
+      ...retryBlockCode ? {
+        retry_block_code: retryBlockCode,
+        retryBlockCode
+      } : {},
+      ...diagnostics ? { diagnostics } : {},
+      ...retryAfter !== void 0 ? { retryAfter } : {},
+      ...retryAfter !== void 0 ? { retry_after_seconds: retryAfter } : {},
+      ...retryAfter !== void 0 ? { retryAfterSeconds: retryAfter } : {},
+      ...nextPollAt !== void 0 ? { next_poll_at: nextPollAt, nextPollAt } : {}
+    });
+  }
+  videoJobStatusUrlHeader(headers) {
+    return this.videoLocationHeader(headers) ?? this.videoContentLocationHeader(headers);
+  }
+  videoJobPollLocationAliases(job, headers) {
+    const bodyStatusUrl = job.statusUrl ?? job.status_url;
+    const bodyContentLocation = job.contentLocation ?? job.content_location;
+    const headerLocation = this.videoLocationHeader(headers);
+    const headerContentLocation = this.videoContentLocationHeader(headers);
+    return {
+      statusUrl: bodyStatusUrl ?? bodyContentLocation ?? headerLocation ?? headerContentLocation,
+      contentLocation: bodyContentLocation ?? bodyStatusUrl ?? headerContentLocation ?? headerLocation
+    };
+  }
+  videoLocationHeader(headers) {
+    const value = headers?.get("Location") ?? headers?.get("location");
+    if (!value) return void 0;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : void 0;
+  }
+  videoContentLocationHeader(headers) {
+    const value = headers?.get("Content-Location") ?? headers?.get("content-location");
+    if (!value) return void 0;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : void 0;
+  }
+  videoOperationIdHeader(headers) {
+    const value = headers?.get("Puppetry-Operation-Id") ?? headers?.get("puppetry-operation-id") ?? headers?.get("X-Puppetry-Operation-Id") ?? headers?.get("x-puppetry-operation-id");
+    if (!value) return void 0;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : void 0;
+  }
+  videoRequestIdHeader(headers) {
+    const value = headers?.get("Puppetry-Request-Id") ?? headers?.get("puppetry-request-id") ?? headers?.get("X-Puppetry-Request-Id") ?? headers?.get("x-puppetry-request-id");
+    if (!value) return void 0;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : void 0;
+  }
+  videoNextPollAtHeader(headers) {
+    const value = headers?.get("X-Puppetry-Next-Poll-At") ?? headers?.get("x-puppetry-next-poll-at");
+    if (!value) return void 0;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : void 0;
+  }
+  videoStatusErrorOptions(method, path, headers, retryAfter) {
+    const statusUrl = this.videoJobStatusUrlHeader(headers);
+    const contentLocation = this.videoContentLocationHeader(headers);
+    const jobId = this.videoJobIdFromStatusUrl(statusUrl ?? contentLocation);
+    const operationId = this.videoOperationIdHeader(headers);
+    const requestId = this.videoRequestIdHeader(headers);
+    const nextPollAt = this.videoNextPollAtHeader(headers);
+    const creationCredits = this.isVideoStatusRequest(method, path) ? this.videoCreationCreditsFromHeaders(headers) : void 0;
+    return {
+      retryAfter,
+      ...jobId ? { id: jobId, job_id: jobId, jobId } : {},
+      ...statusUrl ? { status_url: statusUrl, statusUrl } : {},
+      ...contentLocation ? { content_location: contentLocation, contentLocation } : {},
+      ...operationId ? { operation_id: operationId, operationId } : {},
+      ...requestId ? { request_id: requestId, requestId } : {},
+      ...nextPollAt ? { next_poll_at: nextPollAt, nextPollAt } : {},
+      ...creationCredits ? { creation_credits: creationCredits, creationCredits } : {}
+    };
+  }
+  videoCreditErrorOptions(headers) {
+    const requiredCredits = this.videoCreditHeaderNumber(
+      headers,
+      "X-Puppetry-Credits-Required"
+    );
+    const creditsRemaining = this.videoCreditHeaderNumber(
+      headers,
+      "X-Puppetry-Credits-Remaining"
+    );
+    return {
+      ...requiredCredits !== void 0 ? { required_credits: requiredCredits, requiredCredits } : {},
+      ...creditsRemaining !== void 0 ? {
+        credits_remaining: creditsRemaining,
+        creditsRemaining,
+        remaining_credits: creditsRemaining,
+        remainingCredits: creditsRemaining
+      } : {}
+    };
+  }
+  videoCreditHeaderNumber(headers, name) {
+    const raw = this.readResponseHeader(headers, name);
+    if (raw === null) return void 0;
+    const trimmed = raw.trim();
+    if (!/^\d+$/.test(trimmed)) return void 0;
+    const value = Number(trimmed);
+    return Number.isSafeInteger(value) ? value : void 0;
+  }
+  videoJobIdFromStatusUrl(statusUrl) {
+    if (!statusUrl) return void 0;
+    try {
+      const url = new URL(statusUrl, this.baseUrl);
+      const match = url.pathname.match(/\/videos\/([^/]+)\/?$/);
+      if (!match) return void 0;
+      return decodeURIComponent(match[1]);
+    } catch {
+      return void 0;
+    }
+  }
+  retryableStatusErrorJobId(err) {
+    return err.jobId ?? this.videoJobIdFromStatusUrl(err.statusUrl ?? err.status_url);
+  }
+  videoJobResultDiagnostics(result) {
+    if (!result || typeof result !== "object" || Array.isArray(result)) {
+      return void 0;
+    }
+    return result.diagnostics;
+  }
+  videoStatusCredits(credits) {
+    if (!credits || typeof credits !== "object") return void 0;
+    if (typeof credits.charged !== "number" || !Number.isFinite(credits.charged)) {
+      return void 0;
+    }
+    return {
+      charged: credits.charged,
+      remaining: typeof credits.remaining === "number" && Number.isFinite(credits.remaining) ? credits.remaining : null
+    };
+  }
+  videoCreationCredits(job, headers) {
+    const raw = job.creationCredits ?? job.creation_credits;
+    if (raw && typeof raw === "object") {
+      if (typeof raw.charged !== "number" || !Number.isFinite(raw.charged)) {
+        return this.videoCreationCreditsFromHeaders(headers);
+      }
+      const remainingAfterDebit = raw.remainingAfterDebit ?? raw.remaining_after_debit ?? null;
+      const normalizedRemainingAfterDebit = typeof remainingAfterDebit === "number" && Number.isFinite(remainingAfterDebit) ? remainingAfterDebit : null;
+      return {
+        charged: raw.charged,
+        remaining_after_debit: normalizedRemainingAfterDebit,
+        remainingAfterDebit: normalizedRemainingAfterDebit
+      };
+    }
+    return this.videoCreationCreditsFromHeaders(headers);
+  }
+  videoCreationCreditsFromHeaders(headers) {
+    const charged = this.videoCreditHeaderNumber(
+      headers,
+      "X-Puppetry-Credits-Required"
+    );
+    if (charged === void 0) return void 0;
+    const remainingAfterDebit = this.videoCreditHeaderNumber(
+      headers,
+      "X-Puppetry-Credits-Remaining"
+    ) ?? null;
+    return {
+      charged,
+      remaining_after_debit: remainingAfterDebit,
+      remainingAfterDebit
+    };
+  }
+  videoProgress(job) {
+    const progress = job.progress ?? job.percent ?? job.percentage ?? job.progressPercent ?? job.progress_percent;
+    return typeof progress === "number" || progress === null ? progress : void 0;
+  }
+  attachVideoJobHelpers(job) {
+    const sdkJob = job;
+    Object.defineProperty(sdkJob, "waitForCompletion", {
+      value: (options) => {
+        if (sdkJob.status === "completed" || sdkJob.status === "failed") {
+          return Promise.resolve(sdkJob);
+        }
+        return this.videos.waitForCompletion(
+          this.videoJobIdFromStatusUrl(sdkJob.statusUrl ?? sdkJob.status_url) ?? sdkJob.id,
+          this.waitOptionsWithInitialDelay(
+            options,
+            sdkJob.retryAfter,
+            sdkJob.nextPollAt ?? sdkJob.next_poll_at
+          )
+        );
+      },
+      enumerable: false,
+      configurable: true
+    });
+    return sdkJob;
+  }
+  waitOptionsWithInitialDelay(options, retryAfterSeconds, nextPollAt) {
+    if (options?.initialDelayMs !== void 0) return options;
+    const initialDelayMs = this.retryAfterDelayMs(retryAfterSeconds) ?? this.nextPollDelayMs(nextPollAt);
+    return initialDelayMs === void 0 ? options : { ...options, initialDelayMs };
+  }
+  retryAfterDelayMs(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+      return void 0;
+    }
+    return value * 1e3;
+  }
+  optionDelayMs(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+      return void 0;
+    }
+    return value;
+  }
+  nextPollDelayMs(value) {
+    if (typeof value !== "string" || value.trim() === "") {
+      return void 0;
+    }
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp)) {
+      return void 0;
+    }
+    return Math.max(timestamp - Date.now(), 0);
+  }
+  async sleepWithinDeadline(ms, deadline) {
+    const remainingMs = Math.max(deadline - Date.now(), 0);
+    await this.sleep(Math.min(ms, remainingMs));
+  }
+  pollingDelayMs(job, headers, intervalMs) {
+    const retryAfterSeconds = this.parseRetryAfter(this.readResponseHeader(headers, "Retry-After")) ?? job.retryAfter;
+    const retryAfterDelayMs = this.retryAfterDelayMs(retryAfterSeconds);
+    if (retryAfterDelayMs !== void 0) {
+      return retryAfterDelayMs;
+    }
+    return this.nextPollDelayMs(job.nextPollAt ?? job.next_poll_at) ?? intervalMs;
+  }
+  retryableStatusErrorDelayMs(err, intervalMs) {
+    if (err.retryable !== true) return void 0;
+    return this.retryAfterDelayMs(err.retryAfter) ?? this.nextPollDelayMs(err.nextPollAt ?? err.next_poll_at) ?? intervalMs;
+  }
+  normalizeUsage(usage) {
+    const videoCredits = usage.video_credits ?? usage.videoCredits;
+    if (!videoCredits) {
+      return usage;
+    }
+    const rawCurrentApiKey = videoCredits.current_api_key ?? videoCredits.currentApiKey ?? {
+      used: 0,
+      refunded: 0,
+      net_used: 0,
+      transactions: 0
+    };
+    const currentApiKeyNetUsed = rawCurrentApiKey.net_used ?? rawCurrentApiKey.netUsed ?? 0;
+    const currentApiKey = {
+      ...rawCurrentApiKey,
+      keyId: rawCurrentApiKey.keyId ?? rawCurrentApiKey.key_id,
+      keyPrefix: rawCurrentApiKey.keyPrefix ?? rawCurrentApiKey.key_prefix,
+      net_used: currentApiKeyNetUsed,
+      netUsed: rawCurrentApiKey.netUsed ?? currentApiKeyNetUsed
+    };
+    const videoCreditNetUsed = videoCredits.net_used ?? videoCredits.netUsed ?? 0;
+    const resetAt = videoCredits.reset_at ?? videoCredits.resetAt;
+    const normalizedVideoCredits = {
+      ...videoCredits,
+      reset_at: resetAt,
+      resetAt: videoCredits.resetAt ?? resetAt,
+      net_used: videoCreditNetUsed,
+      netUsed: videoCredits.netUsed ?? videoCreditNetUsed,
+      current_api_key: currentApiKey,
+      currentApiKey: videoCredits.currentApiKey ?? currentApiKey
+    };
+    const videoGeneration = this.normalizeVideoGenerationReadiness(
+      usage.video_generation ?? usage.videoGeneration,
+      videoCredits.balance
+    );
+    return {
+      ...usage,
+      video_credits: normalizedVideoCredits,
+      videoCredits: usage.videoCredits ?? normalizedVideoCredits,
+      video_generation: videoGeneration,
+      videoGeneration: usage.videoGeneration ?? videoGeneration,
+      plan: usage.plan ?? "developer_api",
+      creditsTotal: usage.creditsTotal ?? Math.max(
+        videoCredits.balance + videoCreditNetUsed,
+        videoCredits.balance
+      ),
+      creditsUsed: usage.creditsUsed ?? videoCreditNetUsed,
+      creditsRemaining: usage.creditsRemaining ?? videoCredits.balance,
+      periodStart: usage.periodStart ?? `${videoCredits.month}-01`,
+      periodEnd: usage.periodEnd ?? resetAt
+    };
+  }
+  normalizeVideoGenerationReadiness(readiness, balance) {
+    const requiredCredits = readiness?.required_credits ?? readiness?.requiredCredits ?? 1;
+    const creditsRemaining = readiness?.credits_remaining ?? readiness?.creditsRemaining ?? balance;
+    const concurrentJobs = readiness?.concurrent_jobs ?? readiness?.concurrentJobs;
+    const activeJobs = readiness?.active_jobs ?? readiness?.activeJobs;
+    const availableSlots = readiness?.available_slots ?? readiness?.availableSlots;
+    const activeJobExpiresInSeconds = readiness?.active_job_expires_in_seconds ?? readiness?.activeJobExpiresInSeconds;
+    const canCreate = readiness?.can_create ?? readiness?.canCreate ?? (creditsRemaining >= requiredCredits && (availableSlots === void 0 || availableSlots > 0));
+    const reason = readiness?.reason ?? (creditsRemaining < requiredCredits ? "insufficient_video_credits" : availableSlots !== void 0 && availableSlots <= 0 ? "concurrent_job_limit_reached" : "available");
+    const retryAfterSeconds = readiness?.retry_after_seconds ?? readiness?.retryAfterSeconds ?? readiness?.retryAfter ?? (reason === "concurrent_job_limit_reached" ? activeJobExpiresInSeconds : void 0);
+    const nextPollAt = readiness?.nextPollAt ?? readiness?.next_poll_at;
+    const blockers = this.normalizeVideoGenerationBlockers(
+      readiness?.blockers,
+      {
+        reason,
+        requiredCredits,
+        creditsRemaining,
+        concurrentJobs,
+        activeJobs,
+        availableSlots,
+        activeJobExpiresInSeconds,
+        retryAfterSeconds
+      }
+    );
+    return {
+      can_create: canCreate,
+      canCreate: readiness?.canCreate ?? canCreate,
+      required_credits: requiredCredits,
+      requiredCredits: readiness?.requiredCredits ?? requiredCredits,
+      credits_remaining: creditsRemaining,
+      creditsRemaining: readiness?.creditsRemaining ?? creditsRemaining,
+      ...concurrentJobs === void 0 ? {} : {
+        concurrent_jobs: concurrentJobs,
+        concurrentJobs: readiness?.concurrentJobs ?? concurrentJobs
+      },
+      ...activeJobs === void 0 ? {} : {
+        active_jobs: activeJobs,
+        activeJobs: readiness?.activeJobs ?? activeJobs
+      },
+      ...availableSlots === void 0 ? {} : {
+        available_slots: availableSlots,
+        availableSlots: readiness?.availableSlots ?? availableSlots
+      },
+      ...activeJobExpiresInSeconds === void 0 ? {} : {
+        active_job_expires_in_seconds: activeJobExpiresInSeconds,
+        activeJobExpiresInSeconds: readiness?.activeJobExpiresInSeconds ?? activeJobExpiresInSeconds
+      },
+      ...retryAfterSeconds === void 0 ? {} : {
+        retry_after_seconds: retryAfterSeconds,
+        retryAfter: readiness?.retryAfter ?? retryAfterSeconds,
+        retryAfterSeconds: readiness?.retryAfterSeconds ?? retryAfterSeconds
+      },
+      ...nextPollAt === void 0 ? {} : { next_poll_at: nextPollAt, nextPollAt },
+      ...blockers.length === 0 ? {} : { blockers },
+      reason
+    };
+  }
+  normalizeVideoGenerationBlockers(blockers, fallback) {
+    if (Array.isArray(blockers) && blockers.length > 0) {
+      return blockers.map(
+        (blocker) => this.normalizeVideoGenerationBlocker(blocker)
+      );
+    }
+    return this.derivedVideoGenerationBlockers(fallback);
+  }
+  normalizeVideoGenerationBlocker(blocker) {
+    const record = blocker;
+    const code = this.videoGenerationReadinessReason(record.code) ?? this.videoGenerationReadinessReason(record.reason);
+    if (code === "insufficient_video_credits") {
+      const requiredCredits = this.readinessNumber(record.required_credits) ?? this.readinessNumber(record.requiredCredits) ?? 1;
+      const creditsRemaining = this.readinessNumber(record.credits_remaining) ?? this.readinessNumber(record.creditsRemaining) ?? 0;
+      const retryBlockCode = this.readinessString(record.retry_block_code) ?? this.readinessString(record.retryBlockCode);
+      return {
+        code,
+        reason: code,
+        retryable: false,
+        required_credits: requiredCredits,
+        requiredCredits,
+        credits_remaining: creditsRemaining,
+        creditsRemaining,
+        ...retryBlockCode === void 0 ? {} : {
+          retry_block_code: retryBlockCode,
+          retryBlockCode
+        }
+      };
+    }
+    const retryAfterSeconds = this.readinessNumber(record.retry_after_seconds) ?? this.readinessNumber(record.retryAfterSeconds) ?? this.readinessNumber(record.retryAfter);
+    const nextPollAt = this.readinessString(record.nextPollAt) ?? this.readinessString(record.next_poll_at);
+    return {
+      code: "concurrent_job_limit_reached",
+      reason: "concurrent_job_limit_reached",
+      retryable: true,
+      ...this.activeJobReadinessAliases(record),
+      ...retryAfterSeconds === void 0 ? {} : {
+        retry_after_seconds: retryAfterSeconds,
+        retryAfter: retryAfterSeconds,
+        retryAfterSeconds
+      },
+      ...nextPollAt === void 0 ? {} : { next_poll_at: nextPollAt, nextPollAt }
+    };
+  }
+  derivedVideoGenerationBlockers(params) {
+    const blockers = [];
+    if (params.reason === "insufficient_video_credits" || params.creditsRemaining < params.requiredCredits) {
+      blockers.push({
+        code: "insufficient_video_credits",
+        reason: "insufficient_video_credits",
+        retryable: false,
+        required_credits: params.requiredCredits,
+        requiredCredits: params.requiredCredits,
+        credits_remaining: params.creditsRemaining,
+        creditsRemaining: params.creditsRemaining
+      });
+    }
+    if (params.reason === "concurrent_job_limit_reached" || params.availableSlots !== void 0 && params.availableSlots <= 0) {
+      blockers.push({
+        code: "concurrent_job_limit_reached",
+        reason: "concurrent_job_limit_reached",
+        retryable: true,
+        ...params.concurrentJobs === void 0 ? {} : {
+          concurrent_jobs: params.concurrentJobs,
+          concurrentJobs: params.concurrentJobs
+        },
+        ...params.activeJobs === void 0 ? {} : {
+          active_jobs: params.activeJobs,
+          activeJobs: params.activeJobs
+        },
+        ...params.availableSlots === void 0 ? {} : {
+          available_slots: params.availableSlots,
+          availableSlots: params.availableSlots
+        },
+        ...params.activeJobExpiresInSeconds === void 0 ? {} : {
+          active_job_expires_in_seconds: params.activeJobExpiresInSeconds,
+          activeJobExpiresInSeconds: params.activeJobExpiresInSeconds
+        },
+        ...params.retryAfterSeconds === void 0 ? {} : {
+          retry_after_seconds: params.retryAfterSeconds,
+          retryAfter: params.retryAfterSeconds,
+          retryAfterSeconds: params.retryAfterSeconds
+        }
+      });
+    }
+    return blockers;
+  }
+  activeJobReadinessAliases(record) {
+    const concurrentJobs = this.readinessNumber(record.concurrent_jobs) ?? this.readinessNumber(record.concurrentJobs);
+    const activeJobs = this.readinessNumber(record.active_jobs) ?? this.readinessNumber(record.activeJobs);
+    const availableSlots = this.readinessNumber(record.available_slots) ?? this.readinessNumber(record.availableSlots);
+    const activeJobExpiresInSeconds = this.readinessNumber(record.active_job_expires_in_seconds) ?? this.readinessNumber(record.activeJobExpiresInSeconds);
+    return {
+      ...concurrentJobs === void 0 ? {} : { concurrent_jobs: concurrentJobs, concurrentJobs },
+      ...activeJobs === void 0 ? {} : { active_jobs: activeJobs, activeJobs },
+      ...availableSlots === void 0 ? {} : { available_slots: availableSlots, availableSlots },
+      ...activeJobExpiresInSeconds === void 0 ? {} : {
+        active_job_expires_in_seconds: activeJobExpiresInSeconds,
+        activeJobExpiresInSeconds
+      }
+    };
+  }
+  videoGenerationReadinessReason(value) {
+    return value === "available" || value === "insufficient_video_credits" || value === "concurrent_job_limit_reached" ? value : void 0;
+  }
+  readinessNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+  }
+  readinessString(value) {
+    return typeof value === "string" && value ? value : void 0;
+  }
+  async getVideoGenerationReadiness() {
+    const usage = await this.usage.get();
+    const readiness = usage.video_generation ?? usage.videoGeneration;
+    if (!readiness) {
+      throw new PuppetryError(
+        502,
+        "invalid_response",
+        "Puppetry API usage response did not include video_generation readiness"
+      );
+    }
+    return readiness;
+  }
+  async ensureVideoGenerationReady() {
+    const readiness = await this.getVideoGenerationReadiness();
+    if (readiness.can_create !== false) return readiness;
+    const retryAfter = readiness.retry_after_seconds ?? readiness.retryAfterSeconds ?? readiness.retryAfter ?? readiness.active_job_expires_in_seconds ?? readiness.activeJobExpiresInSeconds;
+    const nextPollAt = readiness.nextPollAt ?? readiness.next_poll_at;
+    const details = { video_generation: readiness };
+    const errorOptions = this.videoGenerationReadinessErrorOptions(readiness);
+    if (readiness.reason === "concurrent_job_limit_reached") {
+      throw new PuppetryRateLimitError(
+        retryAfter,
+        "Video generation is at the active job limit",
+        details,
+        "rate_limited",
+        {
+          ...errorOptions,
+          ...nextPollAt === void 0 ? {} : { next_poll_at: nextPollAt, nextPollAt }
+        }
+      );
+    }
+    throw new PuppetryError(
+      402,
+      readiness.reason,
+      "Video generation is not ready for this API key",
+      details,
+      {
+        ...errorOptions,
+        retryAfter,
+        ...nextPollAt === void 0 ? {} : { next_poll_at: nextPollAt, nextPollAt }
+      }
+    );
+  }
+  videoGenerationReadinessErrorOptions(readiness) {
+    const requiredCredits = readiness.required_credits ?? readiness.requiredCredits;
+    const creditsRemaining = readiness.credits_remaining ?? readiness.creditsRemaining;
+    const blocker = readiness.blockers?.find(
+      (item) => item.reason === readiness.reason || item.code === readiness.reason
+    );
+    const retryBlockCode = readiness.reason === "insufficient_video_credits" ? (blocker && "retry_block_code" in blocker ? blocker.retry_block_code ?? blocker.retryBlockCode : void 0) ?? "INSUFFICIENT_VIDEO_CREDITS" : void 0;
+    const retryBlockedReason = readiness.reason === "insufficient_video_credits" ? `Developer API video generation needs ${requiredCredits ?? 1} credit, but only ${creditsRemaining ?? 0} remain.` : readiness.reason;
+    return {
+      retryable: readiness.reason === "concurrent_job_limit_reached",
+      ...requiredCredits === void 0 ? {} : { required_credits: requiredCredits, requiredCredits },
+      ...creditsRemaining === void 0 ? {} : {
+        credits_remaining: creditsRemaining,
+        creditsRemaining,
+        remaining_credits: creditsRemaining,
+        remainingCredits: creditsRemaining
+      },
+      retry_blocked_reason: retryBlockedReason,
+      retryBlockedReason,
+      ...retryBlockCode === void 0 ? {} : { retry_block_code: retryBlockCode, retryBlockCode }
+    };
+  }
+  normalizeAudioUploadLimits(limits) {
+    const maxFileBytes = limits.max_file_bytes ?? limits.maxFileBytes;
+    const monthlyUploads = limits.monthly_uploads ?? limits.monthlyUploads;
+    const storageBytes = limits.storage_bytes ?? limits.storageBytes;
+    const remainingMonthlyUploads = limits.remaining_monthly_uploads ?? limits.remainingMonthlyUploads;
+    const remainingStorageBytes = limits.remaining_storage_bytes ?? limits.remainingStorageBytes;
+    return {
+      ...limits,
+      max_file_bytes: maxFileBytes,
+      maxFileBytes,
+      monthly_uploads: monthlyUploads,
+      monthlyUploads,
+      storage_bytes: storageBytes,
+      storageBytes,
+      remaining_monthly_uploads: remainingMonthlyUploads,
+      remainingMonthlyUploads,
+      remaining_storage_bytes: remainingStorageBytes,
+      remainingStorageBytes
+    };
+  }
+  normalizeAudioUpload(upload) {
+    const uploadUrl = upload.upload_url ?? upload.uploadUrl;
+    const readUrl = upload.read_url ?? upload.readUrl;
+    if (!uploadUrl || !readUrl) {
+      throw new PuppetryError(
+        502,
+        "invalid_response",
+        "Puppetry API returned an upload response without upload/read URLs"
+      );
+    }
+    const readUrlExpiresIn = upload.read_url_expires_in ?? upload.readUrlExpiresIn;
+    const readUrlExpiresAt = upload.read_url_expires_at ?? upload.readUrlExpiresAt;
+    const uploadUrlExpiresIn = upload.upload_url_expires_in ?? upload.uploadUrlExpiresIn;
+    const idempotentReplay = upload.idempotent_replay ?? upload.idempotentReplay;
+    return {
+      ...upload,
+      upload_url: uploadUrl,
+      uploadUrl,
+      read_url: readUrl,
+      readUrl,
+      read_url_expires_in: readUrlExpiresIn,
+      readUrlExpiresIn,
+      read_url_expires_at: readUrlExpiresAt,
+      readUrlExpiresAt,
+      upload_url_expires_in: uploadUrlExpiresIn,
+      uploadUrlExpiresIn,
+      idempotent_replay: idempotentReplay,
+      idempotentReplay,
+      limits: this.normalizeAudioUploadLimits(upload.limits)
+    };
+  }
+  // ── Polled event helper ────────────────────────────────────────────
+  videoJobEvent(job, headers) {
+    const normalizedJob = this.normalizeVideoJob(job, headers);
+    const progress = typeof normalizedJob.progress === "number" ? normalizedJob.progress : normalizedJob.status === "completed" ? 100 : void 0;
+    const videoUrl = normalizedJob.videoUrl ?? void 0;
+    const type = normalizedJob.status === "processing" && progress !== void 0 ? "progress" : normalizedJob.status;
+    const statusUrl = normalizedJob.statusUrl ?? normalizedJob.status_url;
+    const contentLocation = normalizedJob.contentLocation ?? normalizedJob.content_location;
+    const operationId = job.operationId ?? job.operation_id ?? this.videoOperationIdHeader(headers);
+    const requestId = job.requestId ?? job.request_id ?? this.videoRequestIdHeader(headers);
+    const source = normalizeVideoJobSource(job.source) ?? normalizeVideoJobSource(job.request_source) ?? normalizeVideoJobSource(job.requestSource);
+    const retryAfter = normalizedJob.retryAfter ?? normalizedJob.retryAfterSeconds ?? normalizedJob.retry_after_seconds;
+    const nextPollAt = normalizedJob.nextPollAt ?? normalizedJob.next_poll_at;
+    const creationCredits = this.videoCreationCredits(normalizedJob);
+    return {
+      type,
+      id: normalizedJob.id,
+      job_id: normalizedJob.job_id,
+      jobId: normalizedJob.id,
+      task_id: normalizedJob.task_id,
+      taskId: normalizedJob.taskId,
+      ...operationId ? { operation_id: operationId, operationId } : {},
+      ...requestId ? { request_id: requestId, requestId } : {},
+      ...source ? { source, request_source: source, requestSource: source } : {},
+      ...statusUrl ? { status_url: statusUrl, statusUrl } : {},
+      ...contentLocation ? { content_location: contentLocation, contentLocation } : {},
+      ...progress !== void 0 ? { progress } : {},
+      ...videoUrl ? { video_url: videoUrl, videoUrl } : {},
+      ...normalizedJob.error ? { error: normalizedJob.error } : {},
+      ...normalizedJob.retryable !== void 0 ? { retryable: normalizedJob.retryable } : {},
+      ...normalizedJob.credits ? { credits: normalizedJob.credits } : {},
+      ...creationCredits ? {
+        creation_credits: creationCredits,
+        creationCredits
+      } : {},
+      ...normalizedJob.retryBlockedReason ? {
+        retry_blocked_reason: normalizedJob.retryBlockedReason,
+        retryBlockedReason: normalizedJob.retryBlockedReason
+      } : {},
+      ...normalizedJob.retryBlockCode ? {
+        retry_block_code: normalizedJob.retryBlockCode,
+        retryBlockCode: normalizedJob.retryBlockCode
+      } : {},
+      ...retryAfter !== void 0 ? {
+        retry_after_seconds: retryAfter,
+        retryAfter,
+        retryAfterSeconds: retryAfter
+      } : {},
+      ...nextPollAt ? {
+        next_poll_at: nextPollAt,
+        nextPollAt
+      } : {},
+      ...normalizedJob.createdAt ? {
+        created_at: normalizedJob.createdAt,
+        createdAt: normalizedJob.createdAt
+      } : {},
+      ...normalizedJob.expiresAt ? {
+        expires_at: normalizedJob.expiresAt,
+        expiresAt: normalizedJob.expiresAt
+      } : {},
+      ...normalizedJob.completedAt !== void 0 ? {
+        completed_at: normalizedJob.completedAt,
+        completedAt: normalizedJob.completedAt
+      } : {},
+      timestamp: normalizedJob.completedAt ?? normalizedJob.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  videoRetryingEvent(err, fallbackJobId) {
+    const jobId = this.retryableStatusErrorJobId(err) ?? fallbackJobId;
+    const source = normalizeVideoJobSource(err.source);
+    const requestSource = normalizeVideoJobSource(
+      err.requestSource ?? err.request_source
+    );
+    return {
+      type: "retrying",
+      id: err.id ?? jobId,
+      job_id: err.job_id ?? jobId,
+      jobId,
+      task_id: err.task_id ?? jobId,
+      taskId: err.taskId ?? jobId,
+      ...err.operationId ? { operation_id: err.operationId, operationId: err.operationId } : {},
+      ...err.requestId ? { request_id: err.requestId, requestId: err.requestId } : {},
+      ...source || requestSource ? {
+        source: source ?? requestSource,
+        request_source: requestSource ?? source,
+        requestSource: requestSource ?? source
+      } : {},
+      ...err.statusUrl ? { status_url: err.statusUrl, statusUrl: err.statusUrl } : {},
+      ...err.contentLocation ? {
+        content_location: err.contentLocation,
+        contentLocation: err.contentLocation
+      } : {},
+      error: err.message,
+      code: err.code,
+      status: err.status,
+      statusCode: err.status,
+      ...err.retryable !== void 0 ? { retryable: err.retryable } : {},
+      ...err.credits ? { credits: err.credits } : {},
+      ...err.creationCredits ? {
+        creation_credits: err.creationCredits,
+        creationCredits: err.creationCredits
+      } : {},
+      ...err.retryBlockedReason ? {
+        retry_blocked_reason: err.retryBlockedReason,
+        retryBlockedReason: err.retryBlockedReason
+      } : {},
+      ...err.retryBlockCode ? {
+        retry_block_code: err.retryBlockCode,
+        retryBlockCode: err.retryBlockCode
+      } : {},
+      ...err.retryAfter !== void 0 ? {
+        retry_after_seconds: err.retryAfter,
+        retryAfter: err.retryAfter,
+        retryAfterSeconds: err.retryAfter
+      } : {},
+      ...err.nextPollAt ? { next_poll_at: err.nextPollAt, nextPollAt: err.nextPollAt } : {},
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  async *streamPolledVideoEvents(jobId, options) {
+    const interval = options?.intervalMs ?? 2e3;
+    const timeout = options?.timeoutMs ?? 3e5;
+    const deadline = Date.now() + timeout;
+    const initialDelayMs = this.optionDelayMs(options?.initialDelayMs);
+    let currentJobId = jobId;
+    if (initialDelayMs !== void 0 && initialDelayMs > 0) {
+      await this.sleepWithinDeadline(initialDelayMs, deadline);
+    }
+    while (Date.now() < deadline) {
+      try {
+        const { data: job, headers } = await this.getWithResponse(
+          this.videoJobPath(currentJobId)
+        );
+        const normalizedJob = this.normalizeVideoJob(job, headers);
+        currentJobId = this.videoJobIdFromStatusUrl(
+          normalizedJob.statusUrl ?? normalizedJob.status_url
+        ) ?? normalizedJob.id;
+        yield this.videoJobEvent(job, headers);
+        if (normalizedJob.status === "completed" || normalizedJob.status === "failed") {
+          return;
+        }
+        const delayMs = this.pollingDelayMs(normalizedJob, headers, interval);
+        await this.sleep(Math.min(delayMs, Math.max(deadline - Date.now(), 0)));
+      } catch (err) {
+        if (!(err instanceof PuppetryError)) throw err;
+        const delayMs = this.retryableStatusErrorDelayMs(err, interval);
+        if (delayMs === void 0) throw err;
+        currentJobId = this.retryableStatusErrorJobId(err) ?? currentJobId;
+        yield this.videoRetryingEvent(err, currentJobId);
+        await this.sleepWithinDeadline(delayMs, deadline);
+      }
+    }
+    throw new PuppetryTimeoutError(timeout);
+  }
+};
+
+export {
+  Puppetry
+};