songbrain 0.3.3 → 0.4.0

package/dist/index.d.cts

@@ -7,6 +7,12 @@
  * otherwise (`start_in_clip`).
  */
 type SongStatus = "processing" | "done" | "failed";
+/**
+ * What a song includes. "full" (the default): Song DNA + video direction (story,
+ * shot plan), 25 credits. "dna": Song DNA only (song_dna, timeline, best_moments,
+ * lyrics, scores), 10 credits. Add the direction to a dna song later for 15 credits.
+ */
+type Mode = "full" | "dna";
 /** One of the sections a song document has. Use with `include`. */
 type SectionName = "song_dna" | "timeline" | "best_moments" | "lyrics" | "scores" | "story" | "shot_plan";
 interface Billing {
@@ -305,9 +311,22 @@ interface ErrorInfo {
     /** "req_…", also in the Songbrain-Request-Id header. */
     request_id?: string;
 }
+/** On a "dna" song: how to add the video direction (story + shot plan) later. */
+interface DirectionOffer {
+    included: false;
+    /** "POST https://api.songbrain.ai/v1/songs/{id}/direction" */
+    add: string;
+    /** 15 */
+    credits: number;
+    /** 0.3 */
+    usd: number;
+    /** ["story", "shot_plan"] */
+    adds: SectionName[];
+}
 /**
- * The song document. While processing, only `id`, `status`, `progress` and
- * `eta_sec` are set. With `include`, only the named sections are present.
+ * The song document. While processing, only `id`, `status`, `progress`,
+ * `eta_sec` and `mode` are set. With `include`, only the named sections are
+ * present. A "dna" song has no `story` and no `shot_plan`; it has `direction`.
  */
 interface Song {
     object: "song";
@@ -333,18 +352,35 @@ interface Song {
     livemode?: boolean;
     /** Measured vs. transcribed vs. model estimate vs. generated. */
     provenance?: Provenance;
+    /** "full" or "dna" (API 1.3). */
+    mode?: Mode;
+    /** Only on "dna" songs: how to add the story and shot plan. */
+    direction?: DirectionOffer;
 }
 /** The 202 body of POST /songs. */
 interface SongCreated {
     object: "song";
     id: string;
     status: "processing";
+    mode?: Mode;
     eta_sec: number;
     billing: Billing;
     external_ref?: string | null;
     url: string;
     livemode?: boolean;
 }
+/** The 202 body of POST /songs/{id}/direction. */
+interface DirectionCreated {
+    object: "song";
+    id: string;
+    /** "processing"; "done" right away for a test-mode song. */
+    status: "processing" | "done";
+    mode: "full";
+    eta_sec: number;
+    billing: Billing;
+    url: string;
+    livemode?: boolean;
+}
 /** GET /songs/{id}/shot-plan and GET /examples/{id}/shot-plan. */
 interface SongShotPlan {
     id: string;
@@ -356,6 +392,7 @@ interface SongShotPlan {
 interface SongListItem {
     id: string;
     status: string;
+    mode?: Mode;
     external_ref: string | null;
     created_at: string | null;
     billing: Billing;
@@ -391,13 +428,36 @@ interface ExampleList {
     object: "list";
     data: ExampleSummary[];
 }
+interface Price {
+    credits: number;
+    usd: number;
+}
+interface ModePrice extends Price {
+    name: string;
+    /** Section names the mode returns. */
+    includes: SectionName[];
+    default?: boolean;
+}
+interface AddDirectionPrice extends Price {
+    /** "POST /v1/songs/{id}/direction" */
+    endpoint: string;
+    note?: string;
+}
 interface Account {
     credits: number;
     free_songs_per_month: number;
     free_songs_used: number;
     free_songs_left: number;
+    /** Mode "full". */
     price_per_song_credits: number;
+    /** Mode "full". */
     price_per_song_usd: number;
+    /** Price per mode (API 1.3). */
+    prices?: {
+        full: Price;
+        dna: Price;
+        add_direction: Price;
+    };
     songs_this_month: number;
     buy_credits_url: string;
     songs_left_from_credits?: number;
@@ -410,8 +470,19 @@ interface Account {
 }
 interface Pricing {
     free_songs_per_month: number;
+    /** "either mode" */
+    free_songs_cover?: string;
+    /** Mode "full". */
     price_per_song_credits: number;
+    /** Mode "full". */
     price_per_song_usd: number;
+    /** API 1.3. */
+    modes?: {
+        full: ModePrice;
+        dna: ModePrice;
+    };
+    /** API 1.3: story + shot plan for a finished dna song. */
+    add_direction?: AddDirectionPrice;
     credit_packs: {
         credits: number;
         usd: number;
@@ -421,7 +492,12 @@ interface Pricing {
     limits: Record<string, number>;
     examples_are_free: boolean;
 }
-/** A webhook event body. */
+/**
+ * A webhook event body. For song.* events `data` has `id`, `status`, `mode`,
+ * `external_ref`, `url`, and `shot_plan_url` for "full" songs only. After
+ * `addDirection` a second `song.done` arrives with its own `id` and
+ * `data.direction_added: true`.
+ */
 interface WebhookEvent<T = Record<string, unknown>> {
     /** "evt_…". Stays the same across retries of one event: dedupe on it. */
     id: string;
@@ -500,6 +576,13 @@ interface AnalyzeOptions {
      * left out, never guessed.
      */
     lyrics?: string;
+    /**
+     * "full" (the API default, 25 credits) = Song DNA + video direction (story, shot plan).
+     * "dna" (10 credits) = Song DNA only: song_dna, timeline, best_moments, lyrics and
+     * scores, no story and no shot plan. Add the direction later with `addDirection`
+     * (15 credits). Left out, nothing is sent and the API uses "full". A free song covers either mode.
+     */
+    mode?: Mode;
     /**
      * 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
@@ -541,6 +624,14 @@ interface GetSongOptions {
     /** Only these sections, e.g. ["song_dna", "shot_plan"]. */
     include?: SectionName[] | string;
 }
+interface ExampleOptions extends GetSongOptions {
+    /** "dna" returns what a Song DNA-only song looks like: no story, no shot plan, a `direction` offer. */
+    mode?: Mode;
+}
+interface AddDirectionOptions extends WaitOptions {
+    /** Wait until the direction is there and return the full document (default true). */
+    wait?: boolean;
+}
 /**
  * Client for the Songbrain API. Every method resolves to the JSON body of
  * the response.
@@ -582,9 +673,32 @@ declare class Songbrain {
     analyze(options: AnalyzeOptions): Promise<Song | SongCreated>;
     /** Poll GET /songs/{id} until the song is done. Throws `AnalysisFailed` or `WaitTimeout`. */
     waitFor(songId: string, options?: WaitOptions): Promise<Song>;
+    /**
+     * Add the video direction (story + shot plan) to a finished `mode: "dna"` song:
+     * `POST /songs/{id}/direction`. 15 credits (never a free song), refunded automatically
+     * if it fails. No new upload. Takes about 30-40 s; the song is "processing" meanwhile,
+     * then "done" again with `mode: "full"`. Test-mode songs (`test_…`) upgrade right away, for free.
+     *
+     * With `wait: true` (default) resolves to the full document; with `wait: false` to the
+     * 202 body `{ id, status: "processing", mode: "full", eta_sec, billing }`.
+     * Throws `AnalysisFailed` (code "direction_failed", credits refunded, the song stays "dna"),
+     * `InsufficientCredits` (402), or `SongbrainError` 409 `direction_included`, `not_done`,
+     * `song_failed`, `direction_in_progress`.
+     */
+    addDirection(songId: string, options: AddDirectionOptions & {
+        wait: false;
+    }): Promise<DirectionCreated>;
+    addDirection(songId: string, options?: AddDirectionOptions & {
+        wait?: true;
+    }): Promise<Song>;
+    addDirection(songId: string, options?: AddDirectionOptions): Promise<Song | DirectionCreated>;
+    private poll;
     /** Status while processing, then the full document. */
     getSong(songId: string, options?: GetSongOptions): Promise<Song>;
-    /** Only the story and the shot plan: `{ id, status, song, story, shot_plan }`. */
+    /**
+     * Only the story and the shot plan: `{ id, status, song, story, shot_plan }`.
+     * A "dna" song has none: 409 `no_direction` (the error body's `direction` says how to add it).
+     */
     shotPlan(songId: string): Promise<SongShotPlan>;
     /** One page of your songs, newest first: `{ object: "list", data, has_more, next_cursor }`. */
     listSongs(options?: ListSongsOptions): Promise<SongList>;
@@ -598,7 +712,7 @@ declare class Songbrain {
     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. */
+    /** Free songs left this month, credit balance and prices (`prices`: full, dna, add_direction). */
     account(): Promise<Account>;
     /** Prices and limits. No key needed. */
     pricing(): Promise<Pricing>;
@@ -613,8 +727,11 @@ declare class Songbrain {
     }): 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. */
-    example(exampleId: string, options?: GetSongOptions): Promise<Song>;
+    /**
+     * A full example document, in the same format as `getSong`. No key needed.
+     * `mode: "dna"` returns the Song DNA view (no story, no shot plan).
+     */
+    example(exampleId: string, options?: ExampleOptions): Promise<Song>;
     /** An example story and shot plan, in the same format as `shotPlan`. No key needed. */
     exampleShotPlan(exampleId: string): Promise<SongShotPlan>;
     private backoffMs;
@@ -690,6 +807,6 @@ declare function constructWebhookEvent<T = Record<string, unknown>>(rawBody: Raw
 /** 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.3.3";
+declare const VERSION = "0.4.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 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 };
+export { type Account, type Act, type AddDirectionOptions, type AddDirectionPrice, AnalysisFailed, type AnalyzeOptions, AuthenticationError, type BestMoment, type Billing, type Clip, DEFAULT_BASE_URL, type DeleteResult, type DirectionCreated, type DirectionOffer, type ErrorInfo, type ExampleList, type ExampleOptions, 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, type Mode, type ModePrice, NotFound, type Phases, type Price, 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

@@ -7,6 +7,12 @@
  * otherwise (`start_in_clip`).
  */
 type SongStatus = "processing" | "done" | "failed";
+/**
+ * What a song includes. "full" (the default): Song DNA + video direction (story,
+ * shot plan), 25 credits. "dna": Song DNA only (song_dna, timeline, best_moments,
+ * lyrics, scores), 10 credits. Add the direction to a dna song later for 15 credits.
+ */
+type Mode = "full" | "dna";
 /** One of the sections a song document has. Use with `include`. */
 type SectionName = "song_dna" | "timeline" | "best_moments" | "lyrics" | "scores" | "story" | "shot_plan";
 interface Billing {
@@ -305,9 +311,22 @@ interface ErrorInfo {
     /** "req_…", also in the Songbrain-Request-Id header. */
     request_id?: string;
 }
+/** On a "dna" song: how to add the video direction (story + shot plan) later. */
+interface DirectionOffer {
+    included: false;
+    /** "POST https://api.songbrain.ai/v1/songs/{id}/direction" */
+    add: string;
+    /** 15 */
+    credits: number;
+    /** 0.3 */
+    usd: number;
+    /** ["story", "shot_plan"] */
+    adds: SectionName[];
+}
 /**
- * The song document. While processing, only `id`, `status`, `progress` and
- * `eta_sec` are set. With `include`, only the named sections are present.
+ * The song document. While processing, only `id`, `status`, `progress`,
+ * `eta_sec` and `mode` are set. With `include`, only the named sections are
+ * present. A "dna" song has no `story` and no `shot_plan`; it has `direction`.
  */
 interface Song {
     object: "song";
@@ -333,18 +352,35 @@ interface Song {
     livemode?: boolean;
     /** Measured vs. transcribed vs. model estimate vs. generated. */
     provenance?: Provenance;
+    /** "full" or "dna" (API 1.3). */
+    mode?: Mode;
+    /** Only on "dna" songs: how to add the story and shot plan. */
+    direction?: DirectionOffer;
 }
 /** The 202 body of POST /songs. */
 interface SongCreated {
     object: "song";
     id: string;
     status: "processing";
+    mode?: Mode;
     eta_sec: number;
     billing: Billing;
     external_ref?: string | null;
     url: string;
     livemode?: boolean;
 }
+/** The 202 body of POST /songs/{id}/direction. */
+interface DirectionCreated {
+    object: "song";
+    id: string;
+    /** "processing"; "done" right away for a test-mode song. */
+    status: "processing" | "done";
+    mode: "full";
+    eta_sec: number;
+    billing: Billing;
+    url: string;
+    livemode?: boolean;
+}
 /** GET /songs/{id}/shot-plan and GET /examples/{id}/shot-plan. */
 interface SongShotPlan {
     id: string;
@@ -356,6 +392,7 @@ interface SongShotPlan {
 interface SongListItem {
     id: string;
     status: string;
+    mode?: Mode;
     external_ref: string | null;
     created_at: string | null;
     billing: Billing;
@@ -391,13 +428,36 @@ interface ExampleList {
     object: "list";
     data: ExampleSummary[];
 }
+interface Price {
+    credits: number;
+    usd: number;
+}
+interface ModePrice extends Price {
+    name: string;
+    /** Section names the mode returns. */
+    includes: SectionName[];
+    default?: boolean;
+}
+interface AddDirectionPrice extends Price {
+    /** "POST /v1/songs/{id}/direction" */
+    endpoint: string;
+    note?: string;
+}
 interface Account {
     credits: number;
     free_songs_per_month: number;
     free_songs_used: number;
     free_songs_left: number;
+    /** Mode "full". */
     price_per_song_credits: number;
+    /** Mode "full". */
     price_per_song_usd: number;
+    /** Price per mode (API 1.3). */
+    prices?: {
+        full: Price;
+        dna: Price;
+        add_direction: Price;
+    };
     songs_this_month: number;
     buy_credits_url: string;
     songs_left_from_credits?: number;
@@ -410,8 +470,19 @@ interface Account {
 }
 interface Pricing {
     free_songs_per_month: number;
+    /** "either mode" */
+    free_songs_cover?: string;
+    /** Mode "full". */
     price_per_song_credits: number;
+    /** Mode "full". */
     price_per_song_usd: number;
+    /** API 1.3. */
+    modes?: {
+        full: ModePrice;
+        dna: ModePrice;
+    };
+    /** API 1.3: story + shot plan for a finished dna song. */
+    add_direction?: AddDirectionPrice;
     credit_packs: {
         credits: number;
         usd: number;
@@ -421,7 +492,12 @@ interface Pricing {
     limits: Record<string, number>;
     examples_are_free: boolean;
 }
-/** A webhook event body. */
+/**
+ * A webhook event body. For song.* events `data` has `id`, `status`, `mode`,
+ * `external_ref`, `url`, and `shot_plan_url` for "full" songs only. After
+ * `addDirection` a second `song.done` arrives with its own `id` and
+ * `data.direction_added: true`.
+ */
 interface WebhookEvent<T = Record<string, unknown>> {
     /** "evt_…". Stays the same across retries of one event: dedupe on it. */
     id: string;
@@ -500,6 +576,13 @@ interface AnalyzeOptions {
      * left out, never guessed.
      */
     lyrics?: string;
+    /**
+     * "full" (the API default, 25 credits) = Song DNA + video direction (story, shot plan).
+     * "dna" (10 credits) = Song DNA only: song_dna, timeline, best_moments, lyrics and
+     * scores, no story and no shot plan. Add the direction later with `addDirection`
+     * (15 credits). Left out, nothing is sent and the API uses "full". A free song covers either mode.
+     */
+    mode?: Mode;
     /**
      * 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
@@ -541,6 +624,14 @@ interface GetSongOptions {
     /** Only these sections, e.g. ["song_dna", "shot_plan"]. */
     include?: SectionName[] | string;
 }
+interface ExampleOptions extends GetSongOptions {
+    /** "dna" returns what a Song DNA-only song looks like: no story, no shot plan, a `direction` offer. */
+    mode?: Mode;
+}
+interface AddDirectionOptions extends WaitOptions {
+    /** Wait until the direction is there and return the full document (default true). */
+    wait?: boolean;
+}
 /**
  * Client for the Songbrain API. Every method resolves to the JSON body of
  * the response.
@@ -582,9 +673,32 @@ declare class Songbrain {
     analyze(options: AnalyzeOptions): Promise<Song | SongCreated>;
     /** Poll GET /songs/{id} until the song is done. Throws `AnalysisFailed` or `WaitTimeout`. */
     waitFor(songId: string, options?: WaitOptions): Promise<Song>;
+    /**
+     * Add the video direction (story + shot plan) to a finished `mode: "dna"` song:
+     * `POST /songs/{id}/direction`. 15 credits (never a free song), refunded automatically
+     * if it fails. No new upload. Takes about 30-40 s; the song is "processing" meanwhile,
+     * then "done" again with `mode: "full"`. Test-mode songs (`test_…`) upgrade right away, for free.
+     *
+     * With `wait: true` (default) resolves to the full document; with `wait: false` to the
+     * 202 body `{ id, status: "processing", mode: "full", eta_sec, billing }`.
+     * Throws `AnalysisFailed` (code "direction_failed", credits refunded, the song stays "dna"),
+     * `InsufficientCredits` (402), or `SongbrainError` 409 `direction_included`, `not_done`,
+     * `song_failed`, `direction_in_progress`.
+     */
+    addDirection(songId: string, options: AddDirectionOptions & {
+        wait: false;
+    }): Promise<DirectionCreated>;
+    addDirection(songId: string, options?: AddDirectionOptions & {
+        wait?: true;
+    }): Promise<Song>;
+    addDirection(songId: string, options?: AddDirectionOptions): Promise<Song | DirectionCreated>;
+    private poll;
     /** Status while processing, then the full document. */
     getSong(songId: string, options?: GetSongOptions): Promise<Song>;
-    /** Only the story and the shot plan: `{ id, status, song, story, shot_plan }`. */
+    /**
+     * Only the story and the shot plan: `{ id, status, song, story, shot_plan }`.
+     * A "dna" song has none: 409 `no_direction` (the error body's `direction` says how to add it).
+     */
     shotPlan(songId: string): Promise<SongShotPlan>;
     /** One page of your songs, newest first: `{ object: "list", data, has_more, next_cursor }`. */
     listSongs(options?: ListSongsOptions): Promise<SongList>;
@@ -598,7 +712,7 @@ declare class Songbrain {
     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. */
+    /** Free songs left this month, credit balance and prices (`prices`: full, dna, add_direction). */
     account(): Promise<Account>;
     /** Prices and limits. No key needed. */
     pricing(): Promise<Pricing>;
@@ -613,8 +727,11 @@ declare class Songbrain {
     }): 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. */
-    example(exampleId: string, options?: GetSongOptions): Promise<Song>;
+    /**
+     * A full example document, in the same format as `getSong`. No key needed.
+     * `mode: "dna"` returns the Song DNA view (no story, no shot plan).
+     */
+    example(exampleId: string, options?: ExampleOptions): Promise<Song>;
     /** An example story and shot plan, in the same format as `shotPlan`. No key needed. */
     exampleShotPlan(exampleId: string): Promise<SongShotPlan>;
     private backoffMs;
@@ -690,6 +807,6 @@ declare function constructWebhookEvent<T = Record<string, unknown>>(rawBody: Raw
 /** 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.3.3";
+declare const VERSION = "0.4.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 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 };
+export { type Account, type Act, type AddDirectionOptions, type AddDirectionPrice, AnalysisFailed, type AnalyzeOptions, AuthenticationError, type BestMoment, type Billing, type Clip, DEFAULT_BASE_URL, type DeleteResult, type DirectionCreated, type DirectionOffer, type ErrorInfo, type ExampleList, type ExampleOptions, 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, type Mode, type ModePrice, NotFound, type Phases, type Price, 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.js

@@ -54,7 +54,7 @@ var WaitTimeout = class extends SongbrainError {
 };
 
 // src/version.ts
-var VERSION = "0.3.3";
+var VERSION = "0.4.0";
 
 // src/agent.ts
 var FLAGS = [
@@ -199,6 +199,7 @@ var Songbrain = class {
     if (options.webhookUrl !== void 0) fields.webhook_url = options.webhookUrl;
     if (options.externalRef !== void 0) fields.external_ref = options.externalRef;
     if (options.lyrics !== void 0) fields.lyrics = options.lyrics;
+    if (options.mode !== void 0) fields.mode = options.mode;
     const headers = { [IDEMPOTENCY_HEADER]: options.idempotencyKey || await newIdempotencyKey() };
     let created;
     if (file === void 0) {
@@ -225,12 +226,28 @@ var Songbrain = class {
     });
   }
   /** Poll GET /songs/{id} until the song is done. Throws `AnalysisFailed` or `WaitTimeout`. */
-  async waitFor(songId, options = {}) {
+  waitFor(songId, options = {}) {
+    return this.poll(songId, options, false);
+  }
+  async addDirection(songId, options = {}) {
+    const created = await this.request("POST", `/songs/${encodeURIComponent(songId)}/direction`);
+    if (options.wait === false) return created;
+    return this.poll(songId, options, true);
+  }
+  async poll(songId, options, direction) {
     const timeoutMs = options.timeoutMs ?? 3e5;
     const interval = Math.max(500, options.pollIntervalMs ?? 5e3);
     const deadline = Date.now() + timeoutMs;
     for (; ; ) {
       const doc = await this.getSong(songId);
+      if (doc.status === "done" && direction && doc.mode === "dna") {
+        throw new AnalysisFailed(
+          songId,
+          "direction_failed",
+          "The video direction could not be added. The 15 credits were refunded automatically; the Song DNA is unchanged.",
+          doc
+        );
+      }
       if (doc.status === "done") return doc;
       if (doc.status === "failed") {
         throw new AnalysisFailed(
@@ -249,7 +266,10 @@ var Songbrain = class {
   getSong(songId, options = {}) {
     return this.request("GET", `/songs/${encodeURIComponent(songId)}`, { query: docQuery(options) });
   }
-  /** Only the story and the shot plan: `{ id, status, song, story, shot_plan }`. */
+  /**
+   * Only the story and the shot plan: `{ id, status, song, story, shot_plan }`.
+   * A "dna" song has none: 409 `no_direction` (the error body's `direction` says how to add it).
+   */
   shotPlan(songId) {
     return this.request("GET", `/songs/${encodeURIComponent(songId)}/shot-plan`);
   }
@@ -281,7 +301,7 @@ var Songbrain = class {
     return this.request("DELETE", `/songs/${encodeURIComponent(songId)}`);
   }
   // ── account ──────────────────────────────────────────────────────────────
-  /** Free songs left this month, credit balance and price per song. */
+  /** Free songs left this month, credit balance and prices (`prices`: full, dna, add_direction). */
   account() {
     return this.request("GET", "/account");
   }
@@ -308,9 +328,14 @@ var Songbrain = class {
   examples() {
     return this.request("GET", "/examples");
   }
-  /** A full example document, in the same format as `getSong`. No key needed. */
+  /**
+   * A full example document, in the same format as `getSong`. No key needed.
+   * `mode: "dna"` returns the Song DNA view (no story, no shot plan).
+   */
   example(exampleId, options = {}) {
-    return this.request("GET", `/examples/${encodeURIComponent(exampleId)}`, { query: docQuery(options) });
+    return this.request("GET", `/examples/${encodeURIComponent(exampleId)}`, {
+      query: { ...docQuery(options), mode: options.mode }
+    });
   }
   /** An example story and shot plan, in the same format as `shotPlan`. No key needed. */
   exampleShotPlan(exampleId) {