@omelhorsite/sdk 0.12.2 → 0.15.1

package/dist/index.js

@@ -11076,6 +11076,12 @@ class AuthSessionsNamespace extends Resource {
   async changeEmailStart(newEmail, options = {}) {
     return this.http.post("/users/update_email_start", { email: newEmail }, options);
   }
+  async verifyEmailStart(options = {}) {
+    return this.http.post("/users/verify_email_start", undefined, options);
+  }
+  async verifyEmailComplete(code, options = {}) {
+    return this.http.post("/users/verify_email_end", { code }, options);
+  }
   async changeEmailComplete(input, options = {}) {
     return this.http.post("/users/update_email_end", {
       email: input.email,
@@ -13515,9 +13521,8 @@ var MUSIC_ASSISTANT_MAX_ACTIONS = 10;
 var MUSIC_ASSISTANT_MAX_BODY_BYTES = 256 * 1024;
 var MUSIC_ASSISTANT_READ_ONLY_AFTER_MS = 2 * 24 * 60 * 60 * 1000;
 var MUSIC_ASSISTANT_TIMEOUT_MS = 90000;
-var MUSIC_DJ_HOURLY_CAP = 40;
+var MUSIC_DJ_HOURLY_CAP = 90;
 var MUSIC_DJ_TIMEOUT_MS = 120000;
-var MUSIC_DJ_BATCH_SIZE = 4;
 
 class MusicJamsNamespace extends Resource {
   async list(options = {}) {
@@ -13608,33 +13613,31 @@ class MusicAssistantNamespace extends Resource {
 }
 
 class MusicDjNamespace extends Resource {
-  interstitial(input, options = {}) {
-    const body = { next_song_id: input.nextSongId };
-    if (input.previousSongId !== undefined && input.previousSongId !== null) {
-      body["previous_song_id"] = input.previousSongId;
-    }
-    return this.http.post("/music_dj", body, {
-      ...options,
-      timeoutMs: options.timeoutMs ?? MUSIC_DJ_TIMEOUT_MS,
-      retry: options.retry ?? false
-    });
-  }
-  batch(input = {}, options = {}) {
+  next(input = {}, options = {}) {
     const body = {};
+    if (input.sessionId !== undefined)
+      body["session_id"] = input.sessionId;
     if (input.request !== undefined)
       body["request"] = input.request;
-    if (input.recentSongIds !== undefined)
-      body["recent_song_ids"] = input.recentSongIds;
-    if (input.skippedSongIds !== undefined)
-      body["skipped_song_ids"] = input.skippedSongIds;
-    if (input.batchIndex !== undefined)
-      body["batch_index"] = input.batchIndex;
-    return this.http.post("/music_dj/batch", body, {
+    if (input.skippedSongId !== undefined)
+      body["skipped_song_id"] = input.skippedSongId;
+    if (input.speak !== undefined)
+      body["speak"] = input.speak;
+    if (input.restart !== undefined)
+      body["restart"] = input.restart;
+    return this.http.post("/music_dj/next", body, {
       ...options,
       timeoutMs: options.timeoutMs ?? MUSIC_DJ_TIMEOUT_MS,
       retry: options.retry ?? false
     });
   }
+  async session(options = {}) {
+    const body = await this.http.get("/music_dj/session", options);
+    return body.session ?? null;
+  }
+  async end(options = {}) {
+    await this.http.delete("/music_dj/session", options);
+  }
 }
 
 class MusicSocialNamespace extends Resource {
@@ -13737,7 +13740,8 @@ var SONG_FILTER_COLUMNS = Object.freeze([
   "album",
   "position",
   "year",
-  "artist"
+  "artist",
+  "language"
 ]);
 var SONG_ORDER_COLUMNS = Object.freeze([
   "id",
@@ -13868,6 +13872,13 @@ class MusicSongsNamespace extends Resource {
   async deleteSeparation(id, options = {}) {
     await this.http.delete(`/songs/${encodeURIComponent(String(id))}/separation`, options);
   }
+  async matchCandidates(id, params = {}, options = {}) {
+    const body = await this.http.get(`/songs/${encodeURIComponent(String(id))}/match_candidates`, { ...options, query: { limit: params.limit } });
+    return body.items ?? [];
+  }
+  async rematch(id, input = {}, options = {}) {
+    return this.http.post(`/songs/${encodeURIComponent(String(id))}/rematch`, input.sourceUrl === undefined ? {} : { source_url: input.sourceUrl }, options);
+  }
   async listLiked(params = {}, options = {}) {
     const before = params.before instanceof Date ? params.before.toISOString() : params.before;
     const rows = await this.http.get("/liked_songs", {
@@ -13925,7 +13936,13 @@ class MusicSongsNamespace extends Resource {
     return listQuery(params, at, {
       order: at === undefined ? undefined : "created_at:asc",
       search: { title: params.title },
-      exactSearch: { album: params.album, year: params.year, id: params.ids, artist: params.artist },
+      exactSearch: {
+        album: params.album,
+        year: params.year,
+        id: params.ids,
+        artist: params.artist,
+        language: params.language
+      },
       top: params.artistRole === undefined ? {} : { artist_role: params.artistRole }
     });
   }
@@ -16270,7 +16287,6 @@ export {
   MUSIC_PRESIGNED_URL_TTL_MS,
   MUSIC_DJ_TIMEOUT_MS,
   MUSIC_DJ_HOURLY_CAP,
-  MUSIC_DJ_BATCH_SIZE,
   MUSIC_ASSISTANT_TIMEOUT_MS,
   MUSIC_ASSISTANT_READ_ONLY_AFTER_MS,
   MUSIC_ASSISTANT_MAX_BODY_BYTES,

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

@@ -30,6 +30,13 @@ export interface User extends BaseRecord {
     readonly country_code?: string | null;
     /** `en`, `pt` or `lv`: the language of the emails sent to this account. Own account only. */
     readonly language?: string | null;
+    /**
+     * Whether the address on the account was proven by an emailed code: the same
+     * fact the id token's `email_verified` carries. Own account only. `false`
+     * on accounts older than the emailed sign-up code until they confirm once
+     * with `sessions.verifyEmailStart` / `verifyEmailComplete`.
+     */
+    readonly email_verified?: boolean;
     readonly email_is_public?: boolean;
     readonly gender_is_public?: boolean;
     readonly library_public?: boolean;

package/dist/types/resources/auth/sessions.d.ts

@@ -692,6 +692,26 @@ export declare class AuthSessionsNamespace extends Resource {
      *   rejected at write time - already taken, malformed. Both codes are
      *   consumed by then and the flow restarts at {@link changeEmailStart}.
      */
+    /**
+     * `POST /users/verify_email_start` - emails a code to the address already on
+     * the account, so an account that never proved its mailbox (one older than
+     * the emailed sign-up code) can. Requires a live session; an account that is
+     * already verified answers `200` without sending anything.
+     *
+     * Same shared `*_start` throttle as the other code-issuing calls.
+     *
+     * @throws {OmsAuthError} 401 without a live session.
+     */
+    verifyEmailStart(options?: RequestOptions): Promise<string>;
+    /**
+     * `POST /users/verify_email_end` - presents the code; answers `200` with the
+     * updated {@link User}, `email_verified` now `true`.
+     *
+     * @throws {OmsAuthError} 401 without a live session.
+     * @throws {OmsApiError} 404 `"Invalid Verification"` when the code is wrong,
+     *   expired or burned.
+     */
+    verifyEmailComplete(code: string, options?: RequestOptions): Promise<User>;
     changeEmailComplete(input: ChangeEmailInput, options?: RequestOptions): Promise<User>;
     /**
      * `POST /users/destroy_start` - emails a deletion code to the address on the

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

@@ -60,6 +60,7 @@ import { Resource } from "../../http";
 import type { ListParams } from "../../listing";
 import { type BaseRecord, type FileInput, type FileOutput, type Id, type NativeFile, type Paginated, type RequestOptions, type Timestamp } from "../../types";
 import type { VocalSeparation } from "../tools/vocalSeparation";
+import type { SongImport } from "./imports";
 /**
  * Primary key of a song. An **integer**, unlike most ids in this API.
  *
@@ -113,7 +114,7 @@ export interface SongArtistCredit extends Omit<BaseRecord, "id"> {
     readonly compressed_image_fs_node_id?: Id | null;
 }
 /** Where a track came from. */
-export type SongSourceKind = "upload" | "yt_dlp" | "spotify_sync";
+export type SongSourceKind = "upload" | "yt_dlp" | "spotify_sync" | "rematch";
 /**
  * A track in the library.
  *
@@ -142,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;
@@ -254,6 +284,48 @@ export interface SongSeparationStatus {
      */
     readonly job: VocalSeparation | null;
 }
+/** Providers a track can be matched against. */
+export type SongMatchSource = "youtube" | "soundcloud" | "bandcamp";
+/**
+ * One take the matcher found for a track, scored the way the import scores it.
+ *
+ * A candidate with `score: null` was REJECTED and `reject_reason` says why
+ * ("title says 'cover', query did not"); it is returned anyway, because the
+ * reason is often the whole answer to "why did I get this recording". Rejected
+ * candidates can still be passed to {@link MusicSongsNamespace.rematch}: a
+ * deliberate choice is not second-guessed.
+ */
+export interface SongMatchCandidate {
+    readonly source: SongMatchSource;
+    readonly title: string | null;
+    readonly uploader: string | null;
+    /** The page to import from. Feed it back as `sourceUrl` to take this one. */
+    readonly url: string | null;
+    /** Absent for providers whose search does not carry a runtime. */
+    readonly duration_s: number | null;
+    readonly thumbnail: string | null;
+    readonly source_id: string | null;
+    /** Higher is a better match; `null` means rejected. */
+    readonly score: number | null;
+    readonly reject_reason: string | null;
+    /** Where the provider's own search ranked it, before scoring. */
+    readonly rank: number;
+    /** True for the source the song's audio already came from. */
+    readonly current: boolean;
+}
+/** Arguments for {@link MusicSongsNamespace.matchCandidates}. */
+export interface ListSongMatchCandidatesParams {
+    /** Candidates per provider. Clamped to 1..20; defaults to 8. */
+    readonly limit?: number;
+}
+/** Arguments for {@link MusicSongsNamespace.rematch}. */
+export interface RematchSongInput {
+    /**
+     * The page to download from, normally a {@link SongMatchCandidate.url}.
+     * Omit to re-run the matcher over the track's original search terms.
+     */
+    readonly sourceUrl?: string;
+}
 /** A liked track. The join row, with the whole song inlined. */
 export interface LikedSong extends Omit<BaseRecord, "id"> {
     /** Integer primary key of the like itself. NOT the song id. */
@@ -402,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`. */
@@ -460,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]> {
@@ -901,6 +982,49 @@ export declare class MusicSongsNamespace extends Resource {
      * @throws {OmsAuthError} 401 when the song is not yours.
      */
     deleteSeparation(id: SongId, options?: RequestOptions): Promise<void>;
+    /**
+     * `GET /songs/:id/match_candidates` - every take the matcher can find for
+     * this track, across all three providers, scored and ordered best first.
+     *
+     * This is the answer to "this is the wrong recording". A track imported by
+     * artist and title is matched, not looked up, and the classic wrong result is
+     * a cover: same runtime, the original artist's name in its title, and nothing
+     * about it that a duration check can catch. The pool shows what the matcher
+     * chose between, with the rejects kept and labelled.
+     *
+     * Candidates are searched live on three providers, so this is SLOW - seconds,
+     * not milliseconds - and worth its own timeout. Nothing is cached: two calls
+     * a minute apart can return different pools.
+     *
+     * Scores are comparable within one response and meaningless across two.
+     *
+     * @throws {OmsApiError} 404 for a song that is not yours, 502 when the
+     *   downloader is unreachable.
+     */
+    matchCandidates(id: SongId, params?: ListSongMatchCandidatesParams, options?: RequestOptions): Promise<SongMatchCandidate[]>;
+    /**
+     * `POST /songs/:id/rematch` - re-download this track onto the same record.
+     *
+     * The song row survives: its id, its credits, and every playlist entry, like
+     * and play event that points at it. Only the audio is replaced, along with
+     * the fields that describe the file (runtime, codec, source). Any vocal
+     * separation is thrown away, because the stems came out of audio the song no
+     * longer has.
+     *
+     * With a `sourceUrl` the pick is taken as given - no duration or cover check
+     * stands between you and the recording you named. Without one the matcher
+     * re-runs over the track's original search terms, which is the useful move
+     * after a bad match rather than a repeat of it.
+     *
+     * Returns the import to poll through `music.imports`; the swap lands when it
+     * reaches `complete`.
+     *
+     * @throws {OmsAuthError} 401 when the song is not yours.
+     * @throws {OmsApiError} 400 for a `sourceUrl` that is not http(s), or when no
+     *   `sourceUrl` is given and the track has no search terms to re-run (an
+     *   uploaded file, for one - there is nothing to match it against).
+     */
+    rematch(id: SongId, input?: RematchSongInput, options?: RequestOptions): Promise<SongImport>;
     /**
      * `GET /liked_songs` - the caller's likes, newest first, with each song
      * inlined in full.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omelhorsite/sdk",
-  "version": "0.12.2",
+  "version": "0.15.1",
   "description": "TypeScript SDK for the omelhorsite API. Isolate-safe: no node builtins, no environment access, no stdout.",
   "type": "module",
   "license": "UNLICENSED",