@puppetry.com/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,3163 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PUPPETRY_AGENT_TOOLS: () => PUPPETRY_AGENT_TOOLS,
+  Puppetry: () => Puppetry,
+  PuppetryAuthError: () => PuppetryAuthError,
+  PuppetryError: () => PuppetryError,
+  PuppetryNetworkError: () => PuppetryNetworkError,
+  PuppetryRateLimitError: () => PuppetryRateLimitError,
+  PuppetryTimeoutError: () => PuppetryTimeoutError,
+  callPuppetryAgentTool: () => callPuppetryAgentTool,
+  handlePuppetryMcpRequest: () => handlePuppetryMcpRequest,
+  puppetryErrorData: () => puppetryErrorData,
+  safeCallPuppetryAgentTool: () => safeCallPuppetryAgentTool
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var PuppetryError = class _PuppetryError extends Error {
+  constructor(status, code, message, details, options) {
+    super(message);
+    this.name = "PuppetryError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.object = options?.object;
+    this.retryAfter = options?.retryAfter;
+    this.retryable = options?.retryable;
+    this.credits = options?.credits;
+    this.creationCredits = options?.creationCredits ?? options?.creation_credits;
+    this.creation_credits = this.creationCredits;
+    this.retryBlockedReason = options?.retryBlockedReason ?? options?.retry_blocked_reason;
+    this.retry_blocked_reason = this.retryBlockedReason;
+    this.retryBlockCode = options?.retryBlockCode ?? options?.retry_block_code;
+    this.retry_block_code = this.retryBlockCode;
+    this.jobId = options?.jobId ?? options?.job_id ?? options?.id;
+    this.job_id = this.jobId;
+    this.id = this.jobId;
+    this.operationId = options?.operationId ?? options?.operation_id;
+    this.operation_id = this.operationId;
+    this.taskId = options?.taskId ?? options?.task_id ?? this.jobId;
+    this.task_id = this.taskId;
+    this.statusUrl = options?.statusUrl ?? options?.status_url ?? options?.contentLocation ?? options?.content_location;
+    this.status_url = this.statusUrl;
+    this.contentLocation = options?.contentLocation ?? options?.content_location ?? options?.statusUrl ?? options?.status_url;
+    this.content_location = this.contentLocation;
+    this.createdAt = options?.createdAt ?? options?.created_at;
+    this.created_at = this.createdAt;
+    this.expiresAt = options?.expiresAt ?? options?.expires_at;
+    this.expires_at = this.expiresAt;
+    this.nextPollAt = options?.nextPollAt ?? options?.next_poll_at;
+    this.next_poll_at = this.nextPollAt;
+    this.source = options?.source ?? options?.requestSource ?? options?.request_source;
+    this.requestSource = options?.requestSource ?? options?.request_source ?? this.source;
+    this.request_source = this.requestSource;
+    this.requestId = options?.requestId ?? options?.request_id;
+    this.request_id = this.requestId;
+    this.requiredCredits = options?.requiredCredits ?? options?.required_credits;
+    this.required_credits = this.requiredCredits;
+    this.creditsRemaining = options?.creditsRemaining ?? options?.credits_remaining ?? options?.remainingCredits ?? options?.remaining_credits;
+    this.credits_remaining = this.creditsRemaining;
+    this.remainingCredits = this.creditsRemaining;
+    this.remaining_credits = this.creditsRemaining;
+  }
+  static fromResponse(status, body, options) {
+    return new _PuppetryError(status, body.error, body.message, body.details, {
+      ...options,
+      ...retryMetadataFromApiError(body),
+      ...creditReadinessMetadataFromApiError(body),
+      ...jobCorrelationMetadataFromApiError(body)
+    });
+  }
+};
+var PuppetryTimeoutError = class extends PuppetryError {
+  constructor(timeoutMs) {
+    super(408, "timeout", `Request timed out after ${timeoutMs}ms`);
+    this.name = "PuppetryTimeoutError";
+  }
+};
+function retryMetadataFromApiError(body) {
+  const readinessDetails = objectFromKeys(
+    body.details,
+    "video_generation",
+    "videoGeneration"
+  );
+  const readinessBlocker = firstObjectFromArrayKeys(
+    readinessDetails,
+    "blockers"
+  );
+  const retryable = typeof body.retryable === "boolean" ? body.retryable : typeof body.details?.retryable === "boolean" ? body.details.retryable : typeof readinessDetails?.retryable === "boolean" ? readinessDetails.retryable : typeof readinessBlocker?.retryable === "boolean" ? readinessBlocker.retryable : void 0;
+  const retryBlockedReason = stringFromAliases(body, "retryBlockedReason", "retry_blocked_reason") ?? stringFromAliases(
+    body.details,
+    "retryBlockedReason",
+    "retry_blocked_reason"
+  ) ?? stringFromAliases(
+    readinessDetails,
+    "retryBlockedReason",
+    "retry_blocked_reason"
+  ) ?? stringFromAliases(
+    readinessBlocker,
+    "retryBlockedReason",
+    "retry_blocked_reason"
+  ) ?? stringFromKeys(readinessBlocker, "reason", "code") ?? stringFromKeys(readinessDetails, "reason");
+  const retryBlockCode = stringFromAliases(body, "retryBlockCode", "retry_block_code") ?? stringFromAliases(body.details, "retryBlockCode", "retry_block_code") ?? stringFromAliases(readinessDetails, "retryBlockCode", "retry_block_code") ?? stringFromAliases(readinessBlocker, "retryBlockCode", "retry_block_code") ?? stringFromKeys(readinessBlocker, "code");
+  return {
+    ...retryable !== void 0 ? { retryable } : {},
+    ...retryBlockedReason ? {
+      retry_blocked_reason: retryBlockedReason,
+      retryBlockedReason
+    } : {},
+    ...retryBlockCode ? {
+      retry_block_code: retryBlockCode,
+      retryBlockCode
+    } : {}
+  };
+}
+function jobCorrelationMetadataFromApiError(body) {
+  const readinessDetails = objectFromKeys(
+    body.details,
+    "video_generation",
+    "videoGeneration"
+  );
+  const object = stringFromKeys(body, "object") ?? stringFromKeys(body.details, "object");
+  const jobId = stringFromKeys(body, "jobId", "job_id", "id") ?? stringFromKeys(body.details, "jobId", "job_id", "id");
+  const operationId = stringFromKeys(body, "operationId", "operation_id") ?? stringFromKeys(body.details, "operationId", "operation_id");
+  const taskId = stringFromKeys(body, "taskId", "task_id") ?? stringFromKeys(body.details, "taskId", "task_id") ?? jobId;
+  const bodyStatusUrl = stringFromKeys(body, "statusUrl", "status_url") ?? stringFromKeys(body.details, "statusUrl", "status_url");
+  const bodyContentLocation = stringFromKeys(body, "contentLocation", "content_location") ?? stringFromKeys(body.details, "contentLocation", "content_location");
+  const statusUrl = bodyStatusUrl ?? bodyContentLocation;
+  const contentLocation = bodyContentLocation ?? bodyStatusUrl;
+  const createdAt = stringFromKeys(body, "createdAt", "created_at") ?? stringFromKeys(body.details, "createdAt", "created_at");
+  const expiresAt = stringFromKeys(body, "expiresAt", "expires_at") ?? stringFromKeys(body.details, "expiresAt", "expires_at");
+  const nextPollAt = stringFromKeys(body, "nextPollAt", "next_poll_at") ?? stringFromKeys(body.details, "nextPollAt", "next_poll_at") ?? stringFromKeys(readinessDetails, "nextPollAt", "next_poll_at");
+  const source = stringFromKeys(body, "source") ?? stringFromKeys(body.details, "source");
+  const requestSource = stringFromKeys(body, "requestSource", "request_source") ?? stringFromKeys(body.details, "requestSource", "request_source") ?? source;
+  const requestId = stringFromKeys(body, "requestId", "request_id") ?? stringFromKeys(body.details, "requestId", "request_id") ?? stringFromKeys(readinessDetails, "requestId", "request_id");
+  const credits = statusCreditsFromKeys(body, "credits") ?? statusCreditsFromKeys(body.details, "credits");
+  const creationCredits = creationCreditsFromKeys(body, "creationCredits", "creation_credits") ?? creationCreditsFromKeys(
+    body.details,
+    "creationCredits",
+    "creation_credits"
+  );
+  return {
+    ...object ? { object } : {},
+    ...jobId ? { id: jobId, job_id: jobId, jobId } : {},
+    ...operationId ? { operation_id: operationId, operationId } : {},
+    ...taskId ? { task_id: taskId, taskId } : {},
+    ...statusUrl ? { status_url: statusUrl, statusUrl } : {},
+    ...contentLocation ? { content_location: contentLocation, contentLocation } : {},
+    ...createdAt ? { created_at: createdAt, createdAt } : {},
+    ...expiresAt ? { expires_at: expiresAt, expiresAt } : {},
+    ...nextPollAt ? { next_poll_at: nextPollAt, nextPollAt } : {},
+    ...source ? { source } : {},
+    ...requestSource ? { request_source: requestSource, requestSource } : {},
+    ...requestId ? { request_id: requestId, requestId } : {},
+    ...credits ? { credits } : {},
+    ...creationCredits ? { creation_credits: creationCredits, creationCredits } : {}
+  };
+}
+function creditReadinessMetadataFromApiError(body) {
+  const readinessDetails = objectFromKeys(
+    body.details,
+    "video_generation",
+    "videoGeneration"
+  );
+  const readinessBlocker = firstObjectFromArrayKeys(
+    readinessDetails,
+    "blockers"
+  );
+  const requiredCredits = numberFromKeys(body, "requiredCredits", "required_credits") ?? numberFromKeys(body.details, "requiredCredits", "required_credits") ?? numberFromKeys(readinessDetails, "requiredCredits", "required_credits") ?? numberFromKeys(readinessBlocker, "requiredCredits", "required_credits");
+  const creditsRemaining = numberFromKeys(
+    body,
+    "creditsRemaining",
+    "credits_remaining",
+    "remainingCredits",
+    "remaining_credits"
+  ) ?? numberFromKeys(
+    body.details,
+    "creditsRemaining",
+    "credits_remaining",
+    "remainingCredits",
+    "remaining_credits"
+  ) ?? numberFromKeys(readinessDetails, "creditsRemaining", "credits_remaining") ?? numberFromKeys(
+    readinessBlocker,
+    "creditsRemaining",
+    "credits_remaining",
+    "remainingCredits",
+    "remaining_credits"
+  );
+  return {
+    ...requiredCredits !== void 0 ? { required_credits: requiredCredits, requiredCredits } : {},
+    ...creditsRemaining !== void 0 ? {
+      credits_remaining: creditsRemaining,
+      creditsRemaining,
+      remaining_credits: creditsRemaining,
+      remainingCredits: creditsRemaining
+    } : {}
+  };
+}
+function stringFromAliases(record, camelKey, snakeKey) {
+  return stringFromKeys(record, camelKey, snakeKey);
+}
+function stringFromKeys(record, ...keys) {
+  if (!record) return void 0;
+  const source = record;
+  const value = keys.map((key) => source[key]).find((item) => item !== void 0);
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed || void 0;
+}
+function objectFromKeys(record, ...keys) {
+  if (!record) return void 0;
+  const source = record;
+  const value = keys.map((key) => source[key]).find((item) => item !== void 0);
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  return value;
+}
+function statusCreditsFromKeys(record, ...keys) {
+  const value = objectFromKeys(record, ...keys);
+  if (!value) return void 0;
+  const charged = numberFromKeys(value, "charged");
+  const remaining = nullableNumberFromKeys(value, "remaining");
+  if (charged === void 0 || remaining === void 0) return void 0;
+  return { charged, remaining };
+}
+function creationCreditsFromKeys(record, ...keys) {
+  const value = objectFromKeys(record, ...keys);
+  if (!value) return void 0;
+  const charged = numberFromKeys(value, "charged");
+  const remainingAfterDebit = nullableNumberFromKeys(
+    value,
+    "remainingAfterDebit",
+    "remaining_after_debit"
+  );
+  if (charged === void 0 || remainingAfterDebit === void 0) {
+    return void 0;
+  }
+  return {
+    charged,
+    remaining_after_debit: remainingAfterDebit,
+    remainingAfterDebit
+  };
+}
+function numberFromKeys(record, ...keys) {
+  if (!record) return void 0;
+  const source = record;
+  const value = keys.map((key) => source[key]).find((item) => item !== void 0);
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function nullableNumberFromKeys(record, ...keys) {
+  if (!record) return void 0;
+  const source = record;
+  const value = keys.map((key) => source[key]).find((item) => item !== void 0);
+  if (value === null) return null;
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function firstObjectFromArrayKeys(record, ...keys) {
+  if (!record) return void 0;
+  const source = record;
+  const value = keys.map((key) => source[key]).find((item) => Array.isArray(item));
+  const first = Array.isArray(value) ? value[0] : void 0;
+  if (!first || typeof first !== "object" || Array.isArray(first)) {
+    return void 0;
+  }
+  return first;
+}
+var PuppetryAuthError = class extends PuppetryError {
+  constructor(message = "Invalid or missing API key") {
+    super(401, "unauthorized", message);
+    this.name = "PuppetryAuthError";
+  }
+};
+var PuppetryRateLimitError = class _PuppetryRateLimitError extends PuppetryError {
+  constructor(retryAfter, message = "Rate limit exceeded", details, code = "rate_limited", options) {
+    super(429, code, message, details, {
+      ...options,
+      retryAfter,
+      retryable: options?.retryable ?? (typeof details?.retryable === "boolean" ? details.retryable : void 0)
+    });
+    this.name = "PuppetryRateLimitError";
+  }
+  static fromRateLimitResponse(body, options) {
+    return new _PuppetryRateLimitError(
+      options?.retryAfter,
+      body.message,
+      body.details,
+      body.error || "rate_limited",
+      {
+        ...options,
+        ...retryMetadataFromApiError(body),
+        ...creditReadinessMetadataFromApiError(body),
+        ...jobCorrelationMetadataFromApiError(body)
+      }
+    );
+  }
+};
+var PuppetryNetworkError = class extends PuppetryError {
+  constructor(message = "Network request failed") {
+    super(0, "network_error", message);
+    this.name = "PuppetryNetworkError";
+  }
+};
+function puppetryErrorData(err) {
+  const videoGenerationReadiness = videoGenerationReadinessFromDetails(
+    err.details
+  );
+  return {
+    status: err.status,
+    statusCode: err.status,
+    code: err.code,
+    message: err.message,
+    ...err.object ? { object: err.object } : {},
+    ...err.retryAfter !== void 0 ? {
+      retry_after_seconds: err.retryAfter,
+      retryAfterSeconds: err.retryAfter,
+      retryAfter: err.retryAfter
+    } : {},
+    ...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.jobId ? { id: err.jobId, job_id: err.jobId, jobId: err.jobId } : {},
+    ...err.operationId ? { operation_id: err.operationId, operationId: err.operationId } : {},
+    ...err.taskId ? { task_id: err.taskId, taskId: err.taskId } : {},
+    ...err.statusUrl ? { status_url: err.statusUrl, statusUrl: err.statusUrl } : {},
+    ...err.contentLocation ? {
+      content_location: err.contentLocation,
+      contentLocation: err.contentLocation
+    } : {},
+    ...err.createdAt ? { created_at: err.createdAt, createdAt: err.createdAt } : {},
+    ...err.expiresAt ? { expires_at: err.expiresAt, expiresAt: err.expiresAt } : {},
+    ...err.nextPollAt ? { next_poll_at: err.nextPollAt, nextPollAt: err.nextPollAt } : {},
+    ...err.source ? {
+      source: err.source,
+      request_source: err.requestSource ?? err.source,
+      requestSource: err.requestSource ?? err.source
+    } : {},
+    ...err.requestId ? { request_id: err.requestId, requestId: err.requestId } : {},
+    ...err.requiredCredits !== void 0 ? {
+      required_credits: err.requiredCredits,
+      requiredCredits: err.requiredCredits
+    } : {},
+    ...err.creditsRemaining !== void 0 ? {
+      credits_remaining: err.creditsRemaining,
+      creditsRemaining: err.creditsRemaining,
+      remaining_credits: err.creditsRemaining,
+      remainingCredits: err.creditsRemaining
+    } : {},
+    ...videoGenerationReadiness ? {
+      video_generation: videoGenerationReadiness,
+      videoGeneration: videoGenerationReadiness
+    } : {},
+    ...err.details !== void 0 ? { details: err.details } : {}
+  };
+}
+function videoGenerationReadinessFromDetails(details) {
+  const readiness = objectFromKeys(
+    details,
+    "video_generation",
+    "videoGeneration"
+  );
+  if (!readiness) return void 0;
+  const canCreate = booleanFromKeys(readiness, "canCreate", "can_create");
+  const requiredCredits = numberFromKeys(
+    readiness,
+    "requiredCredits",
+    "required_credits"
+  );
+  const creditsRemaining = numberFromKeys(
+    readiness,
+    "creditsRemaining",
+    "credits_remaining"
+  );
+  const retryAfterSeconds = numberFromKeys(
+    readiness,
+    "retryAfterSeconds",
+    "retryAfter",
+    "retry_after_seconds"
+  );
+  const nextPollAt = stringFromKeys(readiness, "nextPollAt", "next_poll_at");
+  return {
+    ...readiness,
+    ...canCreate === void 0 ? {} : { can_create: canCreate, canCreate },
+    ...requiredCredits === void 0 ? {} : { required_credits: requiredCredits, requiredCredits },
+    ...creditsRemaining === void 0 ? {} : { credits_remaining: creditsRemaining, creditsRemaining },
+    ...retryAfterSeconds === void 0 ? {} : {
+      retry_after_seconds: retryAfterSeconds,
+      retryAfter: retryAfterSeconds,
+      retryAfterSeconds
+    },
+    ...nextPollAt === void 0 ? {} : { next_poll_at: nextPollAt, nextPollAt }
+  };
+}
+function booleanFromKeys(record, ...keys) {
+  if (!record) return void 0;
+  const source = record;
+  const value = keys.map((key) => source[key]).find((item) => item !== void 0);
+  return typeof value === "boolean" ? value : void 0;
+}
+
+// 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);
+  }
+};
+
+// src/agentTools.ts
+var imageUrlAliasRequirement = {
+  anyOf: [
+    { required: ["image_url"] },
+    { required: ["imageUrl"] },
+    { required: ["image"] },
+    { required: ["portrait"] },
+    { required: ["portrait_url"] },
+    { required: ["portraitUrl"] },
+    { required: ["avatar"] },
+    { required: ["avatarUrl"] },
+    { required: ["avatar_url"] },
+    { required: ["photo"] },
+    { required: ["photoUrl"] },
+    { required: ["photo_url"] }
+  ]
+};
+var textScriptAliasRequirement = {
+  anyOf: [
+    { required: ["text"] },
+    { required: ["script"] },
+    { required: ["prompt"] }
+  ]
+};
+var audioUrlAliasRequirement = {
+  anyOf: [
+    { required: ["audio_url"] },
+    { required: ["audioUrl"] },
+    { required: ["audio"] }
+  ]
+};
+var audioUploadReservationRequirement = {
+  allOf: [
+    {
+      anyOf: [
+        { required: ["mime_type"] },
+        { required: ["mimeType"] },
+        { required: ["contentType"] }
+      ]
+    },
+    {
+      anyOf: [
+        { required: ["content_length"] },
+        { required: ["contentLength"] },
+        { required: ["sizeBytes"] },
+        { required: ["file_size"] },
+        { required: ["fileSize"] }
+      ]
+    }
+  ]
+};
+var jobIdAliasRequirement = {
+  anyOf: [
+    { required: ["jobId"] },
+    { required: ["job_id"] },
+    { required: ["task_id"] },
+    { required: ["taskId"] },
+    { required: ["id"] }
+  ]
+};
+var waitOptionsProperties = {
+  intervalMs: {
+    type: "number",
+    description: "Polling interval in milliseconds. Defaults to 2000."
+  },
+  timeoutMs: {
+    type: "number",
+    description: "Maximum wait time in milliseconds. Defaults to 300000."
+  },
+  initialDelayMs: {
+    type: "number",
+    description: "Optional delay before the first status request, useful with Retry-After."
+  }
+};
+var readinessPreflightProperties = {
+  preflightReadiness: {
+    type: "boolean",
+    description: "Check video credits and active slots before queueing. Defaults to false on create-only tools and true on create-and-wait tools."
+  },
+  preflight_readiness: {
+    type: "boolean",
+    description: "Snake_case alias for preflightReadiness."
+  }
+};
+function resolveJobIdAlias(input) {
+  const aliases = [
+    { name: "jobId", value: input.jobId },
+    { name: "job_id", value: input.job_id },
+    { name: "task_id", value: input.task_id },
+    { name: "taskId", value: input.taskId },
+    { name: "id", value: input.id }
+  ];
+  const provided = aliases.filter((alias) => alias.value);
+  const first = provided[0];
+  if (!first?.value) {
+    throw new PuppetryError(
+      400,
+      "invalid_request",
+      "Pass one of jobId, job_id, task_id, taskId, id"
+    );
+  }
+  const conflictingAlias = provided.find(
+    (alias) => alias.value !== first.value
+  );
+  if (conflictingAlias) {
+    throw new PuppetryError(
+      400,
+      "invalid_request",
+      "Pass one of jobId, job_id, task_id, taskId, id, not conflicting values"
+    );
+  }
+  return first.value;
+}
+var PUPPETRY_AGENT_TOOLS = [
+  {
+    name: "puppetry_create_video_from_text",
+    resource: "videos.createFromText",
+    description: "Create a talking-head video from a portrait image and text.",
+    inputSchema: {
+      type: "object",
+      required: [],
+      allOf: [textScriptAliasRequirement, imageUrlAliasRequirement],
+      properties: {
+        text: {
+          type: "string",
+          description: "Script to synthesize and animate."
+        },
+        script: {
+          type: "string",
+          description: "Alias for text script to synthesize and animate."
+        },
+        prompt: {
+          type: "string",
+          description: "Alias for text script, useful for prompt-oriented agents."
+        },
+        image_url: {
+          type: "string",
+          description: "Hosted portrait image URL."
+        },
+        imageUrl: {
+          type: "string",
+          description: "Hosted portrait image URL alias."
+        },
+        image: {
+          type: "string",
+          description: "Hosted portrait image URL alias for agents."
+        },
+        portrait: {
+          type: "string",
+          description: "Deprecated hosted portrait image URL alias."
+        },
+        portrait_url: {
+          type: "string",
+          description: "Hosted portrait image URL snake_case alias."
+        },
+        portraitUrl: {
+          type: "string",
+          description: "Hosted portrait image URL alias."
+        },
+        avatar: {
+          type: "string",
+          description: "Hosted avatar image URL alias."
+        },
+        avatarUrl: {
+          type: "string",
+          description: "Hosted avatar image URL alias."
+        },
+        avatar_url: {
+          type: "string",
+          description: "Hosted avatar image URL snake_case alias."
+        },
+        photo: {
+          type: "string",
+          description: "Hosted photo image URL alias."
+        },
+        photoUrl: {
+          type: "string",
+          description: "Hosted photo image URL alias."
+        },
+        photo_url: {
+          type: "string",
+          description: "Hosted photo image URL snake_case alias."
+        },
+        voice_id: {
+          type: "string",
+          description: "Optional Puppetry voice ID from voices.listPuppetry()."
+        },
+        voiceId: {
+          type: "string",
+          description: "Optional Puppetry voice ID alias."
+        },
+        voice: {
+          type: "string",
+          description: "Optional Puppetry voice ID alias for SDK examples."
+        },
+        language: {
+          type: "string",
+          description: "Optional language code, such as en."
+        },
+        expressiveness: {
+          type: "number",
+          description: "Optional animation expressiveness from 0 to 2."
+        },
+        idempotencyKey: {
+          type: "string",
+          description: "Optional retry key sent as Idempotency-Key."
+        },
+        idempotency_key: {
+          type: "string",
+          description: "Optional retry key alias sent as Idempotency-Key."
+        },
+        ...readinessPreflightProperties
+      }
+    }
+  },
+  {
+    name: "puppetry_create_video_from_audio",
+    resource: "videos.createFromAudio",
+    description: "Create a talking-head video from a portrait image and audio.",
+    inputSchema: {
+      type: "object",
+      required: [],
+      allOf: [imageUrlAliasRequirement, audioUrlAliasRequirement],
+      properties: {
+        audio_url: {
+          type: "string",
+          description: "Hosted audio URL."
+        },
+        audioUrl: {
+          type: "string",
+          description: "Hosted audio URL alias."
+        },
+        audio: {
+          type: "string",
+          description: "Hosted audio URL alias for agents."
+        },
+        image_url: {
+          type: "string",
+          description: "Hosted portrait image URL."
+        },
+        imageUrl: {
+          type: "string",
+          description: "Hosted portrait image URL alias."
+        },
+        image: {
+          type: "string",
+          description: "Hosted portrait image URL alias for agents."
+        },
+        portrait: {
+          type: "string",
+          description: "Deprecated hosted portrait image URL alias."
+        },
+        portrait_url: {
+          type: "string",
+          description: "Hosted portrait image URL snake_case alias."
+        },
+        portraitUrl: {
+          type: "string",
+          description: "Hosted portrait image URL alias."
+        },
+        avatar: {
+          type: "string",
+          description: "Hosted avatar image URL alias."
+        },
+        avatarUrl: {
+          type: "string",
+          description: "Hosted avatar image URL alias."
+        },
+        avatar_url: {
+          type: "string",
+          description: "Hosted avatar image URL snake_case alias."
+        },
+        photo: {
+          type: "string",
+          description: "Hosted photo image URL alias."
+        },
+        photoUrl: {
+          type: "string",
+          description: "Hosted photo image URL alias."
+        },
+        photo_url: {
+          type: "string",
+          description: "Hosted photo image URL snake_case alias."
+        },
+        expressiveness: {
+          type: "number",
+          description: "Optional animation expressiveness from 0 to 2."
+        },
+        idempotencyKey: {
+          type: "string",
+          description: "Optional retry key sent as Idempotency-Key."
+        },
+        idempotency_key: {
+          type: "string",
+          description: "Optional retry key alias sent as Idempotency-Key."
+        },
+        ...readinessPreflightProperties
+      }
+    }
+  },
+  {
+    name: "puppetry_create_video_from_text_and_wait",
+    resource: "videos.createFromText.waitForCompletion",
+    description: "Create a talking-head video from text and wait for completed or failed status.",
+    inputSchema: {
+      type: "object",
+      required: [],
+      allOf: [textScriptAliasRequirement, imageUrlAliasRequirement],
+      properties: {
+        text: {
+          type: "string",
+          description: "Script to synthesize and animate."
+        },
+        script: {
+          type: "string",
+          description: "Alias for text script to synthesize and animate."
+        },
+        prompt: {
+          type: "string",
+          description: "Alias for text script, useful for prompt-oriented agents."
+        },
+        image_url: {
+          type: "string",
+          description: "Hosted portrait image URL."
+        },
+        imageUrl: {
+          type: "string",
+          description: "Hosted portrait image URL alias."
+        },
+        image: {
+          type: "string",
+          description: "Hosted portrait image URL alias for agents."
+        },
+        portrait: {
+          type: "string",
+          description: "Deprecated hosted portrait image URL alias."
+        },
+        portrait_url: {
+          type: "string",
+          description: "Hosted portrait image URL snake_case alias."
+        },
+        portraitUrl: {
+          type: "string",
+          description: "Hosted portrait image URL alias."
+        },
+        avatar: {
+          type: "string",
+          description: "Hosted avatar image URL alias."
+        },
+        avatarUrl: {
+          type: "string",
+          description: "Hosted avatar image URL alias."
+        },
+        avatar_url: {
+          type: "string",
+          description: "Hosted avatar image URL snake_case alias."
+        },
+        photo: {
+          type: "string",
+          description: "Hosted photo image URL alias."
+        },
+        photoUrl: {
+          type: "string",
+          description: "Hosted photo image URL alias."
+        },
+        photo_url: {
+          type: "string",
+          description: "Hosted photo image URL snake_case alias."
+        },
+        voice_id: {
+          type: "string",
+          description: "Optional Puppetry voice ID from voices.listPuppetry()."
+        },
+        voiceId: {
+          type: "string",
+          description: "Optional Puppetry voice ID alias."
+        },
+        voice: {
+          type: "string",
+          description: "Optional Puppetry voice ID alias for SDK examples."
+        },
+        language: {
+          type: "string",
+          description: "Optional language code, such as en."
+        },
+        expressiveness: {
+          type: "number",
+          description: "Optional animation expressiveness from 0 to 2."
+        },
+        idempotencyKey: {
+          type: "string",
+          description: "Optional retry key sent as Idempotency-Key."
+        },
+        idempotency_key: {
+          type: "string",
+          description: "Optional retry key alias sent as Idempotency-Key."
+        },
+        ...readinessPreflightProperties,
+        ...waitOptionsProperties
+      }
+    }
+  },
+  {
+    name: "puppetry_create_video_from_audio_and_wait",
+    resource: "videos.createFromAudio.waitForCompletion",
+    description: "Create a talking-head video from audio and wait for completed or failed status.",
+    inputSchema: {
+      type: "object",
+      required: [],
+      allOf: [imageUrlAliasRequirement, audioUrlAliasRequirement],
+      properties: {
+        audio_url: {
+          type: "string",
+          description: "Hosted audio URL."
+        },
+        audioUrl: {
+          type: "string",
+          description: "Hosted audio URL alias."
+        },
+        audio: {
+          type: "string",
+          description: "Hosted audio URL alias for agents."
+        },
+        image_url: {
+          type: "string",
+          description: "Hosted portrait image URL."
+        },
+        imageUrl: {
+          type: "string",
+          description: "Hosted portrait image URL alias."
+        },
+        image: {
+          type: "string",
+          description: "Hosted portrait image URL alias for agents."
+        },
+        portrait: {
+          type: "string",
+          description: "Deprecated hosted portrait image URL alias."
+        },
+        portrait_url: {
+          type: "string",
+          description: "Hosted portrait image URL snake_case alias."
+        },
+        portraitUrl: {
+          type: "string",
+          description: "Hosted portrait image URL alias."
+        },
+        avatar: {
+          type: "string",
+          description: "Hosted avatar image URL alias."
+        },
+        avatarUrl: {
+          type: "string",
+          description: "Hosted avatar image URL alias."
+        },
+        avatar_url: {
+          type: "string",
+          description: "Hosted avatar image URL snake_case alias."
+        },
+        photo: {
+          type: "string",
+          description: "Hosted photo image URL alias."
+        },
+        photoUrl: {
+          type: "string",
+          description: "Hosted photo image URL alias."
+        },
+        photo_url: {
+          type: "string",
+          description: "Hosted photo image URL snake_case alias."
+        },
+        expressiveness: {
+          type: "number",
+          description: "Optional animation expressiveness from 0 to 2."
+        },
+        idempotencyKey: {
+          type: "string",
+          description: "Optional retry key sent as Idempotency-Key."
+        },
+        idempotency_key: {
+          type: "string",
+          description: "Optional retry key alias sent as Idempotency-Key."
+        },
+        ...readinessPreflightProperties,
+        ...waitOptionsProperties
+      }
+    }
+  },
+  {
+    name: "puppetry_create_audio_upload_url",
+    resource: "uploads.createAudioUrl",
+    description: "Reserve a Puppetry-hosted signed audio upload URL for audio-to-video workflows.",
+    inputSchema: {
+      type: "object",
+      required: [],
+      ...audioUploadReservationRequirement,
+      properties: {
+        mime_type: {
+          type: "string",
+          description: "Audio MIME type, such as audio/wav, audio/mpeg, or audio/mp4."
+        },
+        mimeType: {
+          type: "string",
+          description: "Audio MIME type alias."
+        },
+        contentType: {
+          type: "string",
+          description: "Audio MIME type alias for signed-upload callers."
+        },
+        content_length: {
+          type: "number",
+          description: "Exact byte length of the audio file to upload."
+        },
+        contentLength: {
+          type: "number",
+          description: "Exact byte length alias."
+        },
+        sizeBytes: {
+          type: "number",
+          description: "Exact byte length alias for agent/runtime callers."
+        },
+        file_size: {
+          type: "number",
+          description: "Exact byte length alias for upload metadata callers."
+        },
+        fileSize: {
+          type: "number",
+          description: "Exact byte length alias for upload metadata callers."
+        },
+        idempotencyKey: {
+          type: "string",
+          description: "Optional retry key sent as Idempotency-Key."
+        },
+        idempotency_key: {
+          type: "string",
+          description: "Optional retry key alias sent as Idempotency-Key."
+        }
+      }
+    }
+  },
+  {
+    name: "puppetry_lipsync",
+    resource: "videos.createFromAudio",
+    description: "Lip sync a portrait or puppet with an existing audio URL.",
+    inputSchema: {
+      type: "object",
+      required: [],
+      allOf: [imageUrlAliasRequirement, audioUrlAliasRequirement],
+      properties: {
+        audio_url: {
+          type: "string",
+          description: "Hosted audio URL."
+        },
+        audioUrl: {
+          type: "string",
+          description: "Hosted audio URL alias."
+        },
+        audio: {
+          type: "string",
+          description: "Hosted audio URL alias for agents."
+        },
+        image_url: {
+          type: "string",
+          description: "Hosted portrait image URL."
+        },
+        imageUrl: {
+          type: "string",
+          description: "Hosted portrait image URL alias."
+        },
+        image: {
+          type: "string",
+          description: "Hosted portrait image URL alias for agents."
+        },
+        portrait: {
+          type: "string",
+          description: "Deprecated hosted portrait image URL alias."
+        },
+        portrait_url: {
+          type: "string",
+          description: "Hosted portrait image URL snake_case alias."
+        },
+        portraitUrl: {
+          type: "string",
+          description: "Hosted portrait image URL alias."
+        },
+        avatar: {
+          type: "string",
+          description: "Hosted avatar image URL alias."
+        },
+        avatarUrl: {
+          type: "string",
+          description: "Hosted avatar image URL alias."
+        },
+        avatar_url: {
+          type: "string",
+          description: "Hosted avatar image URL snake_case alias."
+        },
+        photo: {
+          type: "string",
+          description: "Hosted photo image URL alias."
+        },
+        photoUrl: {
+          type: "string",
+          description: "Hosted photo image URL alias."
+        },
+        photo_url: {
+          type: "string",
+          description: "Hosted photo image URL snake_case alias."
+        },
+        idempotencyKey: {
+          type: "string",
+          description: "Optional retry key sent as Idempotency-Key."
+        },
+        idempotency_key: {
+          type: "string",
+          description: "Optional retry key alias sent as Idempotency-Key."
+        }
+      }
+    }
+  },
+  {
+    name: "puppetry_list_voices",
+    resource: "voices.listPuppetry",
+    description: "List Puppetry-hosted voices with preview text and audio.",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  },
+  {
+    name: "puppetry_get_job_status",
+    resource: "jobs.get",
+    description: "Fetch a generated video job by ID.",
+    inputSchema: {
+      type: "object",
+      required: [],
+      ...jobIdAliasRequirement,
+      properties: {
+        jobId: {
+          type: "string",
+          description: "Generated video job ID."
+        },
+        job_id: {
+          type: "string",
+          description: "Generated video job ID alias."
+        },
+        task_id: {
+          type: "string",
+          description: "Generated video task ID alias."
+        },
+        taskId: {
+          type: "string",
+          description: "Generated video task ID camelCase alias."
+        },
+        id: {
+          type: "string",
+          description: "Generated video ID alias."
+        }
+      }
+    }
+  },
+  {
+    name: "puppetry_wait_for_video",
+    resource: "videos.waitForCompletion",
+    description: "Poll a generated video job until it reaches completed or failed.",
+    inputSchema: {
+      type: "object",
+      required: [],
+      ...jobIdAliasRequirement,
+      properties: {
+        jobId: {
+          type: "string",
+          description: "Generated video job ID."
+        },
+        job_id: {
+          type: "string",
+          description: "Generated video job ID alias."
+        },
+        task_id: {
+          type: "string",
+          description: "Generated video task ID alias."
+        },
+        taskId: {
+          type: "string",
+          description: "Generated video task ID camelCase alias."
+        },
+        id: {
+          type: "string",
+          description: "Generated video ID alias."
+        },
+        intervalMs: {
+          type: "number",
+          description: "Polling interval in milliseconds. Defaults to 2000."
+        },
+        timeoutMs: {
+          type: "number",
+          description: "Maximum wait time in milliseconds. Defaults to 300000."
+        },
+        initialDelayMs: {
+          type: "number",
+          description: "Optional delay before the first status request, useful with Retry-After."
+        }
+      }
+    }
+  },
+  {
+    name: "puppetry_get_video_readiness",
+    resource: "videos.getReadiness",
+    description: "Check whether credit-backed video creation can run now, including credit and active-slot blockers.",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  },
+  {
+    name: "puppetry_get_quota",
+    resource: "quota.get",
+    description: "Check current plan, credit usage, and remaining credits.",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  }
+];
+async function callPuppetryAgentTool(client, name, input) {
+  switch (name) {
+    case "puppetry_create_video_from_text":
+      return createTextVideo(
+        client,
+        input
+      );
+    case "puppetry_create_video_from_audio":
+      return createAudioVideo(
+        client,
+        input
+      );
+    case "puppetry_create_video_from_text_and_wait":
+      return createTextVideoAndWait(
+        client,
+        input
+      );
+    case "puppetry_create_video_from_audio_and_wait":
+      return createAudioVideoAndWait(
+        client,
+        input
+      );
+    case "puppetry_create_audio_upload_url":
+      return client.uploads.createAudioUrl(
+        input
+      );
+    case "puppetry_lipsync":
+      return client.videos.createFromAudio(
+        input
+      );
+    case "puppetry_list_voices":
+      return client.voices.listPuppetry();
+    case "puppetry_get_job_status":
+      return client.jobs.get(
+        resolveJobIdAlias(
+          input
+        )
+      );
+    case "puppetry_wait_for_video": {
+      const waitInput = input;
+      return client.videos.waitForCompletion(resolveJobIdAlias(waitInput), {
+        intervalMs: waitInput.intervalMs,
+        timeoutMs: waitInput.timeoutMs,
+        initialDelayMs: waitInput.initialDelayMs
+      });
+    }
+    case "puppetry_get_video_readiness":
+      return client.videos.getReadiness();
+    case "puppetry_get_quota":
+      return client.quota.get();
+    default:
+      throw new Error(`Unsupported Puppetry agent tool: ${String(name)}`);
+  }
+}
+async function createTextVideo(client, input) {
+  const readiness = await preflightVideoReadiness(client, input, false);
+  const job = await client.videos.createFromText(input);
+  return videoCreateResult(job, readiness);
+}
+async function createAudioVideo(client, input) {
+  const readiness = await preflightVideoReadiness(client, input, false);
+  const job = await client.videos.createFromAudio(input);
+  return videoCreateResult(job, readiness);
+}
+async function createTextVideoAndWait(client, input) {
+  const readiness = await preflightVideoReadiness(client, input, true);
+  const acceptedJob = await client.videos.createFromText(input);
+  const wait = measuredWaitOptions(input);
+  const finalJob = await acceptedJob.waitForCompletion(wait.options);
+  return videoFlowResult(acceptedJob, finalJob, wait.summary(), readiness);
+}
+async function createAudioVideoAndWait(client, input) {
+  const readiness = await preflightVideoReadiness(client, input, true);
+  const acceptedJob = await client.videos.createFromAudio(input);
+  const wait = measuredWaitOptions(input);
+  const finalJob = await acceptedJob.waitForCompletion(wait.options);
+  return videoFlowResult(acceptedJob, finalJob, wait.summary(), readiness);
+}
+async function preflightVideoReadiness(client, input, defaultValue) {
+  const shouldPreflight = resolveReadinessPreflight(input, defaultValue);
+  if (!shouldPreflight) return void 0;
+  return client.videos.ensureReady();
+}
+function resolveReadinessPreflight(input, defaultValue) {
+  const aliases = [
+    { name: "preflightReadiness", value: input.preflightReadiness },
+    { name: "preflight_readiness", value: input.preflight_readiness }
+  ].flatMap((alias) => {
+    if (alias.value === void 0 || alias.value === null) return [];
+    if (typeof alias.value !== "boolean") {
+      throw new PuppetryError(
+        400,
+        "invalid_request",
+        `${alias.name} must be a boolean`
+      );
+    }
+    return [{ name: alias.name, value: alias.value }];
+  });
+  const first = aliases[0];
+  if (!first) return defaultValue;
+  for (const alias of aliases) {
+    if (alias.value !== first.value) {
+      throw new PuppetryError(
+        400,
+        "invalid_request",
+        "preflightReadiness and preflight_readiness must describe the same boolean value"
+      );
+    }
+  }
+  return first.value;
+}
+function measuredWaitOptions(input) {
+  const startedAt = Date.now();
+  let pollCount = 0;
+  let retryCount = 0;
+  let latestRetryingEvent;
+  const options = {
+    ...input.intervalMs === void 0 ? {} : { intervalMs: input.intervalMs },
+    ...input.timeoutMs === void 0 ? {} : { timeoutMs: input.timeoutMs },
+    ...input.initialDelayMs === void 0 ? {} : { initialDelayMs: input.initialDelayMs },
+    onPoll: () => {
+      pollCount += 1;
+    },
+    onRetrying: (event) => {
+      retryCount += 1;
+      latestRetryingEvent = event;
+    }
+  };
+  return {
+    options,
+    summary: () => ({
+      pollCount,
+      retryCount,
+      ...latestRetryingEvent === void 0 ? {} : { latestRetryingEvent },
+      durationMs: Date.now() - startedAt
+    })
+  };
+}
+function videoFlowResult(acceptedJob, finalJob, wait, readiness) {
+  const operationId = nonDefaultOperationId(finalJob) ?? nonDefaultOperationId(acceptedJob) ?? finalJob.operationId ?? finalJob.operation_id ?? acceptedJob.operationId ?? acceptedJob.operation_id ?? finalJob.id;
+  const requestId = finalJob.requestId ?? finalJob.request_id ?? acceptedJob.requestId ?? acceptedJob.request_id;
+  const videoUrl = finalJob.videoUrl ?? finalJob.video_url ?? finalJob.url;
+  const acceptedCredits = videoCreditEvidence(acceptedJob.credits);
+  const finalCredits = videoCreditEvidence(finalJob.credits);
+  const creationCredits = videoCreationCreditEvidence(finalJob) ?? videoCreationCreditEvidence(acceptedJob);
+  return {
+    object: "video_flow",
+    accepted_job: acceptedJob,
+    acceptedJob,
+    final_job: finalJob,
+    finalJob,
+    ...acceptedCredits === void 0 ? {} : { accepted_credits: acceptedCredits, acceptedCredits },
+    ...finalCredits === void 0 ? {} : {
+      final_credits: finalCredits,
+      finalCredits,
+      credits: finalCredits
+    },
+    ...creationCredits === void 0 ? {} : { creation_credits: creationCredits, creationCredits },
+    job_id: finalJob.id,
+    jobId: finalJob.id,
+    operation_id: operationId,
+    operationId,
+    ...requestId === void 0 ? {} : { request_id: requestId, requestId },
+    status: finalJob.status,
+    completed: finalJob.status === "completed",
+    ...readiness === void 0 ? {} : { readiness: videoReadinessEvidence(readiness) },
+    readiness_checked: readiness !== void 0,
+    readinessChecked: readiness !== void 0,
+    poll_count: wait.pollCount,
+    pollCount: wait.pollCount,
+    retry_count: wait.retryCount,
+    retryCount: wait.retryCount,
+    ...wait.latestRetryingEvent === void 0 ? {} : {
+      latest_retrying_event: wait.latestRetryingEvent,
+      latestRetryingEvent: wait.latestRetryingEvent
+    },
+    duration_ms: wait.durationMs,
+    durationMs: wait.durationMs,
+    ...videoUrl === void 0 ? {} : { video_url: videoUrl, videoUrl }
+  };
+}
+function videoCreateResult(job, readiness) {
+  const result = job;
+  result.readiness_checked = readiness !== void 0;
+  result.readinessChecked = readiness !== void 0;
+  if (readiness !== void 0) {
+    result.readiness = videoReadinessEvidence(readiness);
+  }
+  return result;
+}
+function videoCreditEvidence(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
+  };
+}
+function videoCreationCreditEvidence(job) {
+  const raw = job.creationCredits ?? job.creation_credits;
+  if (!raw || typeof raw !== "object") return void 0;
+  if (typeof raw.charged !== "number" || !Number.isFinite(raw.charged)) {
+    return void 0;
+  }
+  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
+  };
+}
+function videoReadinessEvidence(readiness) {
+  const canCreate = readiness.canCreate ?? readiness.can_create;
+  const requiredCredits = readiness.requiredCredits ?? readiness.required_credits;
+  const creditsRemaining = readiness.creditsRemaining ?? readiness.credits_remaining;
+  const concurrentJobs = readiness.concurrentJobs ?? readiness.concurrent_jobs;
+  const activeJobs = readiness.activeJobs ?? readiness.active_jobs;
+  const availableSlots = readiness.availableSlots ?? readiness.available_slots;
+  const activeJobExpiresInSeconds = readiness.activeJobExpiresInSeconds ?? readiness.active_job_expires_in_seconds;
+  const retryAfterSeconds = readiness.retryAfterSeconds ?? readiness.retryAfter ?? readiness.retry_after_seconds;
+  const nextPollAt = readiness.nextPollAt ?? readiness.next_poll_at;
+  return {
+    ...readiness,
+    can_create: canCreate,
+    canCreate,
+    required_credits: requiredCredits,
+    requiredCredits,
+    credits_remaining: creditsRemaining,
+    creditsRemaining,
+    ...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
+    },
+    ...retryAfterSeconds === void 0 ? {} : {
+      retry_after_seconds: retryAfterSeconds,
+      retryAfter: readiness.retryAfter ?? retryAfterSeconds,
+      retryAfterSeconds
+    },
+    ...nextPollAt === void 0 ? {} : { next_poll_at: nextPollAt, nextPollAt }
+  };
+}
+function nonDefaultOperationId(job) {
+  const operationId = job.operationId ?? job.operation_id;
+  return operationId && operationId !== job.id ? operationId : void 0;
+}
+async function safeCallPuppetryAgentTool(client, name, input) {
+  try {
+    return {
+      ok: true,
+      data: await callPuppetryAgentTool(client, name, input)
+    };
+  } catch (err) {
+    if (err instanceof PuppetryError) {
+      return {
+        ok: false,
+        error: puppetryErrorData(err)
+      };
+    }
+    return {
+      ok: false,
+      error: {
+        status: 500,
+        statusCode: 500,
+        code: "internal_error",
+        message: err instanceof Error ? err.message : "Internal error"
+      }
+    };
+  }
+}
+
+// src/mcp.ts
+var SERVER_INFO = {
+  name: "puppetry",
+  version: "0.1.0"
+};
+var TOOL_NAMES = new Set(
+  PUPPETRY_AGENT_TOOLS.map((tool) => tool.name)
+);
+async function handlePuppetryMcpRequest(client, request) {
+  if (request.id === void 0 && request.method === "notifications/initialized") {
+    return null;
+  }
+  try {
+    switch (request.method) {
+      case "initialize":
+        return success(request.id, {
+          protocolVersion: requestedProtocolVersion(request.params),
+          capabilities: { tools: {} },
+          serverInfo: SERVER_INFO
+        });
+      case "ping":
+        return success(request.id, {});
+      case "tools/list":
+        return success(request.id, {
+          tools: PUPPETRY_AGENT_TOOLS.map(
+            ({ name, description, inputSchema }) => ({
+              name,
+              description,
+              inputSchema
+            })
+          )
+        });
+      case "tools/call":
+        return success(request.id, await callTool(client, request.params));
+      default:
+        return error(request.id, -32601, `Method not found: ${request.method}`);
+    }
+  } catch (err) {
+    if (err instanceof PuppetryError) {
+      return error(request.id, -32603, err.message, puppetryErrorData(err));
+    }
+    return error(
+      request.id,
+      -32603,
+      err instanceof Error ? err.message : "Internal error"
+    );
+  }
+}
+async function callTool(client, params) {
+  if (!isObject(params) || typeof params.name !== "string") {
+    throw new Error("tools/call requires a tool name");
+  }
+  if (!TOOL_NAMES.has(params.name)) {
+    throw new Error(`Unsupported Puppetry MCP tool: ${params.name}`);
+  }
+  const result = await callPuppetryAgentTool(
+    client,
+    params.name,
+    isObject(params.arguments) ? params.arguments : {}
+  );
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2)
+      }
+    ]
+  };
+}
+function requestedProtocolVersion(params) {
+  if (isObject(params) && typeof params.protocolVersion === "string") {
+    return params.protocolVersion;
+  }
+  return "2024-11-05";
+}
+function success(id, result) {
+  return {
+    jsonrpc: "2.0",
+    id: id ?? null,
+    result
+  };
+}
+function error(id, code, message, data) {
+  return {
+    jsonrpc: "2.0",
+    id: id ?? null,
+    error: data === void 0 ? { code, message } : { code, message, data }
+  };
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PUPPETRY_AGENT_TOOLS,
+  Puppetry,
+  PuppetryAuthError,
+  PuppetryError,
+  PuppetryNetworkError,
+  PuppetryRateLimitError,
+  PuppetryTimeoutError,
+  callPuppetryAgentTool,
+  handlePuppetryMcpRequest,
+  puppetryErrorData,
+  safeCallPuppetryAgentTool
+});