@widecast/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,448 @@
+/**
+ * WideCast.ai TypeScript / JavaScript SDK — thin client for the public API.
+ *
+ * Works in Node 18+, Deno, Bun, browsers — uses the global `fetch`.
+ *
+ * @example
+ *   import Widecast from "@widecast/sdk";
+ *   const client = new Widecast({ apiKey: "wc_live_REPLACE_ME" });
+ *   const video = await client.create_video({ script }).then(v => v.wait());
+ *   console.log(video.review_url);
+ */
+declare const VERSION = "0.1.0";
+declare const SCRIPT_MIN_WORDS = 80;
+declare const SCRIPT_MAX_WORDS = 500;
+declare const IDEA_MIN_WORDS = 5;
+declare const IDEA_MAX_WORDS = 1000;
+declare const BLOG_MIN_WORDS = 30;
+declare const BLOG_MAX_WORDS = 3000;
+declare const OUTPUT_TYPES: readonly ["text", "scene", "video"];
+type OutputType = (typeof OUTPUT_TYPES)[number];
+declare const SOURCES: readonly ["text", "idea", "blog", "video_url", "video_file", "audio_url", "audio_file"];
+type Source = (typeof SOURCES)[number];
+declare const FACELESS_SOURCES: readonly ["text", "idea", "blog"];
+declare const CONTENT_TYPES: readonly ["blog", "facebook", "x", "linkedin"];
+type ContentType = (typeof CONTENT_TYPES)[number];
+declare const INTERVENTION_LEVELS: readonly [0, 1, 2];
+type InterventionLevel = (typeof INTERVENTION_LEVELS)[number];
+declare const PUBLISH_PLATFORMS: readonly ["youtube", "tiktok", "instagram", "facebook", "linkedin", "x", "threads", "pinterest", "reddit", "bluesky", "google_business"];
+type PublishPlatform = (typeof PUBLISH_PLATFORMS)[number];
+/** Options for client.create_content(). */
+interface CreateContentOptions {
+    /** A URL, an idea/topic, or pasted text the content is created from. */
+    content: string;
+    /** "blog" (default) / "facebook" / "x" / "linkedin". */
+    content_type?: ContentType;
+    /** Output language (e.g. "English"). Default "English". */
+    language?: string;
+    callback_url?: string;
+    metadata?: Record<string, unknown>;
+    idempotency_key?: string;
+}
+/** Options for client.enhance_script(). */
+interface EnhanceScriptOptions {
+    /** The DRAFT script to enhance. */
+    script_text: string;
+    /** Output language; "" (default) keeps the draft's original language. */
+    language?: string;
+    /** 0=segment only, 1=natural enhance (default), 2=maximum rewrite. */
+    intervention_level?: InterventionLevel;
+    callback_url?: string;
+    metadata?: Record<string, unknown>;
+    idempotency_key?: string;
+}
+/** Options for client.suggest_ideas(). */
+interface SuggestIdeasOptions {
+    /** Industry name (e.g. "Real Estate"). Falls back to your account industry if omitted. */
+    industry_id?: string;
+    /** How many ideas (1–20, default 5). */
+    num_topics?: number;
+    sub_industry?: string;
+    user_location?: string;
+    idempotency_key?: string;
+}
+/** Options for client.collect_ideas(). */
+interface CollectIdeasOptions {
+    /** Product/service description (≥10 chars) to brainstorm ideas from. */
+    product_service_input: string;
+    sub_industry?: string;
+    user_location?: string;
+    idempotency_key?: string;
+}
+/** Options for client.publish(). Provide EXACTLY ONE of topic_id / text / video_url. */
+interface PublishOptions {
+    /** Publish an existing WideCast video OR blog/social post (auto-detected). */
+    topic_id?: string;
+    /** Post arbitrary text (optionally with photo_urls). */
+    text?: string;
+    /** A direct video file URL to download + publish. Requires `title`. */
+    video_url?: string;
+    /** Caption/title. Required for video_url; optional override for topic_id. */
+    title?: string;
+    description?: string;
+    /** Image URLs to attach (with `text`). */
+    photo_urls?: string[];
+    /** Target platforms. Defaults to ALL connected platforms. */
+    platforms?: PublishPlatform[];
+    scheduled_date?: string;
+    timezone?: string;
+    callback_url?: string;
+    metadata?: Record<string, unknown>;
+    idempotency_key?: string;
+}
+/** Accepted-publish envelope (HTTP 202) returned by client.publish(). */
+interface PublishResponse {
+    object: string;
+    /** Primary upstream request_id — poll get_status(id). */
+    id: string;
+    /** All upstream request_ids (article spanning text+photo may return two). */
+    request_ids: string[];
+    status: "processing";
+    platforms: string[];
+    skipped?: string[];
+    metadata?: Record<string, unknown>;
+    links?: {
+        status?: string;
+    };
+    meta?: {
+        request_id?: string;
+        widecast_version?: string;
+    };
+}
+/** One idea in an IdeasResponse. */
+interface Idea {
+    title: string;
+    description: string;
+    industry?: string;
+    audience?: string;
+    professional?: string;
+    level?: string;
+}
+/** Synchronous response of suggest_ideas / collect_ideas. */
+interface IdeasResponse {
+    object: string;
+    industry?: string;
+    ideas: Idea[];
+}
+declare const MEDIA_SOURCES: {
+    readonly video_url: {
+        readonly media_type: "video";
+        readonly input_kind: "url";
+        readonly field: "video_url";
+    };
+    readonly video_file: {
+        readonly media_type: "video";
+        readonly input_kind: "file";
+        readonly field: "video_file";
+    };
+    readonly audio_url: {
+        readonly media_type: "audio";
+        readonly input_kind: "url";
+        readonly field: "audio_url";
+    };
+    readonly audio_file: {
+        readonly media_type: "audio";
+        readonly input_kind: "file";
+        readonly field: "audio_file";
+    };
+};
+declare const MEDIA_MAX_DURATION_SECONDS = 120;
+declare const MEDIA_MAX_FILE_BYTES: number;
+declare const VIDEO_LENGTHS: readonly ["short", "normal"];
+type VideoLength = (typeof VIDEO_LENGTHS)[number];
+declare const LANGUAGES: readonly ["English", "Vietnamese"];
+type Language = (typeof LANGUAGES)[number];
+type VideoStatus = "pending" | "processing" | "completed" | "failed";
+type ErrorCode = "account_expired" | "credit_exhausted" | "render_failed" | "unknown_error" | "scenes_not_ready" | "export_failed" | "script_too_short" | "script_too_long" | "invalid_output_type";
+interface StatusResult {
+    review_url: string;
+    /** Direct MP4 URL. Present only when output_type="video" OR after
+     *  /v1/export_video completes. */
+    video_url?: string;
+}
+/**
+ * Fine-grained worker state surfaced from the legacy row.
+ * ⚠ DELIBERATE NAME CLASH: `details.status` is a free-form legacy string
+ * (e.g. "Completed", "Avatar videos downloaded"), DISTINCT from the
+ * top-level `status` enum. Gate logic on the top-level field only.
+ */
+interface ProcessingDetails {
+    step: number;
+    status: string;
+    notes: string;
+    updated_at?: string;
+}
+interface StatusError {
+    code: ErrorCode | string;
+    message: string;
+}
+interface VideoResource {
+    object: "status";
+    id: string;
+    topic_id: string;
+    type: "video";
+    status: VideoStatus;
+    stage: string;
+    progress: number;
+    details: ProcessingDetails | null;
+    result: StatusResult | null;
+    error: StatusError | null;
+    callback_url?: string | null;
+    metadata: Record<string, unknown>;
+    usage: Record<string, unknown> | null;
+    links: {
+        self: string;
+    };
+    meta: {
+        request_id: string;
+        widecast_version: string;
+    };
+}
+interface CreateVideoOptions {
+    /** Input flow: "text" (default — backward-compat) requires `script_text`;
+     *  "idea" requires `idea_text` (+ optional language / video_length /
+     *  research_enabled). */
+    source?: Source;
+    /** Plain text script — required when `source="text"`. Used VERBATIM by the
+     *  narrator (no AI rewriting). Must be `SCRIPT_MIN_WORDS`–`SCRIPT_MAX_WORDS`
+     *  words (80–500, ~20s–2min). Word count = whitespace split.
+     *  May contain inline image/video file URLs in either form:
+     *  - Markdown image syntax (recommended for AI-chat callers; chat hosts
+     *    render the picture inline so the end-user can visually approve each
+     *    scene): `![brief description](https://cdn.acme.com/photo.jpg)`.
+     *  - Raw URL on its own line (backward compat): `… https://… …`.
+     *  Direct file links only — .png/.jpg/.jpeg/.gif/.webp/.bmp/.avif/.svg or
+     *  .mp4/.webm/.mov/.m4v/.avi (optional ?query). WideCast strips both forms
+     *  from the narration and uses them as that scene's visual instead of
+     *  auto-sourced B-roll. Page links (e.g. youtube.com/watch) are NOT
+     *  inlined; use `source="video_url"` for a whole clip. */
+    script_text?: string;
+    /** Short idea description — required when `source="idea"`. Server writes
+     *  a narration from this (AI) then continues into scene-sourcing. Bounds:
+     *  `IDEA_MIN_WORDS` (5) min, `IDEA_MAX_WORDS` (1000) max — over-max is
+     *  auto-truncated server-side, NOT rejected. Original word count surfaces
+     *  in `details.input_truncated_from`. */
+    idea_text?: string;
+    /** Blog/article to repurpose — required when `source="blog"`. Same AI
+     *  script-writer + pipeline as idea, just a longer input. Bounds:
+     *  `BLOG_MIN_WORDS` (30) min, `BLOG_MAX_WORDS` (3000) max — over-max
+     *  auto-truncated, surfaced in `details.input_truncated_from`. */
+    blog_text?: string;
+    /** Media URL (YouTube/TikTok/Facebook) — required when source="video_url" /
+     *  "audio_url" (A49). The media's own audio becomes the narration / footage
+     *  becomes b-roll. */
+    video_url?: string;
+    audio_url?: string;
+    /** Media file to upload — required when source="video_file" / "audio_file"
+     *  (A49). Sent as multipart/form-data. Pass a Blob/File (in Node 18+ build one
+     *  with `new Blob([buffer])` or `await openAsBlob(path)`). */
+    video_file?: Blob;
+    audio_file?: Blob;
+    /** Narration language (generative sources only). Default "English". Locked
+     *  enum v0.1.0: see `LANGUAGES`. */
+    language?: Language;
+    /** Target video length (generative sources only). Default "short". "normal"
+     *  caps at ~3 min. See `VIDEO_LENGTHS`. */
+    video_length?: VideoLength;
+    /** Whether the AI does research / fact-check during narration generation
+     *  (generative sources only). Default true. */
+    research_enabled?: boolean;
+    /** Pipeline depth. "text" stops after the source→script phase (review_url →
+     *  Script Editor; generative sources only, NOT source="text"). "scene"
+     *  (default) stops at scenes-ready-for-review. "video" auto-chains into the
+     *  renderer for the final MP4. */
+    output_type?: OutputType;
+    /** If true, every scene is B-roll (no narrator A-roll anywhere) — a
+     *  "faceless" video. Default false (scenes mix A-roll + B-roll). Only valid
+     *  with output_type scene/video for sources text/idea/blog (FACELESS_SOURCES);
+     *  otherwise the server returns invalid_faceless. */
+    faceless?: boolean;
+    /** Extra direct image/video URLs you couldn't confidently place inline →
+     *  added to the first scene's media library so the scene editor lists them
+     *  for the user to drop into any scene. Direct file links only. */
+    media_pool?: string[];
+    wait_for_render?: boolean;
+    callback_url?: string;
+    metadata?: Record<string, unknown>;
+    idempotency_key?: string;
+}
+interface WidecastConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    userAgent?: string;
+    fetchImpl?: typeof fetch;
+}
+interface WaitOptions {
+    timeoutMs?: number;
+    initialIntervalMs?: number;
+    maxIntervalMs?: number;
+    backoffMultiplier?: number;
+}
+declare class WidecastError extends Error {
+    code: string;
+    requestId: string;
+    status: number;
+    docUrl: string;
+    param?: string;
+    responseJson: unknown;
+    constructor(message: string, opts?: Partial<{
+        code: string;
+        requestId: string;
+        status: number;
+        docUrl: string;
+        param: string;
+        responseJson: unknown;
+    }>);
+}
+declare class InvalidRequestError extends WidecastError {
+    constructor(m: string, o?: {});
+}
+declare class NotFoundError extends WidecastError {
+    constructor(m: string, o?: {});
+}
+declare class PreconditionFailedError extends WidecastError {
+    constructor(m: string, o?: {});
+}
+declare class RateLimitError extends WidecastError {
+    constructor(m: string, o?: {});
+}
+declare class APIError extends WidecastError {
+    constructor(m: string, o?: {});
+}
+declare class Video implements VideoResource {
+    #private;
+    object: "status";
+    id: string;
+    topic_id: string;
+    type: "video";
+    status: VideoStatus;
+    stage: string;
+    progress: number;
+    details: ProcessingDetails | null;
+    result: StatusResult | null;
+    error: StatusError | null;
+    callback_url?: string | null;
+    metadata: Record<string, unknown>;
+    usage: Record<string, unknown> | null;
+    links: {
+        self: string;
+    };
+    meta: VideoResource["meta"];
+    constructor(data: VideoResource, client: Widecast);
+    get isTerminal(): boolean;
+    /** URL where the user reviews the rendered scenes + audio. Present from the
+     *  first response (pending / processing / completed) — the review page
+     *  handles early arrival itself (spinner + in-page polling), so this is
+     *  safe to share with the user before status='completed'. */
+    get review_url(): string | null;
+    /** Direct MP4 URL — present only when status='completed' AND the video was
+     *  created with output_type='video' (or exported via client.export_video). */
+    get video_url(): string | null;
+    /** Poll /v1/status until terminal or timeout.
+     *  Default: fixed 5-second polling (no backoff). Override kwargs for
+     *  long-running polls where backoff is preferred. */
+    wait(opts?: WaitOptions): Promise<Video>;
+}
+declare class Widecast {
+    #private;
+    apiKey?: string;
+    baseUrl: string;
+    timeoutMs: number;
+    maxRetries: number;
+    userAgent: string;
+    constructor(cfg?: WidecastConfig);
+    create_video(opts: CreateVideoOptions): Promise<Video>;
+    /** POST /v1/export_video — kick the final-MP4 renderer for an existing
+     *  scene-output video. Idempotent: calling twice is a no-op.
+     *  Throws `PreconditionFailedError` if scenes are not yet ready. */
+    export_video(videoId: string): Promise<Video>;
+    get_status(videoId: string): Promise<Video>;
+    /** POST /v1/create_content — generate written content (blog / social post)
+     *  from a URL, an idea/topic, or pasted text. Async: returns a Video with
+     *  `review_url` (the public content viewer) already populated — safe to
+     *  share before completion; the viewer shows a spinner while content
+     *  generates. Poll with `.wait()` for the final state. */
+    create_content(opts: CreateContentOptions): Promise<Video>;
+    /** POST /v1/enhance_script — improve a DRAFT script with AI. Async: returns
+     *  a Video with `review_url` (the Script Editor) already populated — safe
+     *  to share before completion; the editor shows a spinner while enhancing.
+     *  Poll with `.wait()` for the final enhanced script. */
+    enhance_script(opts: EnhanceScriptOptions): Promise<Video>;
+    /** POST /v1/suggest_ideas — SYNCHRONOUS. Returns video topic ideas for an
+     *  industry immediately (no polling). `industry_id` falls back to your
+     *  account industry if omitted. Consumes credits. */
+    suggest_ideas(opts?: SuggestIdeasOptions): Promise<IdeasResponse>;
+    /** POST /v1/collect_ideas — SYNCHRONOUS. Returns video ideas derived from a
+     *  product/service description (≥10 chars) immediately. Consumes credits. */
+    collect_ideas(opts: CollectIdeasOptions): Promise<IdeasResponse>;
+    /** POST /v1/publish — distribute content to connected social platforms.
+     *  Provide EXACTLY ONE of topic_id / text / video_url. `platforms` defaults
+     *  to ALL connected. Charges 1 credit. Returns the accepted-publish envelope
+     *  (HTTP 202) — publishing is async on the platform side, so poll
+     *  get_status(id) (with any of `request_ids`) for per-platform post URLs. */
+    publish(opts: PublishOptions): Promise<PublishResponse>;
+    /** GET /v1/videos — list the account's recent videos (20/page). Free. */
+    list_videos(opts?: {
+        from_record?: number;
+    }): Promise<any>;
+    /** GET /v1/search — search the account's content by keywords. Free. */
+    search(query: string, opts?: {
+        limit?: number;
+    }): Promise<any>;
+    /** GET /v1/account — account profile + remaining credits. Free. */
+    account(): Promise<any>;
+    /** GET /v1/analytics — social analytics dashboard. Free but SLOW. */
+    analytics(opts?: {
+        period?: string;
+        start_date?: string;
+        end_date?: string;
+    }): Promise<any>;
+    /** GET /v1/roadmap — the account's content roadmap. Free. */
+    roadmap(opts?: {
+        cycle?: number;
+    }): Promise<any>;
+    /** GET /v1/production_plan — the weekly production plan. Free.
+     *  NOTE: passing both week_start + week_end may backfill rows upstream. */
+    production_plan(opts?: {
+        page?: number;
+        week_start?: string;
+        week_end?: string;
+    }): Promise<any>;
+    /** GET /v1/foundation_videos — curated foundation-video templates. Free. */
+    foundation_videos(opts?: {
+        industry?: string;
+        sub_industry?: string;
+        page?: number;
+    }): Promise<any>;
+    /** GET /v1/recommendations — recommended video ideas for an industry. Free. */
+    recommendations(opts?: {
+        industry?: string;
+        page?: number;
+    }): Promise<IdeasResponse>;
+    /** POST /v1/connect — get an OAuth link to connect a social platform. Free.
+     *  Returns `{object:"connect", url, expires_in, ...}` — the USER opens `url`
+     *  to complete the connection on the web (WideCast never performs the OAuth). */
+    connect(opts?: {
+        platform?: PublishPlatform;
+    }): Promise<any>;
+    /** GET /v1/accounts — list the account's connected social platforms. Free. */
+    accounts(): Promise<any>;
+    /** GET /v1/platform_settings — load saved per-platform publish settings. Free. */
+    platform_settings(): Promise<any>;
+    /** POST /v1/platform_settings — save one platform's publish settings. Free. */
+    set_platform_settings(platform: PublishPlatform, settings: Record<string, unknown>): Promise<any>;
+}
+declare class WebhookVerificationError extends Error {
+    constructor(m: string);
+}
+interface VerifyWebhookOptions {
+    body: string;
+    signatureHeader: string;
+    secret: string;
+    toleranceSeconds?: number;
+}
+declare function verifyWebhook(opts: VerifyWebhookOptions): Promise<any>;
+
+export { APIError, BLOG_MAX_WORDS, BLOG_MIN_WORDS, CONTENT_TYPES, type CollectIdeasOptions, type ContentType, type CreateContentOptions, type CreateVideoOptions, type EnhanceScriptOptions, type ErrorCode, FACELESS_SOURCES, IDEA_MAX_WORDS, IDEA_MIN_WORDS, INTERVENTION_LEVELS, type Idea, type IdeasResponse, type InterventionLevel, InvalidRequestError, LANGUAGES, type Language, MEDIA_MAX_DURATION_SECONDS, MEDIA_MAX_FILE_BYTES, MEDIA_SOURCES, NotFoundError, OUTPUT_TYPES, type OutputType, PUBLISH_PLATFORMS, PreconditionFailedError, type ProcessingDetails, type PublishOptions, type PublishPlatform, type PublishResponse, RateLimitError, SCRIPT_MAX_WORDS, SCRIPT_MIN_WORDS, SOURCES, type Source, type StatusError, type StatusResult, type SuggestIdeasOptions, VERSION, VIDEO_LENGTHS, type VerifyWebhookOptions, Video, type VideoLength, type VideoResource, type VideoStatus, type WaitOptions, WebhookVerificationError, Widecast, type WidecastConfig, WidecastError, Widecast as default, verifyWebhook };