@speechweave/node 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,375 @@
+import * as node_fs from 'node:fs';
+import { ReadStream } from 'node:fs';
+
+/** Job lifecycle status. Terminal: completed, failed, cancelled. */
+type PublicJobStatus = "queued" | "processing" | "completed" | "failed" | "cancelled" | string;
+/**
+ * Processing mode.
+ * API defaults to deferred when omitted. `asynchronous` is treated as deferred.
+ * Synchronous has an API size cap (default 512 MiB); use deferred for larger files.
+ */
+type ServiceMode = "synchronous" | "asynchronous" | "deferred" | string;
+interface V1Job {
+    /** Id from createJob / transcribeFile. */
+    id: string;
+    status: PublicJobStatus;
+    model?: string | null;
+    service_mode?: ServiceMode | null;
+    /** Two-letter ISO language code (e.g. 'en', 'es'). */
+    language?: string | null;
+    /** Full text when status is completed; otherwise null/absent. */
+    transcript?: string | null;
+    /** Audio duration in seconds, when known. */
+    duration?: number | null;
+    created_at?: string | null;
+    completed_at?: string | null;
+    /** Failure message when status is failed. */
+    error?: string | null;
+    /** 0–100 while processing, when the API reports it. */
+    progress?: number | null;
+    /** Coarse pipeline stage label while processing. */
+    stage?: string | null;
+}
+interface PresignResponse {
+    /** Short-lived URL for a PUT of the audio bytes. */
+    upload_url: string;
+    /** Pass to createJob as object_key after a successful PUT. */
+    object_key: string;
+    /** Seconds until upload_url expires. */
+    expires_in: number;
+    file_id?: string;
+    filename?: string;
+}
+/** Ack from job creation — no transcript yet; poll getJob or waitForJob. */
+interface CreateJobResponse {
+    id: string;
+    status: PublicJobStatus;
+    model?: string | null;
+    service_mode?: ServiceMode | null;
+    language?: string | null;
+    created_at?: string | null;
+}
+interface CancelJobResponse {
+    success: boolean;
+    status: string;
+}
+interface ListJobsResponse {
+    data?: V1Job[];
+    pagination?: {
+        page?: number;
+        limit?: number;
+        total?: number;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+interface SpeechWeaveClientOptions {
+    /** Falls back to SPEECHWEAVE_API_KEY. Required if the env var is unset. */
+    api_key?: string;
+    /** Defaults to https://api.speechweave.com/v1. */
+    base_url?: string;
+    /** Override global fetch (tests, custom agents). */
+    fetch_func?: typeof fetch;
+}
+
+/** Low-level SpeechWeave `/v1` client (presign, jobs, uploads). */
+declare class SpeechWeaveClient {
+    protected readonly api_key: string;
+    protected readonly base_url: string;
+    protected readonly fetch_func: typeof fetch;
+    /**
+     * @param options.api_key - Falls back to SPEECHWEAVE_API_KEY. Throws if neither is set.
+     * @param options.base_url - Defaults to https://api.speechweave.com/v1.
+     */
+    constructor(options?: SpeechWeaveClientOptions);
+    /**
+     * Authenticated fetch against base_url.
+     * Adds Bearer and User-Agent when missing. Path is relative (leading `/` optional).
+     */
+    rawFetch(path: string, init?: RequestInit): Promise<Response>;
+    protected requestJson<T>(method: string, path: string, json?: unknown, params?: Record<string, string | number | boolean | undefined | null>): Promise<T>;
+    /**
+     * Request a short-lived PUT URL and object_key for direct upload to storage.
+     *
+     * @param params.filename - Original name (used in the storage key).
+     * @param params.content_type - MIME type that must match the subsequent PUT.
+     */
+    presignUpload(params: {
+        filename: string;
+        content_type: string;
+    }): Promise<PresignResponse>;
+    /**
+     * PUT audio bytes to a presigned upload_url.
+     * Sets Content-Length when the body can be measured; pass file_size for pipes/live streams.
+     *
+     * @param uploadUrl - upload_url from presignUpload.
+     */
+    putToPresignedUrl(uploadUrl: string, body: Buffer | ReadStream | Blob, contentType: string, options?: {
+        file_size?: number;
+    }): Promise<void>;
+    /**
+     * Presign → PUT → create job. Returns the create ack (no transcript); poll getJob or waitForJob.
+     * Omitting service_mode leaves the API default (deferred). Synchronous rejects files over the sync size cap (default 512 MiB).
+     *
+     * @param options.filename - Defaults to audio.bin.
+     * @param options.content_type - Defaults to application/octet-stream.
+     * @param options.language - Two-letter ISO code (e.g. 'en', 'es').
+     * @param options.file_size - Content-Length when the body cannot be measured (pipes, live streams).
+     */
+    transcribeFile(file: ReadStream | Buffer | Blob, options?: {
+        filename?: string;
+        content_type?: string;
+        model?: string;
+        service_mode?: ServiceMode;
+        language?: string;
+        metadata?: Record<string, unknown>;
+        file_size?: number;
+    }): Promise<CreateJobResponse>;
+    /**
+     * Same as {@link transcribeFile}, then poll until completed, failed, or cancelled.
+     *
+     * @param options.wait_timeout_ms - Defaults to SPEECHWEAVE_JOB_WAIT_MS or 300_000.
+     * @param options.poll_ms - Poll interval; defaults to 1500.
+     */
+    transcribeFileBlocking(file: ReadStream | Buffer | Blob, options?: {
+        filename?: string;
+        content_type?: string;
+        model?: string;
+        service_mode?: ServiceMode;
+        language?: string;
+        metadata?: Record<string, unknown>;
+        file_size?: number;
+        wait_timeout_ms?: number;
+        poll_ms?: number;
+    }): Promise<V1Job>;
+    /**
+     * Create a transcription job from an already-uploaded object or a remote URL.
+     * Provide exactly one of object_key, input_url, or audio_url. type defaults to transcription.
+     * Omitting service_mode leaves the API default (deferred).
+     *
+     * @param params.object_key - From PresignResponse after a successful PUT.
+     * @param params.input_url - Publicly reachable audio URL.
+     * @param params.audio_url - Alias for input_url.
+     * @param params.language - Two-letter ISO code (e.g. 'en', 'es').
+     */
+    createJob(params: {
+        object_key?: string;
+        input_url?: string;
+        audio_url?: string;
+        model?: string;
+        service_mode?: ServiceMode;
+        language?: string;
+        type?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<CreateJobResponse>;
+    /**
+     * Fetch the current job record (status, transcript when completed, error when failed).
+     *
+     * @param job_id - Id from createJob / transcribeFile.
+     */
+    getJob(job_id: string): Promise<V1Job>;
+    /**
+     * List jobs for the authenticated account.
+     *
+     * @param params.status - Filter by PublicJobStatus value.
+     * @param params.page - 1-based page; API default if omitted.
+     * @param params.limit - Page size; API default if omitted.
+     */
+    listJobs(params?: {
+        page?: number;
+        limit?: number;
+        status?: string;
+    }): Promise<ListJobsResponse>;
+    /**
+     * Cancel a pending or processing job.
+     * Fails if the job is already completed, failed, or cancelled.
+     *
+     * @param job_id - Id from createJob / transcribeFile.
+     */
+    cancelJob(job_id: string): Promise<CancelJobResponse>;
+    /**
+     * Open a disk path and run {@link transcribeFile}.
+     * filename is taken from the path basename.
+     *
+     * @param file_path - Absolute or relative path on the local filesystem.
+     */
+    transcribeFilePath(file_path: string, options?: {
+        model?: string;
+        service_mode?: ServiceMode;
+        language?: string;
+        content_type?: string;
+        metadata?: Record<string, unknown>;
+        file_size?: number;
+    }): Promise<CreateJobResponse>;
+}
+
+declare class SpeechWeaveError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly body?: unknown;
+    readonly retry_after?: number;
+    constructor(message: string, status?: number, code?: string, body?: unknown, retry_after?: number);
+}
+
+interface WaitForJobOptions {
+    /** Max wait in ms; defaults to 3_600_000. */
+    timeout_ms?: number;
+    /** Interval between getJob polls; defaults to 2000. */
+    poll_ms?: number;
+}
+/**
+ * Poll getJob until completed, failed, or cancelled.
+ * Throws SpeechWeaveError with code JOB_WAIT_TIMEOUT on deadline.
+ *
+ * @param job_id - Id from createJob / transcribeFile.
+ */
+declare function waitForJob(client: SpeechWeaveClient, job_id: string, opts?: WaitForJobOptions): Promise<V1Job>;
+
+type UploadBody = Buffer | Blob | ReadStream | Uint8Array;
+declare function shapeOpenAiResponse(job: Record<string, unknown>): {
+    text: string;
+    task: "transcribe";
+    duration?: number;
+    language?: string;
+};
+declare function shapeDeepgramResponse(job: Record<string, unknown>, options?: {
+    model?: string | null;
+}): Record<string, unknown>;
+declare function shapeAssemblyResponse(job: Record<string, unknown>): Record<string, unknown>;
+declare function uploadAndCreateJob(client: SpeechWeaveClient, params: {
+    data: UploadBody;
+    filename: string;
+    content_type?: string;
+    model?: string;
+    language?: string;
+    service_mode?: ServiceMode;
+    metadata?: Record<string, unknown>;
+    file_size?: number;
+}): Promise<CreateJobResponse>;
+declare function createJobFromUrl(client: SpeechWeaveClient, params: {
+    url: string;
+    model?: string;
+    language?: string;
+    service_mode?: ServiceMode;
+    metadata?: Record<string, unknown>;
+}): Promise<CreateJobResponse>;
+declare function finishCompatJob(client: SpeechWeaveClient, job: CreateJobResponse | V1Job | Record<string, unknown>, options: {
+    wait: boolean;
+    error_code: string;
+    timeout_ms?: number;
+    poll_ms?: number;
+}): Promise<V1Job | CreateJobResponse | Record<string, unknown>>;
+
+declare const VERSION = "1.0.0";
+
+interface VerifyWebhookResult {
+    ok: boolean;
+    reason?: string;
+}
+/**
+ * Verify `SpeechWeave-Signature` header (Stripe-style: `t=unix,v1=hex` — may include multiple `v1=` during secret rotation).
+ *
+ * @param secret — active webhook signing secret, or array of `[active, previous]` during a rotation window
+ * @param raw_body — exact request body string (use raw bytes as UTF-8 string)
+ * @param signature_header — value of the `SpeechWeave-Signature` header
+ * @param tolerance_seconds — max clock skew; defaults to 300
+ */
+declare function verifyWebhook(secret: string | string[], raw_body: string, signature_header: string, tolerance_seconds?: number): VerifyWebhookResult;
+
+interface OpenAiTranscriptionCreateOptions {
+    file: UploadBody;
+    filename?: string;
+    model?: string;
+    language?: string;
+    file_size?: number;
+    wait?: boolean;
+}
+declare function createOpenAiAudioNamespace(client: SpeechWeaveClient): {
+    transcriptions: {
+        /** OpenAI-shaped transcription create — drop-in compatibility wrapper. */
+        create: (opts: OpenAiTranscriptionCreateOptions) => Promise<Record<string, unknown> | CreateJobResponse | {
+            text: string;
+            task: "transcribe";
+            duration?: number;
+            language?: string;
+        }>;
+    };
+};
+
+interface DeepgramTranscribeFileOptions {
+    model?: string;
+    filename?: string;
+    language?: string;
+    file_size?: number;
+    wait?: boolean;
+}
+interface DeepgramTranscribeUrlOptions {
+    model?: string;
+    language?: string;
+    wait?: boolean;
+}
+declare function createDeepgramListenNamespace(client: SpeechWeaveClient): {
+    prerecorded: {
+        /** Deepgram-shaped prerecorded file transcription — drop-in compatibility wrapper. */
+        transcribeFile: (stream: UploadBody | ReadStream, options?: DeepgramTranscribeFileOptions) => Promise<Record<string, unknown> | CreateJobResponse>;
+        /** Deepgram-shaped prerecorded URL transcription — drop-in compatibility wrapper. */
+        transcribeUrl: (url: string, options?: DeepgramTranscribeUrlOptions) => Promise<Record<string, unknown> | CreateJobResponse>;
+    };
+};
+
+interface AssemblyTranscribeConfig {
+    model?: string;
+    language?: string;
+    file_size?: number;
+}
+declare function createAssemblyTranscriptsNamespace(client: SpeechWeaveClient): {
+    /** AssemblyAI-shaped transcription — drop-in compatibility wrapper. Pass a URL string or binary/file body. */
+    transcribe: (audio: string | UploadBody | ReadStream, config?: AssemblyTranscribeConfig, options?: {
+        wait?: boolean;
+    }) => Promise<Record<string, unknown> | CreateJobResponse>;
+};
+
+declare function createJobsNamespace(client: SpeechWeaveClient): {
+    /**
+     * Create a job from a local file or a remote URL / object_key.
+     * Pass `file` (path, Buffer, Blob, or stream) to presign-upload then create.
+     * Otherwise pass one of `object_key`, `input_url`, or `audio_url` (no upload).
+     * Omitting service_mode leaves the API default (deferred).
+     */
+    create: (params: {
+        file?: string | Buffer | Blob | node_fs.ReadStream;
+        filename?: string;
+        content_type?: string;
+        object_key?: string;
+        input_url?: string;
+        audio_url?: string;
+        model?: string;
+        service_mode?: ServiceMode;
+        language?: string;
+        type?: string;
+        metadata?: Record<string, unknown>;
+        file_size?: number;
+    }) => Promise<CreateJobResponse>;
+    /** Fetch the current job record. */
+    get: (job_id: string) => Promise<V1Job>;
+    /** List jobs for the authenticated account. */
+    list: (params?: {
+        page?: number;
+        limit?: number;
+        status?: string;
+    }) => Promise<ListJobsResponse>;
+    /**
+     * Cancel a pending or processing job.
+     * Fails if the job is already completed, failed, or cancelled.
+     */
+    cancel: (job_id: string) => Promise<CancelJobResponse>;
+};
+declare class SpeechWeave extends SpeechWeaveClient {
+    readonly audio: ReturnType<typeof createOpenAiAudioNamespace>;
+    readonly listen: ReturnType<typeof createDeepgramListenNamespace>;
+    readonly transcripts: ReturnType<typeof createAssemblyTranscriptsNamespace>;
+    readonly jobs: ReturnType<typeof createJobsNamespace>;
+    constructor(options?: SpeechWeaveClientOptions);
+}
+
+export { type CreateJobResponse, type ListJobsResponse, type PresignResponse, type PublicJobStatus, type ServiceMode, SpeechWeave, SpeechWeaveClient, type SpeechWeaveClientOptions, SpeechWeaveError, type V1Job, VERSION, type VerifyWebhookResult, type WaitForJobOptions, createJobFromUrl, finishCompatJob, shapeAssemblyResponse, shapeDeepgramResponse, shapeOpenAiResponse, uploadAndCreateJob, verifyWebhook, waitForJob };