songbrain 0.1.2 → 0.3.0

package/dist/index.d.cts

@@ -124,11 +124,27 @@ interface LyricLine {
     start: number;
     end: number;
     text: string;
+    /** 0-1 transcription confidence; null when the words were provided. */
+    confidence?: number | null;
     /** Omitted in view=summary. */
     words?: Word[];
 }
+interface LyricsAlignment {
+    /** Share of the provided words that were found in the audio. */
+    match_ratio?: number | null;
+    reference_words?: number | null;
+    corrected_words?: number | null;
+    /** false when the provided lyrics did not match the audio well enough. */
+    used?: boolean;
+    reason?: string;
+}
 interface Lyrics {
     language?: string | null;
+    /** Where the words come from. */
+    source?: "transcribed" | "provided_lyrics" | "suno_lyrics";
+    basis?: "transcribed" | "provided";
+    note?: string;
+    alignment?: LyricsAlignment;
     lines?: LyricLine[];
     /** true for recognised commercial recordings; then `lines` is absent. */
     hidden?: boolean;
@@ -139,6 +155,17 @@ interface ScoreBlock {
     score: number;
     breakdown: Record<string, number>;
     note?: string;
+    /** "model_estimate": an AI model's listening judgement, not a measurement. */
+    basis?: "model_estimate";
+}
+/** Which fields are measured from the audio and which are a model's reading. */
+interface Provenance {
+    measured: string[];
+    transcribed: string[];
+    model_estimate: string[];
+    generated: string[];
+    confidence_fields: string[];
+    doc: string;
 }
 interface WhatWorks {
     title: string;
@@ -158,6 +185,8 @@ interface Scores {
     what_works: WhatWorks[];
     what_to_fix: WhatToFix[];
     audience: string[];
+    basis?: "model_estimate";
+    basis_note?: string;
 }
 interface StoryElement {
     /** The one object the video is about. */
@@ -273,6 +302,8 @@ interface ShotPlan {
 interface ErrorInfo {
     code: string;
     message: string;
+    /** "req_…", also in the Songbrain-Request-Id header. */
+    request_id?: string;
 }
 /**
  * The song document. While processing, only `id`, `status`, `progress` and
@@ -298,6 +329,10 @@ interface Song {
     created_at?: string | null;
     external_ref?: string | null;
     billing?: Billing;
+    /** false for test-mode songs. */
+    livemode?: boolean;
+    /** Measured vs. transcribed vs. model estimate vs. generated. */
+    provenance?: Provenance;
 }
 /** The 202 body of POST /songs. */
 interface SongCreated {
@@ -308,6 +343,7 @@ interface SongCreated {
     billing: Billing;
     external_ref?: string | null;
     url: string;
+    livemode?: boolean;
 }
 /** GET /songs/{id}/shot-plan and GET /examples/{id}/shot-plan. */
 interface SongShotPlan {
@@ -323,10 +359,14 @@ interface SongListItem {
     external_ref: string | null;
     created_at: string | null;
     billing: Billing;
+    livemode?: boolean;
 }
 interface SongList {
     object: "list";
     data: SongListItem[];
+    has_more?: boolean;
+    /** Pass as `startingAfter` for the next page. */
+    next_cursor?: string | null;
 }
 interface DeleteResult {
     id: string;
@@ -383,11 +423,44 @@ interface Pricing {
 }
 /** A webhook event body. */
 interface WebhookEvent<T = Record<string, unknown>> {
-    type: "song.done" | "song.failed" | "account.low_balance" | (string & {});
+    /** "evt_…". Stays the same across retries of one event: dedupe on it. */
+    id: string;
+    type: "song.done" | "song.failed" | "account.low_balance" | "ping" | (string & {});
     /** Unix seconds. */
     created: number;
+    livemode: boolean;
     data: T;
 }
+/** From the X-RateLimit-* headers. See `Songbrain.lastRateLimit`. */
+interface RateLimitInfo {
+    /** Requests per minute. */
+    limit: number;
+    remaining: number | null;
+    /** Seconds until the window has room again. */
+    reset: number | null;
+}
+/** POST /webhooks/test. */
+interface WebhookTestResult {
+    delivered: boolean;
+    status_code: number | null;
+    latency_ms: number;
+    event_id: string;
+}
+interface WebhookDelivery {
+    event_id: string;
+    type: WebhookEvent["type"];
+    song_id: string | null;
+    url: string;
+    attempt: number;
+    status_code: number | null;
+    delivered: boolean;
+    latency_ms: number | null;
+    created_at: string;
+}
+interface WebhookDeliveryList {
+    object: "list";
+    data: WebhookDelivery[];
+}
 
 declare const DEFAULT_BASE_URL = "https://api.songbrain.ai/v1";
 /** A Blob/File, a Buffer or bytes, or a local file path (Node). */
@@ -399,7 +472,10 @@ interface SongbrainOptions {
     baseUrl?: string;
     /** Timeout for each HTTP request in ms (uploads included). Default 60 000. */
     timeoutMs?: number;
-    /** How often to retry 429 and 5xx responses, with backoff. Default 3. */
+    /**
+     * How often to retry network errors, 429 and 5xx responses, with backoff. Default 3.
+     * Song creation is retried too, because every create sends an `Idempotency-Key`.
+     */
     maxRetries?: number;
     /** A custom fetch implementation. Defaults to the global fetch. */
     fetch?: typeof fetch;
@@ -417,6 +493,25 @@ interface AnalyzeOptions {
     externalRef?: string;
     /** File name for an upload. Its extension must match the audio format. Taken from the path or File name, or guessed from the bytes. */
     filename?: string;
+    /**
+     * The song's lyrics as plain text (up to 20,000 characters), e.g. from Suno. The
+     * analysis then uses your exact words on the transcription's timing
+     * (`lyrics.source` = "provided_lyrics"); words the singer can't be heard on are
+     * left out, never guessed.
+     */
+    lyrics?: string;
+    /**
+     * Test mode: free, never charged, no audio needed. The song is done right away and
+     * returns the Sugar Rush example analysis with `livemode: false`. `song.done` is
+     * still sent to `webhookUrl`. Made for CI and integration tests.
+     */
+    test?: boolean;
+    /**
+     * Sent as `Idempotency-Key`. By default a random UUID per call, reused across the
+     * client's own retries, so a retried create never makes a second song. Pass your
+     * own (e.g. your job id) to make retries across processes safe too (24 h window).
+     */
+    idempotencyKey?: string;
     /** Wait until the song is done and return the full document (default true). */
     wait?: boolean;
     /** Time between status checks while waiting. Default 5 000. */
@@ -428,6 +523,18 @@ interface WaitOptions {
     pollIntervalMs?: number;
     timeoutMs?: number;
 }
+interface ListSongsOptions {
+    /** Page size, 1-100. Default 20. */
+    limit?: number;
+    /** A song id, usually the previous page's `next_cursor`. Returns the songs after it. */
+    startingAfter?: string;
+}
+interface IterSongsOptions {
+    /** Songs per request, 1-100. Default 100. */
+    pageSize?: number;
+    /** Start after this song id. */
+    startingAfter?: string;
+}
 interface GetSongOptions {
     /** "summary" drops word timings and beat arrays (about 3x smaller). */
     view?: "full" | "summary";
@@ -450,11 +557,19 @@ declare class Songbrain {
     readonly timeoutMs: number;
     readonly maxRetries: number;
     private readonly fetchImpl;
+    /**
+     * `{ limit, remaining, reset }` from the `X-RateLimit-*` headers of the last response
+     * that had them (null before that). `reset` is seconds until the window has room.
+     */
+    lastRateLimit: RateLimitInfo | null;
+    /** The `Songbrain-Request-Id` of the last response (null before the first one). */
+    lastRequestId: string | null;
     /** @internal Overridable in tests. */
     _sleep: (ms: number) => Promise<void>;
     constructor(options?: SongbrainOptions);
     /**
-     * Analyse a song from a file or a public URL. Pass exactly one of `file` or `audioUrl`.
+     * Analyse a song from a file or a public URL. Pass exactly one of `file` or `audioUrl`
+     * (or neither with `test: true`).
      * Typically 60-90 s. With `wait: true` (default) resolves to the full document;
      * with `wait: false` to the 202 body `{ id, status: "processing", eta_sec, billing }`.
      */
@@ -471,16 +586,31 @@ declare class Songbrain {
     getSong(songId: string, options?: GetSongOptions): Promise<Song>;
     /** Only the story and the shot plan: `{ id, status, song, story, shot_plan }`. */
     shotPlan(songId: string): Promise<SongShotPlan>;
-    /** Your songs, newest first. `limit` is 1-100 (default 20). */
-    listSongs(options?: {
-        limit?: number;
-    }): Promise<SongList>;
+    /** One page of your songs, newest first: `{ object: "list", data, has_more, next_cursor }`. */
+    listSongs(options?: ListSongsOptions): Promise<SongList>;
+    /**
+     * All your songs, newest first, fetching pages as needed.
+     *
+     * ```ts
+     * for await (const item of sb.iterSongs()) console.log(item.id, item.status);
+     * ```
+     */
+    iterSongs(options?: IterSongsOptions): AsyncGenerator<SongListItem, void, undefined>;
     /** Delete a song's audio and analysis now. 409 `still_processing` while it runs. */
     deleteSong(songId: string): Promise<DeleteResult>;
     /** Free songs left this month, credit balance and price per song. */
     account(): Promise<Account>;
     /** Prices and limits. No key needed. */
     pricing(): Promise<Pricing>;
+    /**
+     * Send a signed `ping` event to `url` right now:
+     * `{ delivered, status_code, latency_ms, event_id }`. Checks your receiver before real songs.
+     */
+    testWebhook(url: string): Promise<WebhookTestResult>;
+    /** The last webhook delivery attempts for your account, newest first. */
+    webhookDeliveries(options?: {
+        limit?: number;
+    }): Promise<WebhookDeliveryList>;
     /** Example analyses of Songbrain's own songs. No key needed. */
     examples(): Promise<ExampleList>;
     /** A full example document, in the same format as `getSong`. No key needed. */
@@ -492,9 +622,10 @@ declare class Songbrain {
 }
 
 /**
- * Every API error has the shape `{ error: { code, message } }`. The client
- * turns it into a `SongbrainError` (or a subclass) with `status`, `code` and
- * `message`.
+ * Every API error has the shape `{ error: { code, message, request_id } }`.
+ * The client turns it into a `SongbrainError` (or a subclass) with `status`,
+ * `code`, `message` and `requestId`. The message ends with
+ * ` (request_id: req_…)` when there is one; quote it when you contact support.
  */
 declare class SongbrainError extends Error {
     /** HTTP status, or 0 when the error did not come from an HTTP response. */
@@ -503,7 +634,9 @@ declare class SongbrainError extends Error {
     readonly code: string;
     /** The parsed response body, when there was one. */
     readonly body: unknown;
-    constructor(status: number, code: string, message: string, body?: unknown);
+    /** The `Songbrain-Request-Id` of the failed request (`req_…`), or null. */
+    readonly requestId: string | null;
+    constructor(status: number, code: string, message: string, body?: unknown, requestId?: string | null);
 }
 /** 401: the API key is missing, invalid or revoked. */
 declare class AuthenticationError extends SongbrainError {
@@ -518,7 +651,7 @@ declare class NotFound extends SongbrainError {
 declare class RateLimited extends SongbrainError {
     /** Seconds to wait, from the Retry-After header (null if absent). */
     readonly retryAfter: number | null;
-    constructor(status: number, code: string, message: string, body?: unknown, retryAfter?: number | null);
+    constructor(status: number, code: string, message: string, body?: unknown, retryAfter?: number | null, requestId?: string | null);
 }
 /** The song was accepted but its analysis failed. Paid credits are refunded automatically. */
 declare class AnalysisFailed extends SongbrainError {
@@ -546,13 +679,17 @@ type RawBody = string | Uint8Array | ArrayBuffer;
 declare function verifyWebhook(rawBody: RawBody, header: string | null | undefined, secret: string, toleranceSec?: number): boolean;
 /**
  * Verify the signature and return the parsed event:
- * `{ type: "song.done" | "song.failed" | "account.low_balance", created, data }`.
+ * `{ id, type: "song.done" | "song.failed" | "account.low_balance" | "ping", created, livemode, data }`.
  * Throws if the signature is not valid.
+ *
+ * `id` (`evt_…`, also the `Songbrain-Event-Id` header) stays the same when
+ * Songbrain retries an event (up to 10 attempts over about 3 days): store the
+ * ids you have handled and skip repeats.
  */
 declare function constructWebhookEvent<T = Record<string, unknown>>(rawBody: RawBody, header: string | null | undefined, secret: string, toleranceSec?: number): WebhookEvent<T>;
 /** Build a signature header value. Useful to test your webhook handler. */
 declare function signWebhook(rawBody: RawBody, secret: string, timestampSec?: number): string;
 
-declare const VERSION = "0.1.2";
+declare const VERSION = "0.3.0";
 
-export { type Account, type Act, AnalysisFailed, type AnalyzeOptions, AuthenticationError, type BestMoment, type Billing, type Clip, DEFAULT_BASE_URL, type DeleteResult, type ErrorInfo, type ExampleList, type ExampleSummary, type FileInput, type FullSong, type FullSongSection, type GetSongOptions, type Instrument, InsufficientCredits, type KeyChange, type LoudnessCheck, type LyricHook, type LyricLine, type Lyrics, NotFound, type Phases, type Pricing, RateLimited, SIGNATURE_HEADER, type Scene, type SceneKind, type ScoreBlock, type Scores, type Section, type SectionName, type ShotPlan, type ShotStyle, type Song, type SongCreated, type SongDNA, type SongInfo, type SongList, type SongListItem, type SongShotPlan, type SongStatus, Songbrain, SongbrainError, type SongbrainOptions, type SoundsLike, type Story, type StoryBeats, type StoryElement, type Timeline, VERSION, type VocalChange, type WaitOptions, WaitTimeout, type WebhookEvent, type WhatToFix, type WhatWorks, type Word, constructWebhookEvent, signWebhook, verifyWebhook };
+export { type Account, type Act, AnalysisFailed, type AnalyzeOptions, AuthenticationError, type BestMoment, type Billing, type Clip, DEFAULT_BASE_URL, type DeleteResult, type ErrorInfo, type ExampleList, type ExampleSummary, type FileInput, type FullSong, type FullSongSection, type GetSongOptions, type Instrument, InsufficientCredits, type IterSongsOptions, type KeyChange, type ListSongsOptions, type LoudnessCheck, type LyricHook, type LyricLine, type Lyrics, type LyricsAlignment, NotFound, type Phases, type Pricing, type Provenance, type RateLimitInfo, RateLimited, SIGNATURE_HEADER, type Scene, type SceneKind, type ScoreBlock, type Scores, type Section, type SectionName, type ShotPlan, type ShotStyle, type Song, type SongCreated, type SongDNA, type SongInfo, type SongList, type SongListItem, type SongShotPlan, type SongStatus, Songbrain, SongbrainError, type SongbrainOptions, type SoundsLike, type Story, type StoryBeats, type StoryElement, type Timeline, VERSION, type VocalChange, type WaitOptions, WaitTimeout, type WebhookDelivery, type WebhookDeliveryList, type WebhookEvent, type WebhookTestResult, type WhatToFix, type WhatWorks, type Word, constructWebhookEvent, signWebhook, verifyWebhook };

package/dist/index.d.ts

@@ -124,11 +124,27 @@ interface LyricLine {
     start: number;
     end: number;
     text: string;
+    /** 0-1 transcription confidence; null when the words were provided. */
+    confidence?: number | null;
     /** Omitted in view=summary. */
     words?: Word[];
 }
+interface LyricsAlignment {
+    /** Share of the provided words that were found in the audio. */
+    match_ratio?: number | null;
+    reference_words?: number | null;
+    corrected_words?: number | null;
+    /** false when the provided lyrics did not match the audio well enough. */
+    used?: boolean;
+    reason?: string;
+}
 interface Lyrics {
     language?: string | null;
+    /** Where the words come from. */
+    source?: "transcribed" | "provided_lyrics" | "suno_lyrics";
+    basis?: "transcribed" | "provided";
+    note?: string;
+    alignment?: LyricsAlignment;
     lines?: LyricLine[];
     /** true for recognised commercial recordings; then `lines` is absent. */
     hidden?: boolean;
@@ -139,6 +155,17 @@ interface ScoreBlock {
     score: number;
     breakdown: Record<string, number>;
     note?: string;
+    /** "model_estimate": an AI model's listening judgement, not a measurement. */
+    basis?: "model_estimate";
+}
+/** Which fields are measured from the audio and which are a model's reading. */
+interface Provenance {
+    measured: string[];
+    transcribed: string[];
+    model_estimate: string[];
+    generated: string[];
+    confidence_fields: string[];
+    doc: string;
 }
 interface WhatWorks {
     title: string;
@@ -158,6 +185,8 @@ interface Scores {
     what_works: WhatWorks[];
     what_to_fix: WhatToFix[];
     audience: string[];
+    basis?: "model_estimate";
+    basis_note?: string;
 }
 interface StoryElement {
     /** The one object the video is about. */
@@ -273,6 +302,8 @@ interface ShotPlan {
 interface ErrorInfo {
     code: string;
     message: string;
+    /** "req_…", also in the Songbrain-Request-Id header. */
+    request_id?: string;
 }
 /**
  * The song document. While processing, only `id`, `status`, `progress` and
@@ -298,6 +329,10 @@ interface Song {
     created_at?: string | null;
     external_ref?: string | null;
     billing?: Billing;
+    /** false for test-mode songs. */
+    livemode?: boolean;
+    /** Measured vs. transcribed vs. model estimate vs. generated. */
+    provenance?: Provenance;
 }
 /** The 202 body of POST /songs. */
 interface SongCreated {
@@ -308,6 +343,7 @@ interface SongCreated {
     billing: Billing;
     external_ref?: string | null;
     url: string;
+    livemode?: boolean;
 }
 /** GET /songs/{id}/shot-plan and GET /examples/{id}/shot-plan. */
 interface SongShotPlan {
@@ -323,10 +359,14 @@ interface SongListItem {
     external_ref: string | null;
     created_at: string | null;
     billing: Billing;
+    livemode?: boolean;
 }
 interface SongList {
     object: "list";
     data: SongListItem[];
+    has_more?: boolean;
+    /** Pass as `startingAfter` for the next page. */
+    next_cursor?: string | null;
 }
 interface DeleteResult {
     id: string;
@@ -383,11 +423,44 @@ interface Pricing {
 }
 /** A webhook event body. */
 interface WebhookEvent<T = Record<string, unknown>> {
-    type: "song.done" | "song.failed" | "account.low_balance" | (string & {});
+    /** "evt_…". Stays the same across retries of one event: dedupe on it. */
+    id: string;
+    type: "song.done" | "song.failed" | "account.low_balance" | "ping" | (string & {});
     /** Unix seconds. */
     created: number;
+    livemode: boolean;
     data: T;
 }
+/** From the X-RateLimit-* headers. See `Songbrain.lastRateLimit`. */
+interface RateLimitInfo {
+    /** Requests per minute. */
+    limit: number;
+    remaining: number | null;
+    /** Seconds until the window has room again. */
+    reset: number | null;
+}
+/** POST /webhooks/test. */
+interface WebhookTestResult {
+    delivered: boolean;
+    status_code: number | null;
+    latency_ms: number;
+    event_id: string;
+}
+interface WebhookDelivery {
+    event_id: string;
+    type: WebhookEvent["type"];
+    song_id: string | null;
+    url: string;
+    attempt: number;
+    status_code: number | null;
+    delivered: boolean;
+    latency_ms: number | null;
+    created_at: string;
+}
+interface WebhookDeliveryList {
+    object: "list";
+    data: WebhookDelivery[];
+}
 
 declare const DEFAULT_BASE_URL = "https://api.songbrain.ai/v1";
 /** A Blob/File, a Buffer or bytes, or a local file path (Node). */
@@ -399,7 +472,10 @@ interface SongbrainOptions {
     baseUrl?: string;
     /** Timeout for each HTTP request in ms (uploads included). Default 60 000. */
     timeoutMs?: number;
-    /** How often to retry 429 and 5xx responses, with backoff. Default 3. */
+    /**
+     * How often to retry network errors, 429 and 5xx responses, with backoff. Default 3.
+     * Song creation is retried too, because every create sends an `Idempotency-Key`.
+     */
     maxRetries?: number;
     /** A custom fetch implementation. Defaults to the global fetch. */
     fetch?: typeof fetch;
@@ -417,6 +493,25 @@ interface AnalyzeOptions {
     externalRef?: string;
     /** File name for an upload. Its extension must match the audio format. Taken from the path or File name, or guessed from the bytes. */
     filename?: string;
+    /**
+     * The song's lyrics as plain text (up to 20,000 characters), e.g. from Suno. The
+     * analysis then uses your exact words on the transcription's timing
+     * (`lyrics.source` = "provided_lyrics"); words the singer can't be heard on are
+     * left out, never guessed.
+     */
+    lyrics?: string;
+    /**
+     * Test mode: free, never charged, no audio needed. The song is done right away and
+     * returns the Sugar Rush example analysis with `livemode: false`. `song.done` is
+     * still sent to `webhookUrl`. Made for CI and integration tests.
+     */
+    test?: boolean;
+    /**
+     * Sent as `Idempotency-Key`. By default a random UUID per call, reused across the
+     * client's own retries, so a retried create never makes a second song. Pass your
+     * own (e.g. your job id) to make retries across processes safe too (24 h window).
+     */
+    idempotencyKey?: string;
     /** Wait until the song is done and return the full document (default true). */
     wait?: boolean;
     /** Time between status checks while waiting. Default 5 000. */
@@ -428,6 +523,18 @@ interface WaitOptions {
     pollIntervalMs?: number;
     timeoutMs?: number;
 }
+interface ListSongsOptions {
+    /** Page size, 1-100. Default 20. */
+    limit?: number;
+    /** A song id, usually the previous page's `next_cursor`. Returns the songs after it. */
+    startingAfter?: string;
+}
+interface IterSongsOptions {
+    /** Songs per request, 1-100. Default 100. */
+    pageSize?: number;
+    /** Start after this song id. */
+    startingAfter?: string;
+}
 interface GetSongOptions {
     /** "summary" drops word timings and beat arrays (about 3x smaller). */
     view?: "full" | "summary";
@@ -450,11 +557,19 @@ declare class Songbrain {
     readonly timeoutMs: number;
     readonly maxRetries: number;
     private readonly fetchImpl;
+    /**
+     * `{ limit, remaining, reset }` from the `X-RateLimit-*` headers of the last response
+     * that had them (null before that). `reset` is seconds until the window has room.
+     */
+    lastRateLimit: RateLimitInfo | null;
+    /** The `Songbrain-Request-Id` of the last response (null before the first one). */
+    lastRequestId: string | null;
     /** @internal Overridable in tests. */
     _sleep: (ms: number) => Promise<void>;
     constructor(options?: SongbrainOptions);
     /**
-     * Analyse a song from a file or a public URL. Pass exactly one of `file` or `audioUrl`.
+     * Analyse a song from a file or a public URL. Pass exactly one of `file` or `audioUrl`
+     * (or neither with `test: true`).
      * Typically 60-90 s. With `wait: true` (default) resolves to the full document;
      * with `wait: false` to the 202 body `{ id, status: "processing", eta_sec, billing }`.
      */
@@ -471,16 +586,31 @@ declare class Songbrain {
     getSong(songId: string, options?: GetSongOptions): Promise<Song>;
     /** Only the story and the shot plan: `{ id, status, song, story, shot_plan }`. */
     shotPlan(songId: string): Promise<SongShotPlan>;
-    /** Your songs, newest first. `limit` is 1-100 (default 20). */
-    listSongs(options?: {
-        limit?: number;
-    }): Promise<SongList>;
+    /** One page of your songs, newest first: `{ object: "list", data, has_more, next_cursor }`. */
+    listSongs(options?: ListSongsOptions): Promise<SongList>;
+    /**
+     * All your songs, newest first, fetching pages as needed.
+     *
+     * ```ts
+     * for await (const item of sb.iterSongs()) console.log(item.id, item.status);
+     * ```
+     */
+    iterSongs(options?: IterSongsOptions): AsyncGenerator<SongListItem, void, undefined>;
     /** Delete a song's audio and analysis now. 409 `still_processing` while it runs. */
     deleteSong(songId: string): Promise<DeleteResult>;
     /** Free songs left this month, credit balance and price per song. */
     account(): Promise<Account>;
     /** Prices and limits. No key needed. */
     pricing(): Promise<Pricing>;
+    /**
+     * Send a signed `ping` event to `url` right now:
+     * `{ delivered, status_code, latency_ms, event_id }`. Checks your receiver before real songs.
+     */
+    testWebhook(url: string): Promise<WebhookTestResult>;
+    /** The last webhook delivery attempts for your account, newest first. */
+    webhookDeliveries(options?: {
+        limit?: number;
+    }): Promise<WebhookDeliveryList>;
     /** Example analyses of Songbrain's own songs. No key needed. */
     examples(): Promise<ExampleList>;
     /** A full example document, in the same format as `getSong`. No key needed. */
@@ -492,9 +622,10 @@ declare class Songbrain {
 }
 
 /**
- * Every API error has the shape `{ error: { code, message } }`. The client
- * turns it into a `SongbrainError` (or a subclass) with `status`, `code` and
- * `message`.
+ * Every API error has the shape `{ error: { code, message, request_id } }`.
+ * The client turns it into a `SongbrainError` (or a subclass) with `status`,
+ * `code`, `message` and `requestId`. The message ends with
+ * ` (request_id: req_…)` when there is one; quote it when you contact support.
  */
 declare class SongbrainError extends Error {
     /** HTTP status, or 0 when the error did not come from an HTTP response. */
@@ -503,7 +634,9 @@ declare class SongbrainError extends Error {
     readonly code: string;
     /** The parsed response body, when there was one. */
     readonly body: unknown;
-    constructor(status: number, code: string, message: string, body?: unknown);
+    /** The `Songbrain-Request-Id` of the failed request (`req_…`), or null. */
+    readonly requestId: string | null;
+    constructor(status: number, code: string, message: string, body?: unknown, requestId?: string | null);
 }
 /** 401: the API key is missing, invalid or revoked. */
 declare class AuthenticationError extends SongbrainError {
@@ -518,7 +651,7 @@ declare class NotFound extends SongbrainError {
 declare class RateLimited extends SongbrainError {
     /** Seconds to wait, from the Retry-After header (null if absent). */
     readonly retryAfter: number | null;
-    constructor(status: number, code: string, message: string, body?: unknown, retryAfter?: number | null);
+    constructor(status: number, code: string, message: string, body?: unknown, retryAfter?: number | null, requestId?: string | null);
 }
 /** The song was accepted but its analysis failed. Paid credits are refunded automatically. */
 declare class AnalysisFailed extends SongbrainError {
@@ -546,13 +679,17 @@ type RawBody = string | Uint8Array | ArrayBuffer;
 declare function verifyWebhook(rawBody: RawBody, header: string | null | undefined, secret: string, toleranceSec?: number): boolean;
 /**
  * Verify the signature and return the parsed event:
- * `{ type: "song.done" | "song.failed" | "account.low_balance", created, data }`.
+ * `{ id, type: "song.done" | "song.failed" | "account.low_balance" | "ping", created, livemode, data }`.
  * Throws if the signature is not valid.
+ *
+ * `id` (`evt_…`, also the `Songbrain-Event-Id` header) stays the same when
+ * Songbrain retries an event (up to 10 attempts over about 3 days): store the
+ * ids you have handled and skip repeats.
  */
 declare function constructWebhookEvent<T = Record<string, unknown>>(rawBody: RawBody, header: string | null | undefined, secret: string, toleranceSec?: number): WebhookEvent<T>;
 /** Build a signature header value. Useful to test your webhook handler. */
 declare function signWebhook(rawBody: RawBody, secret: string, timestampSec?: number): string;
 
-declare const VERSION = "0.1.2";
+declare const VERSION = "0.3.0";
 
-export { type Account, type Act, AnalysisFailed, type AnalyzeOptions, AuthenticationError, type BestMoment, type Billing, type Clip, DEFAULT_BASE_URL, type DeleteResult, type ErrorInfo, type ExampleList, type ExampleSummary, type FileInput, type FullSong, type FullSongSection, type GetSongOptions, type Instrument, InsufficientCredits, type KeyChange, type LoudnessCheck, type LyricHook, type LyricLine, type Lyrics, NotFound, type Phases, type Pricing, RateLimited, SIGNATURE_HEADER, type Scene, type SceneKind, type ScoreBlock, type Scores, type Section, type SectionName, type ShotPlan, type ShotStyle, type Song, type SongCreated, type SongDNA, type SongInfo, type SongList, type SongListItem, type SongShotPlan, type SongStatus, Songbrain, SongbrainError, type SongbrainOptions, type SoundsLike, type Story, type StoryBeats, type StoryElement, type Timeline, VERSION, type VocalChange, type WaitOptions, WaitTimeout, type WebhookEvent, type WhatToFix, type WhatWorks, type Word, constructWebhookEvent, signWebhook, verifyWebhook };
+export { type Account, type Act, AnalysisFailed, type AnalyzeOptions, AuthenticationError, type BestMoment, type Billing, type Clip, DEFAULT_BASE_URL, type DeleteResult, type ErrorInfo, type ExampleList, type ExampleSummary, type FileInput, type FullSong, type FullSongSection, type GetSongOptions, type Instrument, InsufficientCredits, type IterSongsOptions, type KeyChange, type ListSongsOptions, type LoudnessCheck, type LyricHook, type LyricLine, type Lyrics, type LyricsAlignment, NotFound, type Phases, type Pricing, type Provenance, type RateLimitInfo, RateLimited, SIGNATURE_HEADER, type Scene, type SceneKind, type ScoreBlock, type Scores, type Section, type SectionName, type ShotPlan, type ShotStyle, type Song, type SongCreated, type SongDNA, type SongInfo, type SongList, type SongListItem, type SongShotPlan, type SongStatus, Songbrain, SongbrainError, type SongbrainOptions, type SoundsLike, type Story, type StoryBeats, type StoryElement, type Timeline, VERSION, type VocalChange, type WaitOptions, WaitTimeout, type WebhookDelivery, type WebhookDeliveryList, type WebhookEvent, type WebhookTestResult, type WhatToFix, type WhatWorks, type Word, constructWebhookEvent, signWebhook, verifyWebhook };