sonilo 0.1.0 → 0.2.1

package/dist/index.d.cts

@@ -51,6 +51,11 @@ interface TextToMusicParams {
     prompt: string;
     duration: number;
     segments?: Segment[];
+    /** Bounds the stream: aborting this cancels the in-flight generation.
+     * Passed straight through to `fetch` — it is never rewrapped as
+     * RequestTimeoutError, since the client's own absolute timeout does not
+     * apply to streaming music generation. */
+    signal?: AbortSignal;
 }
 /** string = file path (Node.js only). */
 type VideoInput = File | Blob | Uint8Array | ArrayBuffer | ReadableStream<Uint8Array> | string;
@@ -59,6 +64,11 @@ interface VideoToMusicParams {
     videoUrl?: string;
     prompt?: string;
     segments?: Segment[];
+    /** Bounds the stream: aborting this cancels the in-flight generation.
+     * Passed straight through to `fetch` — it is never rewrapped as
+     * RequestTimeoutError, since the client's own absolute timeout does not
+     * apply to streaming music generation. */
+    signal?: AbortSignal;
 }
 interface AccountServices {
     available_services: string[];
@@ -87,6 +97,61 @@ interface UsageResponse {
 }
 declare function isAudioChunkEvent(event: StreamEvent): event is AudioChunkEvent;
 declare function isErrorEvent(event: StreamEvent): event is ErrorEvent;
+/** SFX segments (unlike music `Segment`) require `end`, must start at 0,
+ * and be contiguous; validated server-side. */
+interface SfxSegment {
+    start: number;
+    end: number;
+    prompt: string;
+}
+type SfxAudioFormat = "wav" | "mp3" | "aac" | "flac";
+/** Submission ack for the async SFX endpoints. */
+interface SfxTask {
+    task_id: string;
+    status: string;
+}
+/** A generated file re-hosted on R2 behind a presigned URL. */
+interface SfxMedia {
+    url: string;
+    content_type?: string;
+    file_size?: number;
+}
+interface SfxError {
+    code?: string;
+    message?: string;
+}
+/** State of an SFX task (`tasks.get`) or its final result (`wait`/`generate`). */
+interface SfxResult {
+    task_id: string;
+    type?: string;
+    status: "processing" | "succeeded" | "failed" | (string & {});
+    audio?: SfxMedia;
+    /** Kept for backward compatibility; no longer populated — video-to-sfx returns audio only. */
+    video?: SfxMedia;
+    /** Only present when the account's task-field whitelist enables cost. */
+    cost?: number;
+    error?: SfxError;
+    refunded?: boolean;
+    [key: string]: unknown;
+}
+interface TextToSfxParams {
+    prompt: string;
+    duration: number;
+    audioFormat?: SfxAudioFormat;
+}
+interface VideoToSfxParams {
+    video?: VideoInput;
+    videoUrl?: string;
+    prompt?: string;
+    segments?: SfxSegment[];
+    audioFormat?: SfxAudioFormat;
+}
+interface WaitOptions {
+    /** Milliseconds between polls. Default 2000. */
+    pollInterval?: number;
+    /** Overall deadline in milliseconds. Default 600000. */
+    timeout?: number;
+}
 
 declare class Account {
     private readonly client;
@@ -97,6 +162,15 @@ declare class Account {
     }): Promise<UsageResponse>;
 }
 
+declare class Tasks {
+    private readonly client;
+    constructor(client: SoniloClient);
+    /** Fetch current task state. Never throws on a failed status. */
+    get(taskId: string): Promise<SfxResult>;
+    /** Poll until the task is terminal; throw on failure or deadline. */
+    wait(taskId: string, opts?: WaitOptions): Promise<SfxResult>;
+}
+
 declare class TextToMusic {
     private readonly client;
     constructor(client: SoniloClient);
@@ -113,6 +187,20 @@ declare class VideoToMusic {
     generate(params: VideoToMusicParams): Promise<Track>;
 }
 
+declare class TextToSfx {
+    private readonly client;
+    constructor(client: SoniloClient);
+    submit(params: TextToSfxParams): Promise<SfxTask>;
+    generate(params: TextToSfxParams, opts?: WaitOptions): Promise<SfxResult>;
+}
+
+declare class VideoToSfx {
+    private readonly client;
+    constructor(client: SoniloClient);
+    submit(params: VideoToSfxParams): Promise<SfxTask>;
+    generate(params: VideoToSfxParams, opts?: WaitOptions): Promise<SfxResult>;
+}
+
 interface SoniloClientOptions {
     /** Defaults to the SONILO_API_KEY environment variable (Node.js only). */
     apiKey?: string;
@@ -120,17 +208,34 @@ interface SoniloClientOptions {
     baseUrl?: string;
     /** Injection point for tests and custom transports. */
     fetch?: typeof globalThis.fetch;
+    /** Milliseconds before an in-flight request is aborted. Default 600000. */
+    timeout?: number;
 }
+/** Milliseconds before an in-flight request is aborted, unless overridden. */
+declare const DEFAULT_TIMEOUT_MS = 600000;
 declare class SoniloClient {
     readonly baseUrl: string;
     private readonly apiKey;
     private readonly fetchFn;
+    private readonly timeout;
     readonly account: Account;
+    readonly tasks: Tasks;
     readonly textToMusic: TextToMusic;
     readonly videoToMusic: VideoToMusic;
+    readonly textToSfx: TextToSfx;
+    readonly videoToSfx: VideoToSfx;
     constructor(options?: SoniloClientOptions);
-    /** Perform an authenticated request; throws a typed error on non-2xx. */
-    request(path: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Perform an authenticated request; throws a typed error on non-2xx.
+     *
+     * `opts.timeout` overrides the client's default timeout for this call;
+     * pass `null` to disable the abort-on-timeout behavior entirely (used by
+     * the streaming music endpoints — see textToMusic.ts / videoToMusic.ts).
+     * A caller-supplied `init.signal` always wins over any timeout signal.
+     */
+    request(path: string, init?: RequestInit, opts?: {
+        timeout?: number | null;
+    }): Promise<Response>;
 }
 
 declare class SoniloError extends Error {
@@ -139,6 +244,10 @@ declare class SoniloError extends Error {
 declare class APIError extends SoniloError {
     readonly status: number;
     readonly body: unknown;
+    /** The API's typed error code (e.g. "rate_limit_exceeded"), distinct from the HTTP status. */
+    readonly code?: string;
+    /** Per-field validation details, present on a 422. */
+    readonly errors?: unknown[];
     constructor(message: string, status: number, body?: unknown);
 }
 declare class AuthenticationError extends APIError {
@@ -157,7 +266,32 @@ declare class GenerationError extends SoniloError {
     readonly code?: string;
     constructor(message: string, code?: string);
 }
+/** Raised by tasks.wait()/generate() when an SFX task reaches `failed`. */
+declare class TaskFailedError extends SoniloError {
+    readonly code?: string;
+    readonly taskId: string;
+    readonly refunded?: boolean;
+    constructor(message: string, opts: {
+        code?: string;
+        taskId: string;
+        refunded?: boolean;
+    });
+}
+/** Poll deadline passed. The task may still finish server-side — resume with
+ * tasks.wait(taskId) or tasks.get(taskId). */
+declare class TaskTimeoutError extends SoniloError {
+    readonly taskId: string;
+    constructor(message: string, taskId: string);
+}
+/** Raised when a one-shot request or download is aborted by its own timeout
+ * signal (as opposed to a caller-supplied AbortSignal, which propagates
+ * untouched). */
+declare class RequestTimeoutError extends SoniloError {
+}
+
+/** Fetch a result media file. The URL is presigned — no API key is sent. */
+declare function download(media: SfxMedia | undefined, fetchFn?: typeof globalThis.fetch, timeout?: number): Promise<Uint8Array>;
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.2.0";
 
-export { APIError, type AccountServices, type AudioChunkEvent, AuthenticationError, BadRequestError, type CompleteEvent, type CostEvent, type CostInfo, type DailyUsage, type ErrorEvent, GenerationError, PaymentRequiredError, RateLimitError, type Segment, type SegmentLabel, SoniloClient, type SoniloClientOptions, SoniloError, type StreamEvent, type TextToMusicParams, type TitleEvent, type Track, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, type VideoInput, type VideoToMusicParams, isAudioChunkEvent, isErrorEvent };
+export { APIError, type AccountServices, type AudioChunkEvent, AuthenticationError, BadRequestError, type CompleteEvent, type CostEvent, type CostInfo, DEFAULT_TIMEOUT_MS, type DailyUsage, type ErrorEvent, GenerationError, PaymentRequiredError, RateLimitError, RequestTimeoutError, type Segment, type SegmentLabel, type SfxAudioFormat, type SfxError, type SfxMedia, type SfxResult, type SfxSegment, type SfxTask, SoniloClient, type SoniloClientOptions, SoniloError, type StreamEvent, TaskFailedError, TaskTimeoutError, type TextToMusicParams, type TextToSfxParams, type TitleEvent, type Track, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, type VideoInput, type VideoToMusicParams, type VideoToSfxParams, type WaitOptions, download, isAudioChunkEvent, isErrorEvent };

package/dist/index.d.ts

@@ -51,6 +51,11 @@ interface TextToMusicParams {
     prompt: string;
     duration: number;
     segments?: Segment[];
+    /** Bounds the stream: aborting this cancels the in-flight generation.
+     * Passed straight through to `fetch` — it is never rewrapped as
+     * RequestTimeoutError, since the client's own absolute timeout does not
+     * apply to streaming music generation. */
+    signal?: AbortSignal;
 }
 /** string = file path (Node.js only). */
 type VideoInput = File | Blob | Uint8Array | ArrayBuffer | ReadableStream<Uint8Array> | string;
@@ -59,6 +64,11 @@ interface VideoToMusicParams {
     videoUrl?: string;
     prompt?: string;
     segments?: Segment[];
+    /** Bounds the stream: aborting this cancels the in-flight generation.
+     * Passed straight through to `fetch` — it is never rewrapped as
+     * RequestTimeoutError, since the client's own absolute timeout does not
+     * apply to streaming music generation. */
+    signal?: AbortSignal;
 }
 interface AccountServices {
     available_services: string[];
@@ -87,6 +97,61 @@ interface UsageResponse {
 }
 declare function isAudioChunkEvent(event: StreamEvent): event is AudioChunkEvent;
 declare function isErrorEvent(event: StreamEvent): event is ErrorEvent;
+/** SFX segments (unlike music `Segment`) require `end`, must start at 0,
+ * and be contiguous; validated server-side. */
+interface SfxSegment {
+    start: number;
+    end: number;
+    prompt: string;
+}
+type SfxAudioFormat = "wav" | "mp3" | "aac" | "flac";
+/** Submission ack for the async SFX endpoints. */
+interface SfxTask {
+    task_id: string;
+    status: string;
+}
+/** A generated file re-hosted on R2 behind a presigned URL. */
+interface SfxMedia {
+    url: string;
+    content_type?: string;
+    file_size?: number;
+}
+interface SfxError {
+    code?: string;
+    message?: string;
+}
+/** State of an SFX task (`tasks.get`) or its final result (`wait`/`generate`). */
+interface SfxResult {
+    task_id: string;
+    type?: string;
+    status: "processing" | "succeeded" | "failed" | (string & {});
+    audio?: SfxMedia;
+    /** Kept for backward compatibility; no longer populated — video-to-sfx returns audio only. */
+    video?: SfxMedia;
+    /** Only present when the account's task-field whitelist enables cost. */
+    cost?: number;
+    error?: SfxError;
+    refunded?: boolean;
+    [key: string]: unknown;
+}
+interface TextToSfxParams {
+    prompt: string;
+    duration: number;
+    audioFormat?: SfxAudioFormat;
+}
+interface VideoToSfxParams {
+    video?: VideoInput;
+    videoUrl?: string;
+    prompt?: string;
+    segments?: SfxSegment[];
+    audioFormat?: SfxAudioFormat;
+}
+interface WaitOptions {
+    /** Milliseconds between polls. Default 2000. */
+    pollInterval?: number;
+    /** Overall deadline in milliseconds. Default 600000. */
+    timeout?: number;
+}
 
 declare class Account {
     private readonly client;
@@ -97,6 +162,15 @@ declare class Account {
     }): Promise<UsageResponse>;
 }
 
+declare class Tasks {
+    private readonly client;
+    constructor(client: SoniloClient);
+    /** Fetch current task state. Never throws on a failed status. */
+    get(taskId: string): Promise<SfxResult>;
+    /** Poll until the task is terminal; throw on failure or deadline. */
+    wait(taskId: string, opts?: WaitOptions): Promise<SfxResult>;
+}
+
 declare class TextToMusic {
     private readonly client;
     constructor(client: SoniloClient);
@@ -113,6 +187,20 @@ declare class VideoToMusic {
     generate(params: VideoToMusicParams): Promise<Track>;
 }
 
+declare class TextToSfx {
+    private readonly client;
+    constructor(client: SoniloClient);
+    submit(params: TextToSfxParams): Promise<SfxTask>;
+    generate(params: TextToSfxParams, opts?: WaitOptions): Promise<SfxResult>;
+}
+
+declare class VideoToSfx {
+    private readonly client;
+    constructor(client: SoniloClient);
+    submit(params: VideoToSfxParams): Promise<SfxTask>;
+    generate(params: VideoToSfxParams, opts?: WaitOptions): Promise<SfxResult>;
+}
+
 interface SoniloClientOptions {
     /** Defaults to the SONILO_API_KEY environment variable (Node.js only). */
     apiKey?: string;
@@ -120,17 +208,34 @@ interface SoniloClientOptions {
     baseUrl?: string;
     /** Injection point for tests and custom transports. */
     fetch?: typeof globalThis.fetch;
+    /** Milliseconds before an in-flight request is aborted. Default 600000. */
+    timeout?: number;
 }
+/** Milliseconds before an in-flight request is aborted, unless overridden. */
+declare const DEFAULT_TIMEOUT_MS = 600000;
 declare class SoniloClient {
     readonly baseUrl: string;
     private readonly apiKey;
     private readonly fetchFn;
+    private readonly timeout;
     readonly account: Account;
+    readonly tasks: Tasks;
     readonly textToMusic: TextToMusic;
     readonly videoToMusic: VideoToMusic;
+    readonly textToSfx: TextToSfx;
+    readonly videoToSfx: VideoToSfx;
     constructor(options?: SoniloClientOptions);
-    /** Perform an authenticated request; throws a typed error on non-2xx. */
-    request(path: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Perform an authenticated request; throws a typed error on non-2xx.
+     *
+     * `opts.timeout` overrides the client's default timeout for this call;
+     * pass `null` to disable the abort-on-timeout behavior entirely (used by
+     * the streaming music endpoints — see textToMusic.ts / videoToMusic.ts).
+     * A caller-supplied `init.signal` always wins over any timeout signal.
+     */
+    request(path: string, init?: RequestInit, opts?: {
+        timeout?: number | null;
+    }): Promise<Response>;
 }
 
 declare class SoniloError extends Error {
@@ -139,6 +244,10 @@ declare class SoniloError extends Error {
 declare class APIError extends SoniloError {
     readonly status: number;
     readonly body: unknown;
+    /** The API's typed error code (e.g. "rate_limit_exceeded"), distinct from the HTTP status. */
+    readonly code?: string;
+    /** Per-field validation details, present on a 422. */
+    readonly errors?: unknown[];
     constructor(message: string, status: number, body?: unknown);
 }
 declare class AuthenticationError extends APIError {
@@ -157,7 +266,32 @@ declare class GenerationError extends SoniloError {
     readonly code?: string;
     constructor(message: string, code?: string);
 }
+/** Raised by tasks.wait()/generate() when an SFX task reaches `failed`. */
+declare class TaskFailedError extends SoniloError {
+    readonly code?: string;
+    readonly taskId: string;
+    readonly refunded?: boolean;
+    constructor(message: string, opts: {
+        code?: string;
+        taskId: string;
+        refunded?: boolean;
+    });
+}
+/** Poll deadline passed. The task may still finish server-side — resume with
+ * tasks.wait(taskId) or tasks.get(taskId). */
+declare class TaskTimeoutError extends SoniloError {
+    readonly taskId: string;
+    constructor(message: string, taskId: string);
+}
+/** Raised when a one-shot request or download is aborted by its own timeout
+ * signal (as opposed to a caller-supplied AbortSignal, which propagates
+ * untouched). */
+declare class RequestTimeoutError extends SoniloError {
+}
+
+/** Fetch a result media file. The URL is presigned — no API key is sent. */
+declare function download(media: SfxMedia | undefined, fetchFn?: typeof globalThis.fetch, timeout?: number): Promise<Uint8Array>;
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.2.0";
 
-export { APIError, type AccountServices, type AudioChunkEvent, AuthenticationError, BadRequestError, type CompleteEvent, type CostEvent, type CostInfo, type DailyUsage, type ErrorEvent, GenerationError, PaymentRequiredError, RateLimitError, type Segment, type SegmentLabel, SoniloClient, type SoniloClientOptions, SoniloError, type StreamEvent, type TextToMusicParams, type TitleEvent, type Track, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, type VideoInput, type VideoToMusicParams, isAudioChunkEvent, isErrorEvent };
+export { APIError, type AccountServices, type AudioChunkEvent, AuthenticationError, BadRequestError, type CompleteEvent, type CostEvent, type CostInfo, DEFAULT_TIMEOUT_MS, type DailyUsage, type ErrorEvent, GenerationError, PaymentRequiredError, RateLimitError, RequestTimeoutError, type Segment, type SegmentLabel, type SfxAudioFormat, type SfxError, type SfxMedia, type SfxResult, type SfxSegment, type SfxTask, SoniloClient, type SoniloClientOptions, SoniloError, type StreamEvent, TaskFailedError, TaskTimeoutError, type TextToMusicParams, type TextToSfxParams, type TitleEvent, type Track, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, type VideoInput, type VideoToMusicParams, type VideoToSfxParams, type WaitOptions, download, isAudioChunkEvent, isErrorEvent };