@omelhorsite/sdk 0.13.0 → 0.16.0

package/dist/types/resources/cron.d.ts

@@ -0,0 +1,209 @@
+/**
+ * The `cron` namespace: TypeScript scripts of the signed-in person that the
+ * server runs on a schedule.
+ *
+ * A script is an ES module exporting `run(ctx)`. It runs with nothing but the
+ * API: no filesystem, no environment, no processes, and no network beyond
+ * this SDK (`ctx.oms`, authenticated as the owner with the job's scopes) and,
+ * when the job has `network` on, a `ctx.fetch` that goes through the server's
+ * guard against private addresses. What it keeps in `ctx.state` is stored
+ * when a run ends well and handed back on the next one; what it returns is
+ * the run's `result`, and `result.summary` is what the listing shows.
+ *
+ * Needs the `cron:read` scope to read and `cron:write` to change anything.
+ * A job's own token never carries either: a script cannot edit jobs.
+ */
+import { Resource, type ApiClient } from "../http";
+import type { ListParams } from "../listing";
+import type { Id, Json, Paginated, RequestOptions, Timestamp } from "../types";
+/** Scopes a job may ask for its token. Anything else answers `400`. */
+export declare const CRON_JOB_SCOPES: readonly ["profile", "news:read", "news:write", "storage:read", "storage:write", "llm", "tools:read", "tools:write", "blogs:read", "blogs:write"];
+export type CronJobScope = (typeof CRON_JOB_SCOPES)[number];
+export declare const CRON_JOB_HEALTHS: readonly ["unknown", "ok", "error"];
+export type CronJobHealth = (typeof CRON_JOB_HEALTHS)[number];
+/** Consecutive failures after which a job switches itself off. Turn `enabled` back on to revive it. */
+export declare const CRON_JOB_DISABLE_AFTER_FAILURES = 10;
+/** Code longer than this answers `400`. */
+export declare const CRON_JOB_MAX_CODE_BYTES: number;
+/** `state` and `config` ceilings. A run whose state grows past this fails and the state is not stored. */
+export declare const CRON_JOB_MAX_STATE_BYTES: number;
+export declare const CRON_JOB_MAX_CONFIG_BYTES: number;
+/** Two runs of one job must be at least this far apart. */
+export declare const CRON_JOB_MIN_INTERVAL_MINUTES = 5;
+/** `timeout_seconds` range; above 120 the account needs a trusted tier, like `network`. */
+export declare const CRON_JOB_MIN_TIMEOUT_SECONDS = 5;
+export declare const CRON_JOB_MAX_TIMEOUT_SECONDS = 1200;
+export declare const CRON_JOB_BASE_MAX_TIMEOUT_SECONDS = 120;
+export interface CronJob {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    /** Up to 120 characters, unique per account. */
+    readonly name: string;
+    readonly description: string | null;
+    /** Five-field cron expression, read in `timezone`. */
+    readonly schedule: string;
+    /** An IANA zone such as `"Europe/Lisbon"` (the default). */
+    readonly timezone: string;
+    /** The scopes the run's token carries. */
+    readonly scopes: CronJobScope[];
+    /** Names of the stored secrets. The values never leave the server. */
+    readonly secret_keys: string[];
+    /** Whether `ctx.fetch` exists in the script. */
+    readonly network: boolean;
+    readonly timeout_seconds: number;
+    /** A folder of the owner's storage handed to the script as `ctx.job.outputDirId`. */
+    readonly output_dir_id: Id | null;
+    readonly enabled: boolean;
+    readonly next_run_at: Timestamp | null;
+    readonly last_run_at: Timestamp | null;
+    readonly last_success_at: Timestamp | null;
+    readonly health: CronJobHealth;
+    readonly consecutive_failures: number;
+    readonly notify_on_failure: boolean;
+    readonly notify_on_success: boolean;
+    /** The template the job was created from, if any. */
+    readonly template_slug: string | null;
+    /** Whether a run is queued or running right now. */
+    readonly running: boolean;
+}
+/** `GET /cron_jobs/:id` (and every write) adds the code, the config and the state. */
+export interface CronJobDetail extends CronJob {
+    readonly code: string;
+    readonly config: Record<string, Json>;
+    readonly state: Record<string, Json>;
+}
+export declare const CRON_JOB_FILTER_COLUMNS: readonly ["name", "enabled", "health", "template_slug"];
+export interface ListCronJobsParams extends ListParams<(typeof CRON_JOB_FILTER_COLUMNS)[number]> {
+}
+export interface CreateCronJobInput {
+    readonly name: string;
+    readonly description?: string | null;
+    /** Five fields. Two runs must be at least {@link CRON_JOB_MIN_INTERVAL_MINUTES} apart. */
+    readonly schedule: string;
+    readonly timezone?: string;
+    /** TypeScript. Checked for syntax on the server before it is stored. */
+    readonly code: string;
+    /** Defaults to every scope but `news:write` and `tools:write`. */
+    readonly scopes?: readonly CronJobScope[];
+    readonly config?: Record<string, Json>;
+    /** Stored encrypted; on update the object is MERGED, and a `null` value removes that key. */
+    readonly secrets?: Record<string, string | null>;
+    readonly state?: Record<string, Json>;
+    readonly network?: boolean;
+    readonly timeoutSeconds?: number;
+    readonly outputDirId?: Id | null;
+    readonly enabled?: boolean;
+    readonly notifyOnFailure?: boolean;
+    readonly notifyOnSuccess?: boolean;
+    readonly templateSlug?: string | null;
+}
+export type UpdateCronJobInput = Partial<Omit<CreateCronJobInput, "templateSlug">>;
+export declare const CRON_RUN_STATUSES: readonly ["queued", "running", "ok", "error", "timeout", "skipped"];
+export type CronRunStatus = (typeof CRON_RUN_STATUSES)[number];
+export declare const CRON_RUN_TRIGGERS: readonly ["schedule", "manual", "test"];
+export type CronRunTrigger = (typeof CRON_RUN_TRIGGERS)[number];
+export interface CronRun {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly cron_job_id: Id;
+    readonly status: CronRunStatus;
+    /** `test` runs never write the state back and never count as failures. */
+    readonly trigger: CronRunTrigger;
+    readonly scheduled_at: Timestamp;
+    readonly started_at: Timestamp | null;
+    readonly finished_at: Timestamp | null;
+    readonly duration_ms: number | null;
+    readonly error: string | null;
+    readonly error_name: string | null;
+    /** Model calls made with the run's token, and what they cost. */
+    readonly llm_requests: number;
+    readonly llm_cost: number;
+    /** Requests the script made, through the SDK and `ctx.fetch`. */
+    readonly http_calls: number;
+    /** `result.summary`, when the script returned one. */
+    readonly summary: string | null;
+}
+/** `GET /cron_runs/:id` adds the logs and the whole result. */
+export interface CronRunDetail extends CronRun {
+    /** What `ctx.log` and `console.log` wrote, one line per entry, capped at 64 KB. */
+    readonly logs: string | null;
+    readonly result: Json | null;
+}
+export declare const CRON_RUN_FILTER_COLUMNS: readonly ["cron_job_id", "status", "trigger"];
+export interface ListCronRunsParams extends ListParams<(typeof CRON_RUN_FILTER_COLUMNS)[number]> {
+    readonly jobId?: Id;
+    readonly status?: CronRunStatus;
+}
+/** A ready-made script: copy it into a job with {@link CronJobsNamespace.create}. */
+export interface CronTemplate {
+    readonly slug: string;
+    readonly name: string;
+    readonly description: string;
+    /** The schedule the template expects. */
+    readonly schedule: string;
+    readonly scopes: CronJobScope[];
+    readonly network: boolean;
+    /** The config the script reads, with defaults. */
+    readonly config: Record<string, Json>;
+    /** SHA-256 of the code, so a client can tell an edited copy from a pristine one. */
+    readonly hash: string;
+}
+export interface CronTemplateDetail extends CronTemplate {
+    readonly code: string;
+}
+/** What the syntax check answers. */
+export interface CronCheckResult {
+    readonly ok: boolean;
+    readonly error?: string;
+}
+export declare class CronJobsNamespace extends Resource {
+    list(params?: ListCronJobsParams, options?: RequestOptions): Promise<Paginated<CronJob>>;
+    get(id: Id, options?: RequestOptions): Promise<CronJobDetail>;
+    /**
+     * `POST /cron_jobs`. `201` with the full job.
+     *
+     * @throws {OmsApiError} 400 with the validation sentence: a bad or too
+     *   frequent schedule, an unknown timezone, a scope outside
+     *   {@link CRON_JOB_SCOPES}, `network` or a timeout above 120 s on an
+     *   account without a trusted tier, an `Invalid script: ...` syntax error,
+     *   or `job limit reached (N)` (the `cron_jobs` quota).
+     */
+    create(input: CreateCronJobInput, options?: RequestOptions): Promise<CronJobDetail>;
+    /** `PATCH /cron_jobs/:id`. Secrets merge; a `null` value removes a key. Changing the schedule recomputes `next_run_at`. */
+    update(id: Id, input: UpdateCronJobInput, options?: RequestOptions): Promise<CronJobDetail>;
+    /** `DELETE /cron_jobs/:id` - the job and its runs. `204`. */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+    /**
+     * `POST /cron_jobs/:id/run` - runs now, outside the schedule, as a normal
+     * run (the state is stored). `202` with the queued run.
+     *
+     * @throws {OmsApiError} 400 `this job is already running`; 429
+     *   `error: "limit"` when the day's `cron_run_seconds` are spent.
+     */
+    run(id: Id, options?: RequestOptions): Promise<CronRun>;
+    /** `POST /cron_jobs/:id/test` - runs now WITHOUT storing the state or counting a failure. `202`. */
+    test(id: Id, options?: RequestOptions): Promise<CronRun>;
+    /** `POST /cron_jobs/check` - the syntax check the server runs before storing code, on its own. */
+    check(code: string, options?: RequestOptions): Promise<CronCheckResult>;
+}
+export declare class CronRunsNamespace extends Resource {
+    /** `GET /cron_runs` - newest first. */
+    list(params?: ListCronRunsParams, options?: RequestOptions): Promise<Paginated<CronRun>>;
+    get(id: Id, options?: RequestOptions): Promise<CronRunDetail>;
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+}
+export declare class CronTemplatesNamespace extends Resource {
+    /** `GET /cron_templates` - the built-in scripts, without their code. */
+    list(options?: RequestOptions): Promise<CronTemplate[]>;
+    /** `GET /cron_templates/:slug` - one template with its code. */
+    get(slug: string, options?: RequestOptions): Promise<CronTemplateDetail>;
+}
+/** The `cron` namespace, reachable as `oms.cron`. */
+export declare class CronNamespace extends Resource {
+    readonly jobs: CronJobsNamespace;
+    readonly runs: CronRunsNamespace;
+    readonly templates: CronTemplatesNamespace;
+    constructor(http: ApiClient);
+}

package/dist/types/resources/index.d.ts

@@ -22,6 +22,7 @@ export * from "./admin";
 export * from "./auth/index";
 export * from "./chests";
 export * from "./content";
+export * from "./cron";
 export * from "./dynamicQrs";
 export * from "./forms";
 export * from "./ipLookup";

package/dist/types/resources/llm.d.ts

@@ -41,6 +41,8 @@ export interface LlmModelChoice {
     readonly name: string;
     readonly provider_slug: string;
     readonly free: boolean;
+    /** `0` everyone, `1` trusted accounts, `2` administrators. Only models at or below the account's tier are listed. */
+    readonly tier: number;
     readonly context_window: number | null;
     readonly max_output_tokens: number | null;
     readonly input_price_per_million: number | null;
@@ -285,12 +287,81 @@ export declare class LlmChatsNamespace extends Resource {
     /** Removes the chat and every message in it. */
     delete(id: Id, options?: RequestOptions): Promise<void>;
 }
+/** The tools a completion may hand the model. Each call the model makes counts as one search or one page read. */
+export declare const LLM_COMPLETION_TOOLS: readonly ["web_search", "read_url"];
+export type LlmCompletionTool = (typeof LLM_COMPLETION_TOOLS)[number];
+/** At most this many messages in one completion. */
+export declare const LLM_COMPLETION_MAX_MESSAGES = 200;
+/** Longer contents answer `400`. */
+export declare const LLM_COMPLETION_MAX_MESSAGE_CHARS = 100000;
+/** All contents together. */
+export declare const LLM_COMPLETION_MAX_TOTAL_CHARS = 400000;
+/** `maxTokens` above this answers `400`. */
+export declare const LLM_COMPLETION_MAX_OUTPUT_TOKENS = 16000;
+/** How many tool calls one completion may make before the model is told to answer with what it has. */
+export declare const LLM_COMPLETION_MAX_TOOL_CALLS = 6;
+export type LlmCompletionRole = "system" | "user" | "assistant";
+export interface LlmCompletionMessage {
+    readonly role: LlmCompletionRole;
+    /** Plain text. Images and audio are not accepted here. */
+    readonly content: string;
+}
+export interface LlmCompletionInput {
+    /** In order. At least one `user` or `assistant` turn; `system` turns alone are a `400`. */
+    readonly messages: readonly LlmCompletionMessage[];
+    /**
+     * A model the caller may choose (an `id` or a `model_id` from {@link LlmNamespace.models}).
+     * Omitted, the server's own choice for API completions answers, with its fallbacks.
+     */
+    readonly model?: string;
+    /** Ask for a JSON object. A request, not a guarantee: parse defensively. */
+    readonly json?: boolean;
+    /** `0` to `2`. */
+    readonly temperature?: number;
+    /** `1` to {@link LLM_COMPLETION_MAX_OUTPUT_TOKENS}. */
+    readonly maxTokens?: number;
+    /** Tools the model may use while answering. Their calls come back in {@link LlmCompletion.tool_calls}. */
+    readonly tools?: readonly LlmCompletionTool[];
+    /** Language of the web searches the model runs (`"pt-PT"`, `"en"`); defaults to Portuguese. */
+    readonly language?: string;
+}
+/** One finished completion. Tokens and cost are `null` when the provider did not report them. */
+export interface LlmCompletion {
+    readonly text: string;
+    /** The provider's identifier of the model that answered (a fallback may differ from the one asked for). */
+    readonly model_id: string | null;
+    readonly input_tokens: number | null;
+    readonly output_tokens: number | null;
+    /** In the provider's currency (USD for the hosted ones). */
+    readonly cost: number | null;
+    /** What the model did with its tools, in order. Empty without `tools`. */
+    readonly tool_calls: readonly LlmToolCall[];
+    /** From the request to the answer, in milliseconds. */
+    readonly duration_ms: number;
+}
 export declare class LlmNamespace extends Resource {
     /** Conversations with the assistant. */
     readonly chats: LlmChatsNamespace;
     constructor(http: ApiClient);
     /** The models the caller may choose, with today's remaining allowance on each. */
     models(options?: RequestOptions): Promise<LlmModelChoice[]>;
+    /**
+     * `POST /llm/completions` - one answer to a list of messages, with nothing
+     * remembered between calls. For programs; people talk to the assistant
+     * through {@link chats}.
+     *
+     * Every completion counts on the account's daily ceilings (`llm_requests`
+     * and `llm_cost_microusd` in `oms.quotas.list()`) and on the chosen model's
+     * own daily limits. Needs the `llm` scope on an OAuth token.
+     *
+     * @throws {OmsApiError} 400 for malformed messages, an unknown model
+     *   (`error: "unknown_model"`) or an unknown tool; 403 `error: "model_not_allowed"`
+     *   for a model above the account's tier; 429 `error: "limit"` when a
+     *   daily ceiling is reached, or above 30 completions a minute; 502
+     *   `error: "unavailable"` when no model answered; 503 `error: "busy"`
+     *   when the provider has no free slot, worth a retry in a moment.
+     */
+    complete(input: LlmCompletionInput, options?: RequestOptions): Promise<LlmCompletion>;
     /** The caller's own usage. */
     usage(input?: LlmUsageQuery, options?: RequestOptions): Promise<LlmUsageSummary>;
 }

package/dist/types/resources/music/social.d.ts

@@ -501,57 +501,99 @@ export interface SendMusicAssistantMessageInput {
     readonly player?: MusicAssistantPlayerContext;
 }
 /**
- * Generations per user per hour, shared by `/music_dj` and `/music_dj/batch`.
+ * Turns per user per hour on `POST /music_dj/next`.
  *
- * The counter is incremented by EVERY request - including the ones it then
- * refuses with `429`. A retry loop therefore drives the count further past the
- * cap and can never recover inside the hour, which is why
- * {@link MusicDjNamespace} passes `retry: false` unless you override it.
+ * A turn is one song, so an hour of listening spends about 17 of them and the
+ * rest of the budget absorbs skipping. The counter is incremented by EVERY
+ * request - including the ones it then refuses with `429` - so a retry loop
+ * drives the count further past the cap and can never recover inside the hour,
+ * which is why {@link MusicDjNamespace} passes `retry: false` unless you
+ * override it.
  */
-export declare const MUSIC_DJ_HOURLY_CAP = 40;
+export declare const MUSIC_DJ_HOURLY_CAP = 90;
 /**
- * Default deadline for one DJ generation, in milliseconds. Writing the script
- * and speaking it takes well past the client's 60 s default.
+ * Default deadline for one DJ turn, in milliseconds. Choosing the song and
+ * speaking it takes well past the client's 60 s default.
  */
 export declare const MUSIC_DJ_TIMEOUT_MS = 120000;
-/** Songs one `/music_dj/batch` set plans at most. */
-export declare const MUSIC_DJ_BATCH_SIZE = 4;
-/** `POST /music_dj`: one spoken link between two tracks. */
-export interface MusicDjInterstitial {
-    /** The script as text, at most 320 characters. Worth showing while audio loads. */
-    readonly text: string;
+/** One entry in a DJ session's transcript. */
+export interface MusicDjTurn {
+    /** `"dj"` when he played or spoke, `"listener"` when they asked for something. */
+    readonly role: "dj" | "listener";
     /**
-     * The same script spoken, base64, NOT a data URL. Decode with
-     * {@link musicDjAudioBytes} or wrap with {@link musicDjAudioDataUrl}.
+     * What was said. `null` on a DJ turn where he stayed quiet - he speaks on
+     * the first song, whenever the listener asks for something, and every third
+     * song after that, so most turns carry a song and no words.
      */
-    readonly audio_base64: string;
-    /** Container of the decoded bytes. `"wav"` today, and typed wide on purpose. */
-    readonly format: string;
+    readonly text: string | null;
+    /** The song that turn played, when it played one. */
+    readonly song_id: number | null;
+    readonly created_at: Timestamp;
 }
-/** `POST /music_dj/batch`: a whole set - what to play next, and the words for it. */
-export interface MusicDjBatch extends MusicDjInterstitial {
+/** `GET /music_dj/session`: the session still on air, if there is one. */
+export interface MusicDjSession {
+    readonly id: number;
+    /** The listener's standing request. It holds until they ask for something else. */
+    readonly request: string | null;
+    readonly turns: MusicDjTurn[];
     /**
-     * The planned tracks, in play order, in the full `GET /songs` shape and
-     * already scoped to what the caller may play. Between 1 and
-     * {@link MUSIC_DJ_BATCH_SIZE}: the server fails rather than answer with an
-     * empty set, so this is never `[]`.
+     * Every song the transcript refers to, in the full `GET /songs` shape, so a
+     * client can rebuild the session without a lookup per turn. Unordered: match
+     * them to {@link MusicDjTurn.song_id}.
      */
     readonly songs: Song[];
 }
-/** Everything `POST /music_dj/batch` accepts. All of it optional. */
-export interface MusicDjBatchInput {
-    /** A free-text steer ("something calmer"). Truncated to 300 characters. */
+/** `POST /music_dj/next`: the next song, and the words for it when there are any. */
+export interface MusicDjNext {
+    readonly session_id: number;
+    /** What to play now. Never one the session already played. */
+    readonly song: Song;
+    /** Two to five words naming this stretch of the show, for a screen. */
+    readonly theme: string | null;
+    /**
+     * The spoken link, present ONLY on the turns where he speaks. Its absence is
+     * the normal case, not an error: play the song straight away.
+     */
+    readonly text?: string;
+    /**
+     * The same words spoken, base64, NOT a data URL. Decode with
+     * {@link musicDjAudioBytes} or wrap with {@link musicDjAudioDataUrl}.
+     *
+     * Absent when he stayed quiet AND when the voice service failed while he had
+     * something to say - in that second case `text` is there without it, and the
+     * song still plays. Never block playback on this field.
+     */
+    readonly audio_base64?: string;
+    /** Container of the decoded bytes. `"wav"` today, and typed wide on purpose. */
+    readonly format?: string;
+}
+/** Everything `POST /music_dj/next` accepts. All of it optional. */
+export interface MusicDjNextInput {
+    /**
+     * Continue this session. Omit to continue the caller's own session, which
+     * the server finds by itself - a session goes stale after two hours of
+     * silence and the next turn starts a fresh one.
+     */
+    readonly sessionId?: number;
+    /**
+     * A steer ("something calmer", "fados"), truncated to 300 characters.
+     *
+     * STANDING ORDERS, not a one-off: it holds for every following turn until
+     * another request replaces it, and it makes him speak on this turn even if
+     * it was not his turn to.
+     */
     readonly request?: string;
+    /** The song the listener just skipped, as a direction to leave. */
+    readonly skippedSongId?: SongId;
     /**
-     * Recently played ids. Only the last 60 are read, and the planner SUBTRACTS
-     * them from its own picks - so a list that covers the whole library leaves
-     * nothing playable and the call fails with a `502`.
+     * Make him speak on this turn even if it was not his turn to.
+     *
+     * This is the DJ button: the listener wants to hear him now. It changes
+     * nothing about which song comes next.
      */
-    readonly recentSongIds?: SongId[];
-    /** Ids the listener skipped, as negative signal. Only the last 20 are read. */
-    readonly skippedSongIds?: SongId[];
-    /** Which set of the session this is, so the script can vary its opening. */
-    readonly batchIndex?: number;
+    readonly speak?: boolean;
+    /** Start a new session even though one is still on air. */
+    readonly restart?: boolean;
 }
 /**
  * Jams over HTTP. The realtime half lives on the WebSocket stream and is not in
@@ -887,12 +929,16 @@ export declare class MusicAssistantNamespace extends Resource {
     ask(messages: MusicAssistantMessage[], player?: MusicAssistantPlayerContext, options?: RequestOptions): Promise<MusicAssistantAnswer>;
 }
 /**
- * "O Melhor DJ": a written-and-spoken link between tracks, and a whole planned
- * set.
+ * "O Melhor DJ": a radio session for one listener, one song at a time.
+ *
+ * The server holds the session - what played, what was skipped, what he said,
+ * what the listener asked for - so a client only ever says what just happened
+ * and gets the next song back. Ask for one when the current song ends, when
+ * the listener skips, or when they want something else.
  *
- * Both methods pass `retry: false` by default. That is not caution about
+ * {@link next} passes `retry: false` by default. That is not caution about
  * duplicates - the transport does not replay a `POST` anyway - it is about the
- * one thing it DOES replay: a `429`. The hourly cap here counts every request
+ * one thing it DOES replay: a `429`. The hourly cap counts every request
  * including the refused ones, so waiting out a `Retry-After` and asking again
  * pushes the count further past the cap and cannot succeed inside the hour.
  * Pass `retry: {}` to opt back in if you are sure the `429` came from the
@@ -900,57 +946,46 @@ export declare class MusicAssistantNamespace extends Resource {
  */
 export declare class MusicDjNamespace extends Resource {
     /**
-     * `POST /music_dj` - the DJ introduces the next track.
+     * `POST /music_dj/next` - the next song, chosen with the whole session in
+     * view.
      *
-     * Returns the script AND the spoken audio in one answer, base64 in the JSON
-     * body rather than as a URL, because the clip is small and ephemeral and
-     * nothing stores it. Decode with {@link musicDjAudioBytes}, or hand
-     * {@link musicDjAudioDataUrl} to a player that takes a URI.
+     * `next({})` is a valid cold start: with no session on air the server opens
+     * one. The answer always carries a `song`; `text` and `audio_base64` come
+     * only on the turns where he speaks (the first song, after a request, and
+     * every third song), so treat their absence as normal and play the song.
      *
-     * Both ids are resolved against what the caller may play, so a followed
-     * playlist's track works and a stranger's does not. `previousSongId` is genuinely optional and
-     * is what lets the script say goodbye to the outgoing track.
+     * A song the session already played is never returned, which is what lets a
+     * client keep the whole session in its queue and walk back through it.
      *
-     * Generation takes seconds; the deadline defaults to
-     * {@link MUSIC_DJ_TIMEOUT_MS}. The
-     * intended pattern is to ask for the clip while the current track is still
-     * playing and drop it on the boundary, ideally over the outgoing
-     * instrumental.
+     * Choosing takes seconds and speaking takes more; the deadline defaults to
+     * {@link MUSIC_DJ_TIMEOUT_MS}. Ask for the next song while the current one
+     * is still playing, or the listener hears the gap.
      *
      * @throws {OmsError} `401 "Session required"` when unauthenticated.
-     * @throws {OmsError} `404 "Song not found"` for either id.
      * @throws {OmsError} `429 "DJ limit reached, try again later"` past
      *   {@link MUSIC_DJ_HOURLY_CAP}.
-     * @throws {OmsError} `502 "DJ is unavailable right now"` when the script
-     *   failed, `503 "DJ voice is unavailable right now"` when the voice did.
-     *   The split is deliberate: a `503` means the words exist but nothing can
-     *   say them.
+     * @throws {OmsError} `502 "DJ is unavailable right now"` when no song could
+     *   be chosen - including the honest case where the library has nothing left
+     *   that the session has not already played.
      */
-    interstitial(input: {
-        readonly nextSongId: SongId;
-        readonly previousSongId?: SongId | null;
-    }, options?: RequestOptions): Promise<MusicDjInterstitial>;
+    next(input?: MusicDjNextInput, options?: RequestOptions): Promise<MusicDjNext>;
     /**
-     * `POST /music_dj/batch` - a whole set: what to play next AND the words
-     * introducing it, from one model call.
+     * `GET /music_dj/session` - the session still on air, or `null`.
      *
-     * The intended cadence is a real station's: take the set, play it, and come
-     * back when about two tracks remain. Every field is optional, so
-     * `batch({})` is a valid cold start.
-     *
-     * `recentSongIds` is a filter, not just a hint - the planner subtracts those
-     * ids from its own picks. Send a list covering the whole library and the
-     * planner has nothing left, which surfaces as `502 "DJ is unavailable right
-     * now"` rather than as an empty set. Keep it to a genuine recent window; only
-     * the last 60 are read anyway.
-     *
-     * `songs` comes back in play order, in the full `GET /songs` shape, already
-     * scoped to what the caller may play. It is never empty.
+     * `null` is the ordinary answer for someone who has not listened today: a
+     * session goes stale after two hours of silence and stops being served here.
+     * Use it to rebuild the transcript when a screen opens, not to decide
+     * whether {@link next} may be called - it always may.
+     */
+    session(options?: RequestOptions): Promise<MusicDjSession | null>;
+    /**
+     * `DELETE /music_dj/session` - end the session on air.
      *
-     * Shares {@link MUSIC_DJ_HOURLY_CAP} with {@link interstitial}. Same
-     * timeouts, same error shapes.
+     * Idempotent: with nothing on air it still answers `204`. The next
+     * {@link next} starts a session with no memory of this one, which is the
+     * point - it is how a listener says "forget what I asked for".
      */
-    batch(input?: MusicDjBatchInput, options?: RequestOptions): Promise<MusicDjBatch>;
+    end(options?: RequestOptions): Promise<void>;
 }
 /**
  * The `music.social` entry point, holding the five families as sub-namespaces.
@@ -1045,7 +1080,9 @@ export declare function musicStorageAffords(usage: MusicStorageUsage, bytes: num
  * slightly short audio is a better failure than one that throws inside a
  * playback callback.
  */
-export declare function musicDjAudioBytes(clip: Pick<MusicDjInterstitial, "audio_base64">): Uint8Array;
+export declare function musicDjAudioBytes(clip: {
+    readonly audio_base64: string;
+}): Uint8Array;
 /**
  * Wraps a DJ clip as a `data:` URI, for a player that takes a URI rather than
  * bytes - which is most of them.
@@ -1054,4 +1091,7 @@ export declare function musicDjAudioBytes(clip: Pick<MusicDjInterstitial, "audio
  * in memory, so this is cheap in every sense that matters at this size. It is
  * not a URL anything can fetch twice - it is the bytes, spelled differently.
  */
-export declare function musicDjAudioDataUrl(clip: MusicDjInterstitial): string;
+export declare function musicDjAudioDataUrl(clip: {
+    readonly audio_base64: string;
+    readonly format?: string;
+}): string;

package/dist/types/resources/music/songs.d.ts

@@ -143,6 +143,35 @@ export interface Song extends Omit<BaseRecord, "id"> {
     readonly source_id: string | null;
     /** Recording identifier, when the importer resolved one. */
     readonly isrc: string | null;
+    /**
+     * ISO 639-1 code of the language SUNG on the track (`"es"`, `"pt"`, `"ja"`),
+     * or `null`.
+     *
+     * Derived, not declared: the server runs a detector over the stored lyrics,
+     * and falls back to unambiguous Last.fm tags (`"j-pop"`, `"fado"`) when
+     * there are none. So `null` means "not known yet" - a song whose lyrics were
+     * never fetched, or an instrumental - and NEVER "no language". Treat it as
+     * unknown rather than quietly dropping it from a language view.
+     */
+    readonly language: string | null;
+    /**
+     * Lowercased Last.fm tags for the track, most-voted first, at most six.
+     *
+     * Crowd tags, not a controlled vocabulary: expect `"rock"` and
+     * `"female vocalists"` in the same list, and expect `[]` for anything
+     * obscure. The server drops the junk ones ("seen live", "albums i own") and
+     * falls back to the artist's tags when the track has none of its own, which
+     * is why two songs by one artist often carry identical lists.
+     */
+    readonly tags: string[];
+    /**
+     * Tempo in beats per minute, or `null` when it is not known.
+     *
+     * Comes from the recording's own registry entry, matched by ISRC, so a
+     * track with no ISRC never gets one and a remix is never given the
+     * original's tempo. `null` is common and means nothing about the music.
+     */
+    readonly bpm: number | null;
     readonly original_filename: string | null;
     readonly audio_codec: string | null;
     readonly audio_bitrate_kbps: number | null;
@@ -445,7 +474,7 @@ export interface MusicExternalSearchResult {
  * `artist` is on the list but is not a column - see
  * {@link ListSongsParams.artist}.
  */
-export declare const SONG_FILTER_COLUMNS: readonly ["id", "created_at", "updated_at", "title", "album", "position", "year", "artist"];
+export declare const SONG_FILTER_COLUMNS: readonly ["id", "created_at", "updated_at", "title", "album", "position", "year", "artist", "language"];
 /** Columns the backend will accept in `modifiers[order]`. */
 export declare const SONG_ORDER_COLUMNS: readonly string[];
 /** Filters shared by `GET /songs` and `GET /songs/albums`. */
@@ -503,6 +532,15 @@ export interface SongFilters {
      * excluded even if they also appear as a feature.
      */
     readonly artistRole?: SongArtistRole;
+    /**
+     * Exact language code, or a list of them, sent as `exact_search[language]`.
+     *
+     * Matches {@link Song.language}, with the same caveat: rows the server could
+     * not classify hold `null` and are NOT returned by any code you ask for.
+     * Pass `null` to get exactly those - the unclassified pile - which is a
+     * different question from "songs with no words".
+     */
+    readonly language?: string | string[] | null;
 }
 /** Arguments for {@link MusicSongsNamespace.list}. */
 export interface ListSongsParams extends SongFilters, ListParams<(typeof SONG_FILTER_COLUMNS)[number]> {