@omelhorsite/sdk 0.2.0 → 0.4.0

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

@@ -0,0 +1,222 @@
+/** Shapes, constants and helpers shared by more than one `admin` module. */
+import type { Id, Timestamp } from "../../types";
+/**
+ * Where a client sits in the review queue.
+ *
+ * There is no fourth state and in particular there is no "suspended": pulling
+ * an approved client back off the air is `"rejected"`, which is why
+ * {@link AdminOauthApplicationsNamespace.reject} accepts a client that was
+ * already approved.
+ *
+ * A database check constraint pins the column to exactly these three, so this
+ * union is closed rather than widened to `string`.
+ */
+export type OauthApprovalStatus = "pending" | "approved" | "rejected";
+/** Every value {@link OauthApprovalStatus} can take, for building filters. */
+export declare const OAUTH_APPROVAL_STATUSES: readonly OauthApprovalStatus[];
+/**
+ * A person attached to a client: its owner, or the administrator who decided.
+ *
+ * Three keys and no more. This is not the full user record, precisely so that
+ * reviewing a client does not leak an email address or a session count into an
+ * admin panel.
+ */
+export interface OauthApplicationParty {
+    /** User id. A string, like every user id in this API. */
+    readonly id: Id;
+    readonly handle: string;
+    /** Display name. `null` for an account that never set one. */
+    readonly name: string | null;
+}
+/**
+ * The shape both halves render for a registered OAuth client.
+ *
+ * The owner routes and the administrator routes emit the same eleven keys on
+ * purpose, so one renderer works on both surfaces. The differences are in the
+ * VALUES, not the keys, and there are exactly two:
+ *
+ * - `approved_by` is hardcoded `null` on the owner routes. Which administrator
+ *   decided what is deliberately withheld from the applicant, so read it as
+ *   "not disclosed", not as "nobody approved it";
+ * - the owner routes only ever show you your own rows, so `owner` there is
+ *   always you.
+ */
+export interface OauthApplicationSummary {
+    /**
+     * Primary key, and an **integer**: one of the handful of ids in this API that
+     * is not a string. Do not compare it against an {@link Id}.
+     */
+    readonly id: number;
+    /** The public `client_id`, i.e. the `uid` column. Not a secret. */
+    readonly client_id: string;
+    /** What the consent screen renders. At most 60 characters. */
+    readonly name: string;
+    /**
+     * Already split: what arrives here is an array and never needs splitting.
+     *
+     * An EMPTY array would be dangerous rather than harmless - on the server a
+     * blank scopes column means "every scope the server has", not "none" - which
+     * is why both write paths refuse to save one.
+     */
+    readonly scopes: string[];
+    /**
+     * `true` for a client that holds a secret. Frozen after registration: see
+     * {@link MyOauthApplicationsNamespace.update} for why neither direction is
+     * editable.
+     */
+    readonly confidential: boolean;
+    /**
+     * Every registered redirect URI, in ONE space-separated string, exactly as
+     * the server stores it. Use {@link splitRedirectUris} rather than reading it
+     * raw.
+     *
+     * Matching at the authorization endpoint is exact - no wildcards, no prefix
+     * match, no fragment - so a URI that looks nearly right matches nothing.
+     */
+    readonly redirect_uri: string;
+    readonly approval_status: OauthApprovalStatus;
+    /** When it was approved, `null` while pending or rejected. */
+    readonly approved_at: Timestamp | null;
+    /** The reason shown to the owner. `null` unless rejected. At most 500 characters. */
+    readonly rejection_reason: string | null;
+    /**
+     * Who registered it. `null` for the clients this project ships itself
+     * (`owner_id` is deliberately NULL for those) **and** for a client whose
+     * owner deleted their account.
+     *
+     * Because those two cases are indistinguishable here, `owner === null` is
+     * NOT a trust signal. See {@link isShippedClient}.
+     */
+    readonly owner: OauthApplicationParty | null;
+    /**
+     * The administrator who approved it, or `null`.
+     *
+     * Always `null` on {@link MyOauthApplicationsNamespace} regardless of the
+     * truth. Populated on {@link AdminOauthApplicationsNamespace}.
+     */
+    readonly approved_by: OauthApplicationParty | null;
+    readonly created_at: Timestamp;
+}
+/** The longest name the server accepts, measured after normalisation. */
+export declare const OAUTH_APP_NAME_MAX_LENGTH = 60;
+/**
+ * How many of ONE person's clients may sit in the review queue at once. The
+ * sixth answers `429 too_many_pending`, and so does an edit that would send a
+ * sixth approved client back into the queue. Deleting a pending client frees
+ * its slot immediately.
+ */
+export declare const OAUTH_APP_MAX_PENDING = 5;
+/** The most redirect URIs one client may register. More than this is `400 redirect_uri_excessive`. */
+export declare const OAUTH_REDIRECT_URI_MAX_COUNT = 8;
+/** The longest `redirect_uri` value the server accepts, counted across the whole space-separated string. */
+export declare const OAUTH_REDIRECT_URI_MAX_LENGTH = 1024;
+/**
+ * What a blank `redirect_uri` registers.
+ *
+ * RFC 8252 section 7.3. No port, because the client listens on an ephemeral one
+ * and the server drops the port from both sides before comparing, so
+ * `http://127.0.0.1:49731/callback` matches the first entry.
+ *
+ * Both literals, because `127.0.0.1` and `[::1]` are two different hosts to
+ * that comparison and an IPv6-only machine can only bind the second.
+ * `localhost` is deliberately absent and registering it is a mistake: the
+ * server does not treat a name as loopback and would then demand an exact port
+ * match, which is the one thing an ephemeral port cannot promise.
+ */
+export declare const NATIVE_LOOPBACK_REDIRECT_URIS: readonly string[];
+/** {@link NATIVE_LOOPBACK_REDIRECT_URIS} as the single column value the server stores. */
+export declare const NATIVE_LOOPBACK_REDIRECT_VALUE = "http://127.0.0.1/callback http://[::1]/callback";
+/**
+ * The `client_id`s this project ships itself.
+ *
+ * Pinned constants rather than values generated per environment, so matching on
+ * them is stable across dev, CI and production.
+ */
+export declare const SHIPPED_CLIENT_IDS: readonly string[];
+/**
+ * True for a client this project ships, by `client_id`.
+ *
+ * **Use this, not `owner === null`.** A NULL owner means two very different
+ * things - "registered by the operator" and "orphaned when its owner deleted
+ * their account" - and calling an orphan official is exactly the lie the whole
+ * review gate exists to prevent. The server draws the same distinction, and the
+ * consent screen uses the pinned list too.
+ */
+export declare function isShippedClient(application: {
+    readonly client_id: string;
+}): boolean;
+/**
+ * Splits the one space-separated `redirect_uri` column into the URIs it holds.
+ *
+ * The server keeps every registered redirect URI in a single column. Splitting
+ * on whitespace is exactly what the server does on the way in, so what comes
+ * back out is what was registered, character for character.
+ */
+export declare function splitRedirectUris(value: string | null | undefined): string[];
+/**
+ * Normalises a redirect URI list the way the server will store it.
+ *
+ * Split, trim, de-duplicate, join with single spaces. **Nothing else.** No
+ * trailing slash is added or removed, no scheme is upgraded, no case is folded:
+ * redirect matching is exact, so quietly "fixing" a URI would register
+ * something the client can never match and the failure would only appear at the
+ * end of a login attempt.
+ *
+ * A blank result means the server will register
+ * {@link NATIVE_LOOPBACK_REDIRECT_VALUE}, which is what
+ * {@link registeredRedirectUris} makes explicit.
+ */
+export declare function normalizeRedirectUris(raw: string | null | undefined): string;
+/**
+ * What the server will actually store for this input, blank included.
+ *
+ * Use it to compare a form against a record: an empty field and a field holding
+ * the loopback pair register the same value, so comparing the raw strings would
+ * report a change that is not one.
+ */
+export declare function registeredRedirectUris(raw: string | null | undefined): string;
+/**
+ * Predicts whether an edit will send an APPROVED client back to the review
+ * queue, before the call is made.
+ *
+ * Losing an approval without being told is the difference between "I did that"
+ * and "this is broken": the client keeps its `client_id`, keeps working for
+ * about as long as its live tokens last, and then starts answering
+ * `invalid_client` with nothing in the request to explain it. Warn first.
+ *
+ * The rule reproduced here is:
+ *
+ * - a client that is not `approved` cannot be sent back to a queue it is
+ *   already in, so this is always `false` for `pending` and `rejected`;
+ * - **any** change of name requeues. The name is what the consent screen shows;
+ * - **widening** scopes requeues. Narrowing does not: asking for less than what
+ *   was already reviewed has nothing left to review;
+ * - **any** move of the redirect URI requeues, in either direction. There is no
+ *   "narrower" destination - a different destination is a different
+ *   destination, and it is where the authorization code gets delivered.
+ *
+ * This is a prediction, not the enforcement. The server decides, and the
+ * `approval_status` on the response is the answer.
+ */
+export declare function editWouldRequeue(application: OauthApplicationSummary, next: {
+    readonly name: string;
+    readonly scopes: readonly string[];
+    readonly redirectUris: string;
+}): boolean;
+/**
+ * One day of a 30 day series.
+ *
+ * Every daily series on the administrator surface has **exactly 30 entries,
+ * oldest first, ending today**, with `count: 0` filled in for days that had
+ * nothing. The series is safe to plot without gap filling, and the window is
+ * fixed server-side: there is no parameter to widen it.
+ *
+ * Structurally identical to `ShortLinkDailyClicks` from the `shortLinks`
+ * namespace, and kept separate because half the series here count creations
+ * rather than clicks.
+ */
+export interface AdminDailyCount {
+    /** `YYYY-MM-DD`. */
+    readonly date: string;
+    readonly count: number;
+}

package/dist/types/resources/admin/vocalSeparations.d.ts

@@ -0,0 +1,98 @@
+/** `oms.admin.vocalSeparations` - every separation run on the server. Administrators only. */
+import type { VocalSeparation } from "../tools/vocalSeparation";
+import { Resource } from "../../http";
+import type { ListParams } from "../../listing";
+import type { Id, Paginated, RequestOptions } from "../../types";
+/**
+ * A separation run as the admin surface renders it.
+ *
+ * The same shape the tool namespace reads, so the type is the same:
+ * every key of {@link VocalSeparation}, `user_id` and `ip_address` included.
+ * What changes is the SCOPE - an administrator sees every run on the server
+ * rather than their own.
+ */
+export type AdminVocalSeparation = VocalSeparation;
+/** Filter columns of `GET /admin/vocal_separations`. */
+export declare const ADMIN_VOCAL_SEPARATION_FILTER_COLUMNS: readonly ["id", "status", "model_id", "created_at", "finished_at", "user_id", "song_id"];
+/** Filters for {@link AdminVocalSeparationsNamespace.list}. */
+export interface ListAdminVocalSeparationsParams extends ListParams<(typeof ADMIN_VOCAL_SEPARATION_FILTER_COLUMNS)[number]> {
+    /** Exact status. An array becomes an `IN`. */
+    readonly status?: string | readonly string[];
+    /** Exact model id. An array becomes an `IN`. */
+    readonly modelId?: string | readonly string[];
+    /**
+     * `"song"` for runs started from the music library, `"tool"` for uploads.
+     *
+     * A top-level parameter, not a search bucket: the server turns it into a
+     * `song_id IS NOT NULL` test. Omitting it means both.
+     */
+    readonly source?: "song" | "tool";
+    /** `exact_search[user_id]`. */
+    readonly userId?: Id;
+    /** `modifiers[order]`. Defaults to `"created_at:desc"`. */
+    readonly order?: string;
+}
+/**
+ * `oms.admin.vocalSeparations` - **administrators only**. Every separation run
+ * on the server.
+ *
+ * The unprivileged half is `oms.tools.vocalSeparation`, which is scoped to the
+ * caller's own runs and the songs they own.
+ */
+export declare class AdminVocalSeparationsNamespace extends Resource {
+    /**
+     * `GET /admin/vocal_separations` - every run, newest first.
+     *
+     * A bare JSON array through the generic list DSL, with ETag and `304`.
+     *
+     * **This listing is not cheap and the cost is not in the database.** The
+     * server computes `progress_percent` by calling the separator sidecar,
+     * synchronously, ONCE PER ROW THAT IS `"processing"`. A page with twenty live
+     * runs is twenty sidecar round trips inside one request, and if the sidecar
+     * is slow or down the whole listing is slow with it. Filter to terminal
+     * statuses when you only want history, and keep the page size modest when you
+     * are polling a dashboard.
+     *
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    list(params?: ListAdminVocalSeparationsParams, options?: RequestOptions): Promise<Paginated<AdminVocalSeparation>>;
+    /**
+     * `GET /admin/vocal_separations/:id` - one run, anybody's.
+     *
+     * @throws {OmsApiError} 404 `"Resource not found"`.
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    get(id: Id, options?: RequestOptions): Promise<AdminVocalSeparation>;
+    /**
+     * `POST /admin/vocal_separations/:id/cancel` - stops a run.
+     *
+     * **The row lands on `"failed"`, not on a cancelled status, and there is no
+     * cancelled status for a separation.** The `error` field is set to
+     * `"Canceled by admin"` and that string is the only way to tell an
+     * administrative stop from a genuine failure. Anything counting failures will
+     * count this, so match on the message if that matters.
+     *
+     * A run attached to a song also clears that song's
+     * `vocal_separation_started_at`, which is what lets the owner start a new
+     * separation instead of being told one is already running.
+     *
+     * Like every cancel in this API, it marks the row rather than reaching into
+     * the worker.
+     *
+     * @throws {OmsApiError} 400 `"Already terminal"`; 404 `"Resource not found"`.
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    cancel(id: Id, options?: RequestOptions): Promise<AdminVocalSeparation>;
+    /**
+     * `DELETE /admin/vocal_separations/:id` - deletes a run. Answers `204`, empty.
+     *
+     * The stems go with it: the attached audio is destroyed with the row, and a
+     * complete run's download URLs stop working immediately. Deleting a run that
+     * is still processing does not stop the worker, it removes the row the worker
+     * is going to write to.
+     *
+     * @throws {OmsApiError} 404 `"Resource not found"`.
+     * @throws {OmsAuthError} 403 for a non-admin.
+     */
+    destroy(id: Id, options?: RequestOptions): Promise<void>;
+}