@omelhorsite/sdk 0.12.1 → 0.13.0

package/README.md

@@ -100,7 +100,7 @@ const rows = await oms.http.get<{ id: string }[]>("/some/path");
 
 ## Namespaces
 
-- `oms.auth` - OAuth: device grant, refresh, revoke, `whoami`.
+- `oms.auth` - OAuth: device grant, refresh, revoke, `whoami`. `decodeIdToken(idToken).sub` is the stable identifier; `email` is a contact and `email_verified` is often `false`, so never find or merge users by email.
 - `oms.sessions`, `oms.passkeys` - sign-in, sign-up, OTP, passkeys.
 - `oms.account` - the signed-in user, profile, sessions, usage. `oms.account.notificationPreferences` decides, per notification kind, whether it shows in the inbox and whether it is emailed; the security kinds always email, unless the master switch is off.
 - `oms.storage` - files and folders: upload, download, share.

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,
@@ -13868,6 +13874,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", {

package/dist/types/auth/tokens.d.ts

@@ -55,8 +55,22 @@ export interface IdentityClaims {
     readonly iat?: number;
     /** Present only when the `profile` scope was granted. Mutable, display only. */
     readonly preferred_username?: string;
-    /** Present only when the `email` scope was granted. Mutable, display only. */
+    /**
+     * Present only when the `email` scope was granted. Mutable, display only.
+     *
+     * Never look a user up by this. An account can be created with any address
+     * and used without proving it, so the value may belong to someone else;
+     * matching on it lets whoever registers with a victim's address into the
+     * victim's account on your side. Key on `iss` + `sub`.
+     */
     readonly email?: string;
+    /**
+     * Whether the server holds proof that `email` belongs to the user. Present
+     * whenever `email` is, and often `false`. `true` still only means the
+     * server checked it once; confirm it yourself before attaching the address
+     * to an account that already existed.
+     */
+    readonly email_verified?: boolean;
     readonly [claim: string]: unknown;
 }
 /**

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/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.
  *
@@ -254,6 +255,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. */
@@ -901,6 +944,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.1",
+  "version": "0.13.0",
   "description": "TypeScript SDK for the omelhorsite API. Isolate-safe: no node builtins, no environment access, no stdout.",
   "type": "module",
   "license": "UNLICENSED",