@puppetry.com/sdk 0.1.0

package/dist/mcp-ChYQVbVe.d.mts

@@ -0,0 +1,947 @@
+/**
+ * Puppetry SDK Types
+ * Generated from OpenAPI spec (docs/api/openapi.yaml)
+ */
+type VideoStatus = "queued" | "processing" | "completed" | "failed";
+type VideoJobSource = "text" | "audio";
+interface IdempotencyKeyOptions {
+    /**
+     * Optional retry key sent as the Idempotency-Key header.
+     *
+     * Use this when retrying create requests so Puppetry can replay the accepted
+     * job or upload reservation without charging or reserving quota twice.
+     */
+    idempotencyKey?: string;
+    /**
+     * Optional snake_case retry key alias for agent tool inputs.
+     *
+     * This is normalized to the Idempotency-Key header just like
+     * idempotencyKey.
+     */
+    idempotency_key?: string;
+}
+interface ApiAudioUploadFallbackDiagnostics {
+    source: "api-audio-upload-s3-fallback";
+    key: string;
+    recoveredFromS3: boolean;
+    reason?: string;
+    s3FallbackRetryCount?: number;
+    s3FallbackLastRetryReason?: string;
+    expectedETag?: string;
+    expectedMimeType?: "audio/wav" | "audio/mpeg" | "audio/mp4";
+    expectedSizeBytes?: number;
+    readUrlExpiresAt?: string;
+    readUrlExpiredAtFallback?: boolean;
+}
+interface LivePortraitRecoveryDiagnostics {
+    source: "liveportrait";
+    squareDrivingCropBypassAttempted: true;
+    squareDrivingCropBypassStage: string;
+}
+interface VideoJobDiagnostics {
+    apiAudioUpload?: ApiAudioUploadFallbackDiagnostics;
+    livePortrait?: LivePortraitRecoveryDiagnostics;
+}
+interface VideoJobResult {
+    diagnostics?: VideoJobDiagnostics;
+    [key: string]: unknown;
+}
+type ImageUrlAliases = {
+    /** Hosted portrait image URL. */
+    image_url?: string;
+    /** @deprecated Prefer image_url for raw API parity. Kept for idiomatic SDK callers. */
+    imageUrl?: string;
+    /** Alias for agent callers that label the portrait input as an image. */
+    image?: string;
+    /** @deprecated Use image_url. Kept as an SDK alias for older callers. */
+    portrait?: string;
+    /** Hosted portrait image URL snake_case alias for agent callers. */
+    portrait_url?: string;
+    /** Hosted portrait image URL alias for agent callers. */
+    portraitUrl?: string;
+    /** Hosted avatar image URL alias for agent callers. */
+    avatar?: string;
+    /** Hosted avatar image URL alias for agent callers. */
+    avatarUrl?: string;
+    /** Hosted avatar image URL snake_case alias for agent callers. */
+    avatar_url?: string;
+    /** Hosted photo image URL alias for agent callers. */
+    photo?: string;
+    /** Hosted photo image URL alias for agent callers. */
+    photoUrl?: string;
+    /** Hosted photo image URL snake_case alias for agent callers. */
+    photo_url?: string;
+};
+type ImageUrlInput = ImageUrlAliases & ({
+    image_url: string;
+} | {
+    imageUrl: string;
+} | {
+    image: string;
+} | {
+    portrait: string;
+} | {
+    portrait_url: string;
+} | {
+    portraitUrl: string;
+} | {
+    avatar: string;
+} | {
+    avatarUrl: string;
+} | {
+    avatar_url: string;
+} | {
+    photo: string;
+} | {
+    photoUrl: string;
+} | {
+    photo_url: string;
+});
+type AudioUrlInput = {
+    /** Hosted audio URL. */
+    audio_url: string;
+    audioUrl?: string;
+    /** Hosted audio URL alias for agent callers. */
+    audio?: string;
+} | {
+    audio_url?: string;
+    /** @deprecated Use audio_url. Kept as an SDK alias for older callers. */
+    audioUrl: string;
+    /** Hosted audio URL alias for agent callers. */
+    audio?: string;
+} | {
+    audio_url?: string;
+    /** @deprecated Use audio_url. Kept as an SDK alias for older callers. */
+    audioUrl?: string;
+    /** Hosted audio URL alias for agent callers. */
+    audio: string;
+};
+type MimeTypeInput = {
+    /** Audio MIME type. */
+    mime_type: string;
+    mimeType?: string;
+    contentType?: string;
+} | {
+    mime_type?: string;
+    /** Audio MIME type. */
+    mimeType: string;
+    contentType?: string;
+} | {
+    mime_type?: string;
+    mimeType?: string;
+    /** Audio MIME type alias commonly used for signed uploads. */
+    contentType: string;
+};
+type ContentLengthInput = {
+    /** Exact byte length of the audio file to upload */
+    content_length: number;
+    contentLength?: number;
+    sizeBytes?: number;
+    file_size?: number;
+    fileSize?: number;
+} | {
+    content_length?: number;
+    /** Exact byte length of the audio file to upload */
+    contentLength: number;
+    sizeBytes?: number;
+    file_size?: number;
+    fileSize?: number;
+} | {
+    content_length?: number;
+    contentLength?: number;
+    /** Exact byte length alias for agent/runtime callers. */
+    sizeBytes: number;
+    file_size?: number;
+    fileSize?: number;
+} | {
+    content_length?: number;
+    contentLength?: number;
+    sizeBytes?: number;
+    /** Exact byte length alias for upload/file metadata callers. */
+    file_size: number;
+    fileSize?: number;
+} | {
+    content_length?: number;
+    contentLength?: number;
+    sizeBytes?: number;
+    file_size?: number;
+    /** Exact byte length alias for upload/file metadata callers. */
+    fileSize: number;
+};
+type TextScriptInput = {
+    /** Text script for TTS */
+    text: string;
+    /** Alias for text, useful for MCP/agent callers that use script terminology. */
+    script?: string;
+    /** Alias for text, useful for prompt-oriented agents. */
+    prompt?: string;
+} | {
+    /** Text script for TTS */
+    text?: string;
+    /** Alias for text, useful for MCP/agent callers that use script terminology. */
+    script: string;
+    /** Alias for text, useful for prompt-oriented agents. */
+    prompt?: string;
+} | {
+    /** Text script for TTS */
+    text?: string;
+    /** Alias for text, useful for MCP/agent callers that use script terminology. */
+    script?: string;
+    /** Alias for text, useful for prompt-oriented agents. */
+    prompt: string;
+};
+interface VideoJob {
+    object?: "video_job";
+    id: string;
+    job_id?: string;
+    jobId?: string;
+    operation_id?: string;
+    operationId?: string;
+    request_id?: string;
+    requestId?: string;
+    task_id?: string;
+    taskId?: string;
+    source?: VideoJobSource;
+    request_source?: VideoJobSource;
+    requestSource?: VideoJobSource;
+    status: VideoStatus;
+    state?: VideoStatus;
+    task_status?: VideoStatus;
+    taskStatus?: VideoStatus;
+    progress?: number | null;
+    percent?: number | null;
+    percentage?: number | null;
+    progress_percent?: number | null;
+    progressPercent?: number | null;
+    created_at?: string;
+    createdAt?: string;
+    expires_at?: string;
+    expiresAt?: string;
+    completed_at?: string | null;
+    completedAt?: string | null;
+    url?: string | null;
+    video_url?: string | null;
+    videoUrl?: string | null;
+    result_url?: string | null;
+    resultUrl?: string | null;
+    download_url?: string | null;
+    downloadUrl?: string | null;
+    output_url?: string | null;
+    outputUrl?: string | null;
+    thumbnail_url?: string | null;
+    thumbnailUrl?: string | null;
+    duration?: number | null;
+    duration_seconds?: number | null;
+    durationSeconds?: number | null;
+    error?: string | null;
+    retryable?: boolean;
+    retry_blocked_reason?: string;
+    retryBlockedReason?: string;
+    retry_block_code?: string;
+    retryBlockCode?: string;
+    diagnostics?: VideoJobDiagnostics;
+    result?: VideoJobResult | null;
+    credits?: {
+        charged: number;
+        remaining: number | null;
+    };
+    creation_credits?: {
+        charged: number;
+        remaining_after_debit: number | null;
+        remainingAfterDebit?: number | null;
+    };
+    creationCredits?: {
+        charged: number;
+        remaining_after_debit?: number | null;
+        remainingAfterDebit: number | null;
+    };
+    status_url?: string;
+    statusUrl?: string;
+    content_location?: string;
+    contentLocation?: string;
+    retry_after_seconds?: number;
+    retryAfter?: number;
+    retryAfterSeconds?: number;
+    next_poll_at?: string;
+    nextPollAt?: string;
+    idempotent_replay?: true;
+    idempotentReplay?: true;
+}
+interface VideoJobHelpers {
+    /**
+     * Poll this job until it reaches completed or failed.
+     *
+     * SDK-returned jobs expose this helper as a non-enumerable property, so the
+     * object still serializes like the raw API response.
+     */
+    waitForCompletion(options?: WaitForCompletionOptions): Promise<PuppetryVideoJob>;
+}
+type PuppetryVideoJob = VideoJob & VideoJobHelpers;
+type CreateTextVideoParams = IdempotencyKeyOptions & ImageUrlInput & TextScriptInput & {
+    /** Puppetry voice ID (from voices.listPuppetry()) */
+    voice_id?: string;
+    /** @deprecated Use voice_id. Kept as an SDK alias for older callers. */
+    voiceId?: string;
+    /** Voice ID alias that matches the quickstart-style SDK examples. */
+    voice?: string;
+    /** Language code (default: "en") */
+    language?: string;
+    /** Animation expressiveness from 0 to 2 (default: 1) */
+    expressiveness?: number;
+};
+type CreateAudioVideoParams = IdempotencyKeyOptions & ImageUrlInput & AudioUrlInput & {
+    /** Animation expressiveness from 0 to 2 (default: 1) */
+    expressiveness?: number;
+};
+interface WaitForCompletionOptions {
+    /** Polling interval in milliseconds, default 2000 */
+    intervalMs?: number;
+    /** Max wait time in milliseconds, default 300000 */
+    timeoutMs?: number;
+    /**
+     * Optional delay before the first status request.
+     *
+     * Jobs returned by create helpers use the API's Retry-After hint by default
+     * so the first poll is paced like the raw Developer API contract.
+     */
+    initialDelayMs?: number;
+    /**
+     * Called after each status poll, including the terminal completed/failed job.
+     *
+     * Use this for agent progress logs or UI updates without starting a separate
+     * stream.
+     */
+    onPoll?: (job: PuppetryVideoJob) => void | Promise<void>;
+    /**
+     * Called when status polling receives a retryable API error and the SDK will
+     * wait/back off before polling again.
+     */
+    onRetrying?: (event: VideoEvent) => void | Promise<void>;
+}
+interface Voice {
+    id: string;
+    name: string;
+    language: string;
+    gender?: "male" | "female" | "neutral";
+    provider: string;
+    previewUrl?: string;
+    isCloned?: boolean;
+}
+interface PuppetryVoice {
+    id: string;
+    object: "voice";
+    name: string;
+    provider: "puppetry";
+    language: string;
+    language_code: string;
+    gender: string;
+    description: string;
+    styles: string[];
+    preview_text: string;
+    preview_url: string;
+}
+interface PuppetryVoiceList {
+    object: "list";
+    data: PuppetryVoice[];
+    default_voice_id: string;
+}
+interface ListVoicesParams {
+    language?: string;
+    gender?: "male" | "female" | "neutral";
+    cursor?: string;
+    limit?: number;
+}
+interface CreatePuppetryTtsParams {
+    /** Voice ID from voices.listPuppetry() */
+    voice_id: string;
+    /** Text to synthesize, up to 5,000 characters */
+    text: string;
+    /** Speech speed multiplier, from 0.5 to 2.0 */
+    speed?: number;
+}
+interface PuppetryTtsResponse {
+    object: "audio";
+    id: string;
+    voice_id: string;
+    audio_url: string;
+    format: "wav" | string;
+    usage?: {
+        voice_characters: {
+            used: number;
+            limit: number;
+            remaining: number;
+        };
+    };
+}
+interface AudioUploadVideoReadinessOptions {
+    /**
+     * Require current video-generation credit/slot readiness before reserving a
+     * hosted audio upload URL for an audio-to-video workflow.
+     */
+    require_video_readiness?: boolean;
+    /** CamelCase alias for require_video_readiness. */
+    requireVideoReadiness?: boolean;
+}
+type CreateAudioUploadUrlParams = IdempotencyKeyOptions & MimeTypeInput & ContentLengthInput & AudioUploadVideoReadinessOptions;
+type AudioUploadBody = NonNullable<NonNullable<Parameters<typeof globalThis.fetch>[1]>["body"]>;
+type UploadAudioParams = CreateAudioUploadUrlParams & {
+    /** Raw audio bytes to PUT to the signed upload URL */
+    body: AudioUploadBody;
+};
+interface ApiUploadLimits {
+    max_file_bytes: number;
+    maxFileBytes?: number;
+    monthly_uploads: number;
+    monthlyUploads?: number;
+    storage_bytes: number;
+    storageBytes?: number;
+    remaining_monthly_uploads: number;
+    remainingMonthlyUploads?: number;
+    remaining_storage_bytes: number;
+    remainingStorageBytes?: number;
+}
+interface AudioUploadUrlResponse {
+    object: "upload_url";
+    id: string;
+    upload_url: string;
+    uploadUrl?: string;
+    method: "PUT";
+    headers: {
+        "Content-Type": string;
+        "Content-Length": string;
+    };
+    key: string;
+    read_url: string;
+    readUrl?: string;
+    read_url_expires_in: number;
+    readUrlExpiresIn?: number;
+    read_url_expires_at: string;
+    readUrlExpiresAt?: string;
+    upload_url_expires_in: number;
+    uploadUrlExpiresIn?: number;
+    idempotent_replay?: true;
+    idempotentReplay?: true;
+    limits: ApiUploadLimits;
+}
+interface Puppet {
+    id: string;
+    name: string;
+    imageUrl: string;
+    createdAt: string;
+}
+interface CreatePuppetParams {
+    /** Portrait image URL */
+    imageUrl: string;
+    /** Display name for the puppet */
+    name?: string;
+}
+interface ListPuppetsParams {
+    cursor?: string;
+    limit?: number;
+}
+interface UsageApiKeyVideoCredits {
+    id?: string;
+    key_id?: string;
+    keyId?: string;
+    name?: string;
+    key_prefix?: string;
+    keyPrefix?: string;
+    type?: "developer_api" | "mcp";
+    used: number;
+    refunded: number;
+    net_used: number;
+    netUsed?: number;
+    transactions: number;
+}
+interface UsageVideoCredits {
+    balance: number;
+    month: string;
+    reset_at: string;
+    resetAt?: string;
+    used: number;
+    refunded: number;
+    net_used: number;
+    netUsed?: number;
+    transactions: number;
+    current_api_key: UsageApiKeyVideoCredits;
+    currentApiKey?: UsageApiKeyVideoCredits;
+}
+type UsageVideoGenerationReadinessReason = "available" | "insufficient_video_credits" | "concurrent_job_limit_reached";
+interface UsageVideoGenerationCreditBlocker {
+    code: "insufficient_video_credits";
+    reason: "insufficient_video_credits";
+    retryable: false;
+    required_credits: number;
+    requiredCredits?: number;
+    credits_remaining: number;
+    creditsRemaining?: number;
+    retry_block_code?: string;
+    retryBlockCode?: string;
+}
+interface UsageVideoGenerationConcurrentBlocker {
+    code: "concurrent_job_limit_reached";
+    reason: "concurrent_job_limit_reached";
+    retryable: true;
+    concurrent_jobs?: number;
+    concurrentJobs?: number;
+    active_jobs?: number;
+    activeJobs?: number;
+    available_slots?: number;
+    availableSlots?: number;
+    active_job_expires_in_seconds?: number;
+    activeJobExpiresInSeconds?: number;
+    retry_after_seconds?: number;
+    retryAfter?: number;
+    retryAfterSeconds?: number;
+    next_poll_at?: string;
+    nextPollAt?: string;
+}
+type UsageVideoGenerationBlocker = UsageVideoGenerationCreditBlocker | UsageVideoGenerationConcurrentBlocker;
+interface UsageVideoGenerationReadiness {
+    can_create: boolean;
+    canCreate?: boolean;
+    required_credits: number;
+    requiredCredits?: number;
+    credits_remaining: number;
+    creditsRemaining?: number;
+    concurrent_jobs?: number;
+    concurrentJobs?: number;
+    active_jobs?: number;
+    activeJobs?: number;
+    available_slots?: number;
+    availableSlots?: number;
+    active_job_expires_in_seconds?: number;
+    activeJobExpiresInSeconds?: number;
+    retry_after_seconds?: number;
+    retryAfter?: number;
+    retryAfterSeconds?: number;
+    next_poll_at?: string;
+    nextPollAt?: string;
+    reason: UsageVideoGenerationReadinessReason;
+    blockers?: UsageVideoGenerationBlocker[];
+}
+interface Usage {
+    object?: "usage";
+    video_credits?: UsageVideoCredits;
+    videoCredits?: UsageVideoCredits;
+    video_generation?: UsageVideoGenerationReadiness;
+    videoGeneration?: UsageVideoGenerationReadiness;
+    /** @deprecated Use video_credits.balance or videoCredits.balance. */
+    plan: string;
+    /** @deprecated Use video_credits.balance plus video_credits.net_used when needed. */
+    creditsTotal: number;
+    /** @deprecated Use video_credits.net_used or videoCredits.netUsed. */
+    creditsUsed: number;
+    /** @deprecated Use video_credits.balance or videoCredits.balance. */
+    creditsRemaining: number;
+    /** @deprecated Use video_credits.month. */
+    periodStart: string;
+    /** @deprecated Use video_credits.reset_at or videoCredits.resetAt. */
+    periodEnd: string;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    nextCursor?: string | null;
+    hasMore: boolean;
+}
+type VideoEventType = "queued" | "processing" | "progress" | "retrying" | "completed" | "failed";
+interface VideoEvent {
+    type: VideoEventType;
+    id?: string;
+    job_id?: string;
+    jobId: string;
+    task_id?: string;
+    taskId?: string;
+    operation_id?: string;
+    operationId?: string;
+    request_id?: string;
+    requestId?: string;
+    source?: VideoJobSource;
+    request_source?: VideoJobSource;
+    requestSource?: VideoJobSource;
+    status_url?: string;
+    statusUrl?: string;
+    content_location?: string;
+    contentLocation?: string;
+    progress?: number;
+    video_url?: string;
+    videoUrl?: string;
+    error?: string;
+    code?: string;
+    status?: number;
+    statusCode?: number;
+    retryable?: boolean;
+    credits?: {
+        charged: number;
+        remaining: number | null;
+    };
+    creation_credits?: {
+        charged: number;
+        remaining_after_debit: number | null;
+        remainingAfterDebit: number | null;
+    };
+    creationCredits?: {
+        charged: number;
+        remaining_after_debit: number | null;
+        remainingAfterDebit: number | null;
+    };
+    retry_blocked_reason?: string;
+    retryBlockedReason?: string;
+    retry_block_code?: string;
+    retryBlockCode?: string;
+    retry_after_seconds?: number;
+    retryAfter?: number;
+    retryAfterSeconds?: number;
+    next_poll_at?: string;
+    nextPollAt?: string;
+    created_at?: string;
+    createdAt?: string;
+    expires_at?: string;
+    expiresAt?: string;
+    completed_at?: string | null;
+    completedAt?: string | null;
+    timestamp: string;
+}
+interface PuppetryRequestRetryEvent {
+    /** HTTP method being retried. */
+    method: string;
+    /** SDK API path being retried, relative to the configured base URL. */
+    path: string;
+    /** Full request URL being retried. */
+    url: string;
+    /** Normalized Idempotency-Key header value for retry-safe writes. */
+    idempotency_key?: string;
+    /** CamelCase alias for idempotency_key. */
+    idempotencyKey?: string;
+    /** One-based failed attempt count. */
+    attempt: number;
+    /** Configured retry budget. */
+    maxRetries: number;
+    /** Delay the SDK will wait before the next attempt. */
+    delayMs: number;
+    status?: number;
+    statusCode?: number;
+    code?: string;
+    message?: string;
+    details?: Record<string, unknown>;
+    retryable?: boolean;
+    credits?: {
+        charged: number;
+        remaining: number | null;
+    };
+    creation_credits?: {
+        charged: number;
+        remaining_after_debit: number | null;
+        remainingAfterDebit: number | null;
+    };
+    creationCredits?: {
+        charged: number;
+        remaining_after_debit: number | null;
+        remainingAfterDebit: number | null;
+    };
+    retry_blocked_reason?: string;
+    retryBlockedReason?: string;
+    retry_block_code?: string;
+    retryBlockCode?: string;
+    retry_after_seconds?: number;
+    retryAfter?: number;
+    retryAfterSeconds?: number;
+    id?: string;
+    job_id?: string;
+    jobId?: string;
+    operation_id?: string;
+    operationId?: string;
+    request_id?: string;
+    requestId?: string;
+    task_id?: string;
+    taskId?: string;
+    source?: string;
+    request_source?: string;
+    requestSource?: string;
+    status_url?: string;
+    statusUrl?: string;
+    content_location?: string;
+    contentLocation?: string;
+    next_poll_at?: string;
+    nextPollAt?: string;
+}
+interface PuppetryConfig {
+    /** Your Puppetry API key */
+    apiKey: string;
+    /** Base URL (default: https://www.puppetry.com/api/v1) */
+    baseUrl?: string;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Retries for safe 429/5xx reads and idempotency-protected 429/5xx writes (default: 2) */
+    maxRetries?: number;
+    /** Initial exponential backoff delay in ms (default: 500) */
+    retryDelayMs?: number;
+    /**
+     * Called before the SDK sleeps and retries a safe/idempotent request.
+     *
+     * Use this to surface Developer API 429/5xx backoff and job correlation
+     * metadata in agents or CLIs. Observer failures are ignored so retry logging
+     * cannot break an otherwise successful idempotent replay.
+     */
+    onRetry?: (event: PuppetryRequestRetryEvent) => void | Promise<void>;
+    /** Custom fetch implementation (for Node 16 or custom environments) */
+    fetch?: typeof globalThis.fetch;
+}
+interface ApiErrorResponse {
+    error: string;
+    message: string;
+    object?: unknown;
+    id?: unknown;
+    job_id?: unknown;
+    jobId?: unknown;
+    operation_id?: unknown;
+    operationId?: unknown;
+    task_id?: unknown;
+    taskId?: unknown;
+    source?: unknown;
+    request_source?: unknown;
+    requestSource?: unknown;
+    status_url?: unknown;
+    statusUrl?: unknown;
+    content_location?: unknown;
+    contentLocation?: unknown;
+    created_at?: unknown;
+    createdAt?: unknown;
+    expires_at?: unknown;
+    expiresAt?: unknown;
+    next_poll_at?: unknown;
+    nextPollAt?: unknown;
+    retryable?: unknown;
+    retry_blocked_reason?: unknown;
+    retryBlockedReason?: unknown;
+    retry_block_code?: unknown;
+    retryBlockCode?: unknown;
+    retry_after_seconds?: unknown;
+    retryAfter?: unknown;
+    retryAfterSeconds?: unknown;
+    details?: Record<string, unknown>;
+}
+
+declare class Puppetry {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    private readonly onRetry?;
+    private readonly fetchFn;
+    constructor(config: PuppetryConfig);
+    private requestWithResponse;
+    private requestRetryEvent;
+    private notifyRetry;
+    private request;
+    private get;
+    private getWithResponse;
+    private post;
+    private delete;
+    private shouldRetry;
+    private isRetryableVideoStatusError;
+    private isVideoStatusRequest;
+    private shouldRetryTransport;
+    private isRetrySafeRequest;
+    private isAbortError;
+    private isNetworkError;
+    private transportErrorMessage;
+    private parseRetryAfter;
+    private responseRetryAfter;
+    private retryAfterFromErrorBody;
+    private retryAfterFromDetails;
+    private normalizeRetryAfterSeconds;
+    private retryDelay;
+    private sleep;
+    private responseHeaders;
+    private readHeader;
+    private readResponseHeader;
+    private compactBody;
+    private normalizeIdempotencyKey;
+    private idempotencyKeyFromParams;
+    private resolveAlias;
+    private resolveRequiredStringAliases;
+    private resolveOptionalStringAliases;
+    private resolveUploadStringAliases;
+    private resolveNumberAliases;
+    private firstDefinedNullable;
+    private textVideoBody;
+    private audioVideoBody;
+    private videoJobPath;
+    private normalizeVideoJob;
+    private videoJobStatusUrlHeader;
+    private videoJobPollLocationAliases;
+    private videoLocationHeader;
+    private videoContentLocationHeader;
+    private videoOperationIdHeader;
+    private videoRequestIdHeader;
+    private videoNextPollAtHeader;
+    private videoStatusErrorOptions;
+    private videoCreditErrorOptions;
+    private videoCreditHeaderNumber;
+    private videoJobIdFromStatusUrl;
+    private retryableStatusErrorJobId;
+    private videoJobResultDiagnostics;
+    private videoStatusCredits;
+    private videoCreationCredits;
+    private videoCreationCreditsFromHeaders;
+    private videoProgress;
+    private attachVideoJobHelpers;
+    private waitOptionsWithInitialDelay;
+    private retryAfterDelayMs;
+    private optionDelayMs;
+    private nextPollDelayMs;
+    private sleepWithinDeadline;
+    private pollingDelayMs;
+    private retryableStatusErrorDelayMs;
+    private normalizeUsage;
+    private normalizeVideoGenerationReadiness;
+    private normalizeVideoGenerationBlockers;
+    private normalizeVideoGenerationBlocker;
+    private derivedVideoGenerationBlockers;
+    private activeJobReadinessAliases;
+    private videoGenerationReadinessReason;
+    private readinessNumber;
+    private readinessString;
+    private getVideoGenerationReadiness;
+    private ensureVideoGenerationReady;
+    private videoGenerationReadinessErrorOptions;
+    private normalizeAudioUploadLimits;
+    private normalizeAudioUpload;
+    /**
+     * 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",
+     * });
+     * ```
+     */
+    readonly videos: {
+        createFromText: (params: CreateTextVideoParams) => Promise<PuppetryVideoJob>;
+        createFromAudio: (params: CreateAudioVideoParams) => Promise<PuppetryVideoJob>;
+        get: (jobId: string) => Promise<PuppetryVideoJob>;
+        /**
+         * 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: () => Promise<NonNullable<Usage["video_generation"]>>;
+        /**
+         * 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: () => Promise<NonNullable<Usage["video_generation"]>>;
+        /**
+         * 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: (jobId: string, options?: WaitForCompletionOptions) => Promise<PuppetryVideoJob>;
+        /**
+         * 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: string, options?: WaitForCompletionOptions) => AsyncGenerator<VideoEvent>;
+    };
+    readonly 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: string) => Promise<PuppetryVideoJob>;
+        /**
+         * Wait for a generated video job to complete, polling at the given interval.
+         */
+        waitForCompletion: (jobId: string, options?: WaitForCompletionOptions) => Promise<PuppetryVideoJob>;
+    };
+    readonly voices: {
+        list: (params?: ListVoicesParams) => Promise<PaginatedResponse<Voice>>;
+        listPuppetry: () => Promise<PuppetryVoiceList>;
+    };
+    readonly tts: {
+        createPuppetry: (params: CreatePuppetryTtsParams) => Promise<PuppetryTtsResponse>;
+    };
+    readonly uploads: {
+        /**
+         * Create a signed PUT URL for hosting audio that can be used by Puppetry API
+         * workflows.
+         */
+        createAudioUrl: (params: CreateAudioUploadUrlParams) => Promise<AudioUploadUrlResponse>;
+        /**
+         * Create a signed audio upload URL and PUT the provided bytes to it.
+         *
+         * The returned `read_url` can be passed to `videos.createFromAudio()`.
+         */
+        uploadAudio: (params: UploadAudioParams) => Promise<AudioUploadUrlResponse>;
+    };
+    readonly puppets: {
+        list: (params?: ListPuppetsParams) => Promise<PaginatedResponse<Puppet>>;
+        create: (params: CreatePuppetParams) => Promise<Puppet>;
+        delete: (puppetId: string) => Promise<void>;
+    };
+    readonly usage: {
+        get: () => Promise<Usage>;
+    };
+    readonly quota: {
+        get: () => Promise<Usage>;
+    };
+    private videoJobEvent;
+    private videoRetryingEvent;
+    private streamPolledVideoEvents;
+}
+
+type JsonRpcId = string | number | null;
+interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id?: JsonRpcId;
+    method: string;
+    params?: unknown;
+}
+interface JsonRpcSuccessResponse {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    result: unknown;
+}
+interface JsonRpcErrorResponse {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+interface PuppetryMcpServerInfo {
+    name: "puppetry";
+    version: string;
+}
+declare function handlePuppetryMcpRequest(client: Puppetry, request: JsonRpcRequest): Promise<JsonRpcResponse | null>;
+
+export { type ApiErrorResponse as A, type VideoJobSource as B, type CreateTextVideoParams as C, type VideoStatus as D, type Voice as E, handlePuppetryMcpRequest as F, type JsonRpcErrorResponse as J, type ListPuppetsParams as L, type PuppetryVideoJob as P, type UsageVideoGenerationReadiness as U, type VideoEvent as V, type WaitForCompletionOptions as W, type AudioUploadUrlResponse as a, type PuppetryVoiceList as b, type Usage as c, type CreateAudioVideoParams as d, type CreateAudioUploadUrlParams as e, Puppetry as f, type ApiUploadLimits as g, type AudioUploadBody as h, type CreatePuppetParams as i, type CreatePuppetryTtsParams as j, type JsonRpcId as k, type JsonRpcRequest as l, type JsonRpcResponse as m, type JsonRpcSuccessResponse as n, type ListVoicesParams as o, type PaginatedResponse as p, type Puppet as q, type PuppetryConfig as r, type PuppetryMcpServerInfo as s, type PuppetryRequestRetryEvent as t, type PuppetryTtsResponse as u, type PuppetryVoice as v, type UploadAudioParams as w, type VideoEventType as x, type VideoJob as y, type VideoJobHelpers as z };