@omelhorsite/sdk 0.4.0 → 0.4.2

package/dist/types/resources/tools/srMachine.d.ts

@@ -0,0 +1,114 @@
+/** The `tools.srMachine` namespace: fetch a track's audio, artwork and metadata by URL, and transcode audio to Opus. Administrators only. */
+import { Resource } from "../../http";
+import type { FileInput, FileOutput, NativeFile, RequestOptions } from "../../types";
+/** What `GET /s_r_machine/metadata` answers. Two keys, both nullable. */
+export interface SRMachineMetadata {
+    readonly title: string | null;
+    readonly artist: string | null;
+}
+/**
+ * The SR Machine helpers, reachable as `oms.tools.srMachine`.
+ *
+ * ## Admin only, and the check is blunt
+ *
+ * Every route answers `403 "You SHALL NOT use this resource"` to anyone who is
+ * not an administrator. There is no allowlist, no scope and no per-user
+ * quota.
+ *
+ * ## What it is
+ *
+ * Four unrelated primitives left over from the "slowed + reverb" video tool:
+ * fetch the artwork behind a URL, fetch its audio, read its title and artist,
+ * and transcode an arbitrary audio blob to Opus. Nothing here touches the
+ * library - no song is created, nothing is stored, and the bytes come back in
+ * the response body. If you want a track IN the library, use
+ * `oms.music.imports.create()` instead; this is the raw pipe.
+ *
+ * Three of the four fetch a caller-supplied URL and hold a server thread while
+ * they do it, exactly like `oms.music.imports.previewPlaylist()` - but
+ * they have no budget of their own, so the only ceiling is the general
+ * 600/min. The admin gate is what stands in for a budget here. Do not build a
+ * batch loop on top of these.
+ *
+ * A YouTube URL carrying `?list=` is truncated at the `?list=` before the fetch,
+ * so a link copied from inside a playlist resolves to the single video rather
+ * than the playlist. That happens server-side, in all three fetchers.
+ *
+ * All three fetchers respond with `Content-Disposition: attachment` and a
+ * fixed filename (`artwork.jpg`, `audio.opus`), so `FileOutput.filename` is
+ * that constant rather than anything derived from the source.
+ */
+export declare class SRMachineNamespace extends Resource {
+    /**
+     * `GET /s_r_machine/metadata` - the title and artist read off a URL.
+     *
+     * Both keys can be `null` for a source that carries no tags; it is a
+     * best-effort read, not a lookup.
+     *
+     * Not retried by default: it parks a server thread for up to 60 seconds,
+     * and a failure means the source refused.
+     *
+     * @throws {OmsAuthError} 403 `"You SHALL NOT use this resource"` for a
+     *   non-admin.
+     * @throws {OmsApiError} 400 `"url is not allowed"` for a URL that is not
+     *   public http(s); 500 when the fetch itself fails - an upstream failure
+     *   surfaces as a server error here, not as a 502.
+     */
+    metadata(url: string, options?: RequestOptions): Promise<SRMachineMetadata>;
+    /**
+     * `GET /s_r_machine/artwork` - the cover behind a URL, as `image/jpeg`.
+     *
+     * Buffered fully into memory in every runtime, React Native included. It is a
+     * cover, so that is fine; {@link SRMachineNamespace.audio} is where it is not.
+     *
+     * @throws {OmsAuthError} 403 for a non-admin.
+     * @throws {OmsApiError} 400 `"url is not allowed"`; 500 on a fetch failure.
+     */
+    artwork(url: string, options?: RequestOptions): Promise<FileOutput>;
+    /**
+     * `GET /s_r_machine/audio` - the audio behind a URL, as `audio/opus`.
+     *
+     * The whole track is downloaded server-side, held in memory there, and sent
+     * back in one body which this then buffers into memory again on the client.
+     * Nothing streams. On a phone that is a whole track in the JavaScript heap,
+     * and there is no signed-URL alternative here the way there is for library
+     * media - this endpoint has no storage node behind it. Reach for it on
+     * desktop, think twice on React Native, and never for a batch.
+     *
+     * Generous `timeoutMs` by default because a long track legitimately takes
+     * minutes.
+     *
+     * @throws {OmsAuthError} 403 for a non-admin.
+     * @throws {OmsApiError} 400 `"url is not allowed"`; 500 on a fetch failure.
+     */
+    audio(url: string, options?: RequestOptions): Promise<FileOutput>;
+    /**
+     * `POST /s_r_machine/convert-opus` - transcode an audio file to Opus.
+     *
+     * Multipart, field name `file`, and the only method in this namespace that
+     * uploads. The response is `audio/opus` bytes, not JSON.
+     *
+     * Works on all three runtimes: a React Native `{ uri, name, type }` descriptor
+     * goes into the `FormData` verbatim and is streamed off disk by the native
+     * layer, while a browser or Bun caller passes a `FileInput` carrying a Blob
+     * or a `Uint8Array`. A `ReadableStream` is buffered first, because
+     * `FormData` has no streaming entry.
+     *
+     * The upload has no client-side size cap here because the server declares
+     * none - but the CDN in front of the API rejects a request body over roughly
+     * 100 MB with a 413 that never reaches it. There is no chunked path for this
+     * route, so a file above that simply cannot go through it.
+     *
+     * The server reads the whole part into memory before transcoding, so a large
+     * input is a large allocation on both sides.
+     *
+     * @throws {OmsAuthError} 403 `"You SHALL NOT use this resource"` for a
+     *   non-admin.
+     * @throws {OmsApiError} 500 when no `file` part was sent or when the input
+     *   cannot be transcoded. Neither is a graceful 400.
+     * @throws {TypeError} when a React Native descriptor is passed on a runtime
+     *   whose `FormData` is the web one, which would otherwise upload the literal
+     *   text `"[object Object]"` and answer 500.
+     */
+    convertToOpus(file: FileInput | NativeFile, options?: RequestOptions): Promise<FileOutput>;
+}

package/dist/types/resources/tools/upscale.d.ts

@@ -1,13 +1,13 @@
 /**
  * Upscaling: enlarges an image without turning it to mush.
  *
- * Same shape as background removal: `POST /upscales` enqueues a proxy job and
+ * Same shape as background removal: `POST /upscales` enqueues a job and
  * answers with a row plus a `job_id` and, when anonymous, a `watch_token`.
  *
- * Backend limits: 20 MiB, and the scale must be one the upscaler advertises.
+ * Limits: 20 MiB, and the scale must be one of `"2"`, `"3"`, `"4"`.
  *
- * Like background removal, this tool is not metered by the `Quotas` catalogue,
- * so there is no `quota()` to call first.
+ * Like background removal, this tool has no daily quota, so there is no
+ * `quota()` to call first.
  */
 import { Resource } from "../../http";
 import type { FileInput, Id, RequestOptions } from "../../types";
@@ -15,7 +15,7 @@ import { type ToolCaptcha, type ToolJobHandle, type ToolRecord, type ToolRunOpti
 /**
  * Enlargement factor, as the string the API expects.
  *
- * A string and not a number because the backend compares it against an
+ * A string and not a number because the server compares it against an
  * allow-list of strings; `4` and `"4"` are not the same request.
  */
 export type UpscaleScale = "2" | "3" | "4";
@@ -23,19 +23,15 @@ export type UpscaleScale = "2" | "3" | "4";
  * An upscale run.
  *
  * Both routes that answer with one - `POST /upscales` and `GET /upscales/:id` -
- * render the `:extended` view, so `result_url` is always PRESENT and simply
- * `null` until the run completes. There is no default-view variant of this
- * record reachable through the API.
+ * answer the same shape, so `result_url` is always PRESENT and simply `null`
+ * until the run completes.
  *
  * `progress_percent`, inherited from {@link ToolRecord}, is never sent for this
- * tool: `UpscaleBlueprint` has no such field. Progress for an upscale lives on
- * the {@link Job} row that {@link UpscaleCreated.job_id} names.
+ * tool. Progress for an upscale lives on the {@link Job} row that
+ * {@link UpscaleCreated.job_id} names.
  */
 export interface Upscale extends ToolRecord {
-    /**
-     * One of `"2"`, `"3"`, `"4"` - a string, because the column is a string and
-     * the allow-list is `%w[2 3 4]`. Never `null`: `NOT NULL DEFAULT '4'`.
-     */
+    /** One of `"2"`, `"3"`, `"4"` - a string. Never `null`; defaults to `"4"`. */
     readonly scale: string;
     /**
      * Signed URL of the enlarged PNG, or `null`. `null` covers three different
@@ -49,9 +45,9 @@ export interface Upscale extends ToolRecord {
 export type UpscaleCreated = Upscale & ToolJobHandle;
 /** Arguments for starting a run. */
 export interface CreateUpscaleInput extends ToolCaptcha {
-    /** The image. Backend cap: 20 MiB. */
+    /** The image. Cap: 20 MiB. */
     readonly file: FileInput;
-    /** Defaults to `"4"`, which is what the backend picks when none is sent. */
+    /** Defaults to `"4"`, which is what the server picks when none is sent. */
     readonly scale?: UpscaleScale;
 }
 /** The `upscale` tool, reachable as `oms.tools.upscale`. */

package/dist/types/types.d.ts

@@ -4,7 +4,7 @@
  * Nothing here touches the platform: no `node:*`, no `process`, no `console`.
  * Files are normally values (Blob / Uint8Array / ReadableStream), never paths -
  * the core has no filesystem, and turning a path into a {@link FileInput} is the
- * CLI's job.
+ * host's job.
  *
  * React Native is the one exception, and it is the platform's exception rather
  * than a relaxation of ours: a file the user picked there is a
@@ -31,9 +31,8 @@ export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>
 /**
  * A file picked on React Native, exactly as the platform hands it over.
  *
- * This is the shape `expo-file-system`'s picker returns and the shape the app
- * already builds by hand (`oms-music/src/features/settings/pickers.ts`,
- * `features/playlist/artworkPicker.ts`), and it is a DESCRIPTOR, not bytes: the
+ * This is the shape `expo-file-system`'s picker returns, and it is a
+ * DESCRIPTOR, not bytes: the
  * URI is a `file://`, `content://` or `ph://` handle into the device, and
  * nothing in JavaScript can turn it into a `Blob` without a native module.
  *
@@ -66,10 +65,9 @@ export interface NativeFile {
     /** Filename the server should store. RN sends it as the part's `filename`. */
     readonly name: string;
     /**
-     * MIME type. Pickers report `""` for some `content://` URIs, which is why the
-     * app falls back to a per-kind constant before it gets here; do the same, as
-     * Rails infers the container format from the part's content type for several
-     * of the tools.
+     * MIME type. Pickers report `""` for some `content://` URIs; fall back to a
+     * per-kind constant before it gets here, as the server infers the container
+     * format from the part's content type for several of the tools.
      */
     readonly type?: string;
     /** Byte length when the picker reported one. Ignored by RN, used by the SDK. */
@@ -97,7 +95,7 @@ export declare function isNativeFile(value: unknown): value is NativeFile;
  * multipart form bodies have to be materialised: {@link readFileInput} buffers
  * a stream into a Blob before it can be appended to a `FormData`. For anything
  * large, prefer the storage direct-upload path, which streams straight to the
- * object store and never passes through Rails.
+ * object store.
  *
  * On React Native there is no need to wrap a picked file in one of these at
  * all: pass the picked `{ uri, name, type }` object straight into the form bag
@@ -171,10 +169,8 @@ export declare function file(data: Blob | Uint8Array | ReadableStream<Uint8Array
  *
  * It ticks once per COMPLETED transfer, never per byte, and that is a property
  * of `fetch` rather than a decision this SDK is free to revisit. No `fetch` -
- * browser, React Native or Worker - exposes request-body progress. The web
- * frontend gets a real byte counter in its 36 `onUploadProgress` call sites
- * because axios is XHR underneath, and XHR is the only API that has ever
- * reported bytes as they leave.
+ * browser, React Native or Worker - exposes request-body progress. XHR is the
+ * only API that has ever reported bytes as they leave.
  *
  * There is therefore ONE mechanism in this SDK, not two: `resources/storage/upload.ts`
  * ticks per finished transfer (one per 32 MiB part on the multipart tier, one
@@ -282,17 +278,17 @@ export declare const DEFAULT_RETRY: ResolvedRetry;
 /**
  * One value in a query string.
  *
- * Nested objects and arrays are encoded the way Rails reads them
+ * Nested objects and arrays are encoded the way the API reads them
  * (`search[status]=open`, `ids[]=1&ids[]=2`). Three values do NOT encode
  * literally, and `encodeQuery` in `http.ts` carries the full argument:
  *
  * - `undefined` is dropped. It means "I am not filtering on this column".
- * - `null` is sent as the backend's `\b` null sentinel and comes back out of
- *   `CrudActions` as SQL `NULL`. It means "filter where this column IS NULL".
- *   The two are not interchangeable, and getting them the wrong way round is
- *   the difference between one folder and somebody's entire tree.
- * - a `Date` is sent as its ISO-8601 string, which is the only shape the Rails
- *   date filters parse (`String#to_date_safe`).
+ * - `null` is sent as the API's `\b` null sentinel and is read as SQL `NULL`.
+ *   It means "filter where this column IS NULL". The two are not
+ *   interchangeable, and getting them the wrong way round is the difference
+ *   between one folder and somebody's entire tree.
+ * - a `Date` is sent as its ISO-8601 string, which is the only shape the date
+ *   filters parse.
  */
 export type QueryValue = string | number | boolean | Date | null | undefined | QueryValue[] | {
     [key: string]: QueryValue;
@@ -300,11 +296,10 @@ export type QueryValue = string | number | boolean | Date | null | undefined | Q
 /** A bag of query parameters. */
 export type QueryParams = Record<string, QueryValue>;
 /**
- * Hard ceiling the backend applies to a page size, mirroring
- * `QueryModifier::MAX_PAGE_SIZE`.
+ * Hard ceiling the API applies to a page size.
  *
- * The server clamps silently - `size = [size, MAX_PAGE_SIZE].min` - so asking
- * for 1200 returns 500 rows and no indication that a ceiling was hit. The SDK
+ * The server clamps silently, so asking for 1200 returns 500 rows and no
+ * indication that a ceiling was hit. The SDK
  * therefore clamps to the same number BEFORE the request, so that the size it
  * reports back in {@link Paginated.pageSize} is the size the rows were actually
  * counted against. See {@link resolvePageSize}.
@@ -316,8 +311,7 @@ export declare const MAX_PAGE_SIZE = 500;
  * Deliberately below {@link MAX_PAGE_SIZE}: a `list()` is usually the first
  * screen of something, and 500 rows of expanded records is a slow first paint.
  * Note this is NOT the server's own default - a request with no page modifier
- * at all gets `QueryModifier::DEFAULT_PAGE_SIZE` (500) forced on it by
- * `CrudActions#index_modifiers_params` - but the SDK always sends one.
+ * at all gets 500 - but the SDK always sends one.
  */
 export declare const DEFAULT_PAGE_SIZE = 100;
 /**
@@ -332,11 +326,9 @@ export declare const DEFAULT_PAGE_SIZE = 100;
  *   `hasMore: false`, dropping 700 rows without a word.
  * - **not a usable size at all** (`NaN`, `Infinity`, zero, negative) throws.
  *   There is nothing sensible to clamp such a value to, and it is not merely
- *   wrong on the client: `pageModifier` would put `"1:NaN"` on the wire,
- *   `QueryModifier#apply_pagination` reads that as size `0`, bails out before
- *   `limit`/`offset` are applied, and the endpoint answers with the WHOLE
- *   table. A typo would turn a listing into an unbounded scan holding a Puma
- *   thread and a DB connection.
+ *   wrong on the client: `pageModifier` would put `"1:NaN"` on the wire, the
+ *   server reads that as size `0`, skips pagination, and the endpoint answers
+ *   with the WHOLE table. A typo would turn a listing into an unbounded scan.
  *
  * @throws {TypeError} when `pageSize` is not a finite number of at least 1.
  */
@@ -370,11 +362,10 @@ export interface PageParams {
      * A size the server could not parse is NOT clamped, it throws: `0`, a
      * negative, `NaN` and `Infinity` all raise a `TypeError` before the request
      * is built. This is deliberate and it is not defensive tidiness. `"1:NaN"`
-     * on the wire makes `QueryModifier#apply_pagination` read the size as zero
-     * and bail out before `limit`/`offset` are applied, so the endpoint answers
-     * with the WHOLE table: one typo turns a listing into an unbounded scan
-     * holding a Puma thread and a database connection. Failing at the call site
-     * is the only place that mistake is still cheap.
+     * on the wire is read as size zero and disables pagination, so the endpoint
+     * answers with the WHOLE table: one typo turns a listing into an unbounded
+     * scan. Failing at the call site is the only place that mistake is still
+     * cheap.
      *
      * Narrower than 0.2.0, which clamped `0` to 1 and let `NaN` through onto
      * the wire. See {@link resolvePageSize}.
@@ -459,8 +450,8 @@ export interface QuotaStatus {
 /**
  * How a long-running server-side job reports itself.
  *
- * These are the five strings `Job::STATUSES` holds, spelled exactly as the
- * backend spells them: `"complete"` and `"canceled"`, not `"completed"` and
+ * These are the five strings the API uses, spelled exactly as it spells
+ * them: `"complete"` and `"canceled"`, not `"completed"` and
  * `"cancelled"`. Compare against `JOB_STATUS` / `isJobTerminal` from the jobs
  * namespace rather than against a literal you typed from memory - a wait loop
  * that tests for `"completed"` never ends.

package/package.json

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