@omelhorsite/sdk 0.4.0 → 0.4.1

package/README.md

@@ -39,7 +39,7 @@ const oms = new Oms({
   baseUrl: "http://localhost:3000",  // defaults to https://backend.omelhorsite.pt
   fetch: myFetch,                    // defaults to globalThis.fetch
   headers: { "X-Trace": id },        // merged under per-call headers
-  timeoutMs: 30_000,                 // whole call, retries included; 0 disables
+  timeoutMs: 30_000,                 // per attempt; 0 disables
   retry: { maxAttempts: 3 },         // or false to never retry
   clientName: "my-worker/1.0",       // becomes X-Oms-Client
 });
@@ -186,7 +186,7 @@ const done = await oms.tools.transcription.run(
 `run` is `create` plus `jobs.wait`. Use `create` on hosts with a wall-clock
 budget or nowhere to hold a wait: start the job, keep the id, pick it up later.
 
-Waiting resolves for both `"completed"` and `"failed"`: a failed job is an
+Waiting resolves for both `"complete"` and `"failed"`: a failed job is an
 answer, not a transport error. Check the status before reading the result.
 
 ```ts
@@ -194,8 +194,8 @@ const job = await oms.jobs.wait({ id: started.job_id!, watchToken: started.watch
 if (job.status === "failed") throw new Error(job.error ?? "the job failed");
 ```
 
-A finished tool row says `status: "complete"`; a finished row in the job table
-says `"completed"`; the downloader says `"done"`. Compare against the exported
+A finished job says `status: "complete"`, not `"completed"`, and the
+downloader spells its own terminal state `"done"`. Compare against the exported
 constants, never against a literal.
 
 Check the quota before starting something expensive:

package/dist/index.js

@@ -12835,7 +12835,7 @@ class MusicPlaylistsNamespace extends Resource {
   async reorder(id, songIds, options = {}) {
     const ids = integerIds(songIds, "songIds");
     if (ids.length === 0) {
-      throw new TypeError("reorder needs the complete desired order and refuses an empty array: the backend raises ArgumentError " + "for it, which surfaces as a 500 rather than a 400.");
+      throw new TypeError("reorder needs the complete desired order and refuses an empty array: the server answers 500 for it, " + "not 400.");
     }
     await this.http.post(`/playlists/${encodeURIComponent(String(id))}/reorder`, { song_ids: ids }, options);
   }
@@ -12958,7 +12958,7 @@ function integerIds(ids, field) {
   return ids.map((raw, index) => {
     const value = typeof raw === "string" ? Number(raw) : raw;
     if (typeof value !== "number" || !Number.isInteger(value)) {
-      throw new TypeError(`${field}[${index}] is ${JSON.stringify(raw)}, which is not an integer id. Song ids are integers on this ` + "API, and the backend matches them by identity: a string id matches no row, so the request would " + "succeed and change nothing.");
+      throw new TypeError(`${field}[${index}] is ${JSON.stringify(raw)}, which is not an integer id. Song ids are integers on this ` + "API and are matched by identity: a string id matches no row, so the request would succeed and " + "change nothing.");
     }
     return value;
   });
@@ -13553,7 +13553,7 @@ class CableConnectionImpl {
     const identifier = JSON.stringify(params);
     const registration = { handlers, live: true };
     if (this.subs.has(identifier)) {
-      throw new OmsNetworkError(`Already subscribed to ${identifier}. ActionCable keys subscriptions by identifier, so a second one would shadow the first: reuse the handle, or unsubscribe before resubscribing.`);
+      throw new OmsNetworkError(`Already subscribed to ${identifier}. Subscriptions are keyed by identifier, so a second one would shadow the first: reuse the handle, or unsubscribe before resubscribing.`);
     }
     this.subs.set(identifier, registration);
     if (this.welcomed)
@@ -14861,7 +14861,7 @@ class CaptionsNamespace extends Resource {
   }
   async createChunked(input, options = {}) {
     if (isNativeFile(input.video.data)) {
-      throw new OmsError(`Cannot chunk-upload "${input.video.filename}": it is a React Native file descriptor ` + `(${input.video.data.uri}), and the chunked path has to slice the bytes. Use create() for a file ` + "under Cloudflare's ~100 MB request cap, or read the video into a Uint8Array first " + "(Expo: `new File(uri).bytes()`) and pass that.", "invalid_request");
+      throw new OmsError(`Cannot chunk-upload "${input.video.filename}": it is a React Native file descriptor ` + `(${input.video.data.uri}), and the chunked path has to slice the bytes. Use create() for a file ` + "under the ~100 MB request cap, or read the video into a Uint8Array first " + "(Expo: `new File(uri).bytes()`) and pass that.", "invalid_request");
     }
     const { onProgress, onPart, ...request } = options;
     const { blob } = await readFileInput(input.video);

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

@@ -1,7 +1,7 @@
 /**
  * OAuth 2.0 Device Authorization Grant (RFC 8628).
  *
- * This is how a CLI or an MCP server signs a person in without ever handling
+ * This is how a terminal or a headless client signs a person in without ever handling
  * their password: the client asks for a code, the person opens a URL in a real
  * browser and approves, and the client polls the token endpoint until the
  * approval lands.

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

@@ -36,7 +36,7 @@ export * from "./device";
 export * from "./tokens";
 /** Who the current credential belongs to. */
 export interface WhoAmI {
-    /** `users.id`. The stable identifier; matches the OIDC `sub` claim. */
+    /** The stable user identifier; matches the OIDC `sub` claim. */
     readonly id: string;
     /** Current handle. Mutable - never key anything on it. */
     readonly handle: string;
@@ -107,7 +107,7 @@ export declare class AuthNamespace extends Resource {
     }, options?: RequestOptions): Promise<void>;
     /**
      * Reads the OIDC claims of the current credential from
-     * `GET /oauth/userinfo`. `sub` is `users.id`.
+     * `GET /oauth/userinfo`. `sub` is the user's stable `id`.
      *
      * Needs the `openid` scope; without it the answer is 403. Members whose
      * value is null or empty are omitted from the response, so read defensively.

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

@@ -2,15 +2,15 @@
  * Token providers: where the transport gets a bearer token from.
  *
  * The core has no storage. A provider is either a constant, or a thing the
- * host wired to its own store (the CLI's config file, a Worker KV namespace, a
+ * host wired to its own store (a config file, a Worker KV namespace, a
  * browser's memory). Nothing here reads a file or an environment variable.
  *
  * Two credential shapes exist today and both are just bearer tokens on the
  * wire:
- * - a legacy opaque session token (a UUID minted by `Session`), which never
- *   expires and carries no scopes;
- * - an OAuth 2 / OIDC access token from doorkeeper, which does expire and does
- *   carry scopes, and which comes with a refresh token.
+ * - a legacy opaque session token (a UUID), which never expires and carries no
+ *   scopes;
+ * - an OAuth 2 / OIDC access token, which does expire and does carry scopes,
+ *   and which comes with a refresh token.
  *
  * {@link TokenSet} models the second. The first is just a string.
  *
@@ -23,7 +23,7 @@ import { OmsError } from "../errors";
 import { type ApiClient, type TokenProvider } from "../http";
 import type { RequestOptions } from "../types";
 /**
- * An OAuth 2 token response, as doorkeeper returns it.
+ * An OAuth 2 token response, as the token endpoint returns it.
  *
  * `expiresAt` is absolute epoch milliseconds, not the `expires_in` seconds the
  * server sends, so a stored set stays correct across a restart.
@@ -45,8 +45,8 @@ export interface TokenSet {
 /** Claims the SDK reads out of an OIDC id token. */
 export interface IdentityClaims {
     /**
-     * Stable user identifier: `users.id`. Never the handle and never the email,
-     * both of which the user can change.
+     * Stable user identifier: the user's `id`, as `oms.account.me()` reports it.
+     * Never the handle and never the email, both of which the user can change.
      */
     readonly sub: string;
     readonly iss?: string;
@@ -87,8 +87,8 @@ export declare const DEFAULT_REFRESH_SKEW_MS = 60000;
 /**
  * Wraps a constant token. This is what `new Oms({ token })` builds.
  *
- * Accepts both credential kinds: an opaque session UUID and a doorkeeper
- * access token look identical on the wire.
+ * Accepts both credential kinds: an opaque session UUID and an OAuth access
+ * token look identical on the wire.
  */
 export declare function staticToken(token: string | null): TokenProvider;
 /**
@@ -304,8 +304,8 @@ export declare class OmsOAuthError extends OmsError {
  * Recognises an OAuth error inside whatever the transport threw.
  *
  * Deliberately narrow: only 400 and 401 bodies are read as OAuth errors. A 429
- * comes from rack-attack with the body `{"error":"rate_limited"}`, and that
- * `error` key is NOT an OAuth code - reading it as one abandons a perfectly
+ * carries the body `{"error":"rate_limited"}`, and that `error` key is NOT an
+ * OAuth code - reading it as one abandons a perfectly
  * live device flow. It stays an {@link OmsQuotaError} and the caller handles
  * it as a rate limit.
  *
@@ -316,8 +316,8 @@ export declare function oauthErrorFrom(thrown: unknown): OmsOAuthError | undefin
 export interface InsufficientScope {
     /**
      * The scopes the endpoint needed. EMPTY when the server named none, which
-     * means the endpoint has not been opened to OAuth clients at all - a backend
-     * gap, not a client bug. The two cases must read differently to the user.
+     * means the endpoint accepts no OAuth token at all - a server-side gap, not
+     * a client bug. The two cases must read differently to the user.
      */
     readonly required: string[];
     /** The `realm` parameter, when present. */
@@ -342,7 +342,7 @@ export declare function readInsufficientScope(error: unknown): InsufficientScope
  *
  * The OAuth endpoints do not take JSON, which is why this exists next to
  * `ApiClient.post` rather than using it. Blank values are dropped rather than
- * sent empty, because doorkeeper reads `""` as a present-but-invalid parameter.
+ * sent empty, because the server reads `""` as a present-but-invalid parameter.
  *
  * Retries are OFF and stay off. Replaying `POST /oauth/token` after a lost
  * response is not safe: the server may have rotated the refresh token already,

package/dist/types/client.d.ts

@@ -41,7 +41,7 @@ import type { FetchLike, RetryOptions } from "./types";
  * Anything accepted as a credential by {@link Oms}.
  *
  * A bare string is either kind of bearer token the API takes: a legacy opaque
- * `Session` UUID or an OAuth access token. A function is called on every
+ * session UUID or an OAuth access token. A function is called on every
  * request. A {@link TokenProvider} additionally gets a chance to refresh on a
  * 401 - see `auth/tokens.ts`.
  */
@@ -66,7 +66,7 @@ export interface OmsOptions {
      * by name.
      *
      * ```ts
-     * // in the omelhorsite web app, served from the same site as the API
+     * // on a first-party page, served from the same site as the API
      * const oms = new Oms({ sessionCookie: true });
      * ```
      */
@@ -75,13 +75,13 @@ export interface OmsOptions {
     readonly baseUrl?: string;
     /**
      * The fetch to talk through. Defaults to `globalThis.fetch`. Injecting one is
-     * how a Worker adds a cache, how a test swaps in a double, and how the CLI
+     * how a Worker adds a cache, how a test swaps in a double, and how a host
      * adds a proxy - the SDK never patches a global.
      */
     readonly fetch?: FetchLike;
     /** Headers merged into every request, below per-call headers. */
     readonly headers?: Record<string, string>;
-    /** Default deadline for one call including its retries. `0` disables it. */
+    /** Default deadline for one attempt; a retry gets a fresh one. `0` disables it. */
     readonly timeoutMs?: number;
     /** Default backoff policy, or `false` to never retry. */
     readonly retry?: RetryOptions | false;
@@ -103,10 +103,10 @@ export interface OmsOptions {
  *
  * ## Two credentials, two namespaces
  *
- * `oms.sessions` mints the opaque `Session` token the website and the mobile
- * apps use, which carries the whole account. `oms.auth` runs OAuth, whose
- * tokens are scoped and, because `enforce_oauth_scope!` denies by omission,
- * cannot reach most of the API at all. `oms.realtime` accepts only the first
+ * `oms.sessions` mints the opaque session token, which carries the whole
+ * account. `oms.auth` runs OAuth, whose tokens are scoped and, because an
+ * endpoint with no declared scope refuses every OAuth token, cannot reach most
+ * of the API at all. `oms.realtime` accepts only the first
  * kind. Picking the wrong one shows up as a `403 insufficient_scope`, or on the
  * cable as a connection that is silently anonymous.
  *
@@ -178,9 +178,9 @@ export declare class Oms {
     /** OAuth client registration for anyone, plus the `/admin/*` routes. */
     readonly admin: AdminNamespace;
     /**
-     * The ActionCable connection: playback handoff, jams, notifications, job
+     * The WebSocket connection: playback handoff, jams, notifications, job
      * progress. Opens nothing until {@link RealtimeNamespace.connect} is called,
-     * and wants a `Session` token rather than the client's own credential - see
+     * and wants a session token rather than the client's own credential - see
      * that method for why.
      */
     readonly realtime: RealtimeNamespace;

package/dist/types/errors.d.ts

@@ -8,15 +8,15 @@
  * The API answers with at least four different error body shapes, so anything
  * that reads an error body must go through {@link normalizeErrorBody}:
  *
- * - a bare JSON string:            `"Image too large"`            (ResponseHelpers)
- * - a sentence from ActiveModel:   `"Name can't be blank and ..."` (error_messages)
+ * - a bare JSON string:            `"Image too large"`
+ * - a validation sentence:         `"Name can't be blank and ..."`
  * - an object with `error`:        `{"error":"rate_limited","retry_after":37}`
  * - an object of field errors:     `{"errors":{"url":["is invalid"]}}`
  * - plain text / HTML:             short-link 404 pages, proxy errors
  */
 /** Machine-readable code carried by every SDK error. */
 export type OmsErrorCode = "api_error" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "invalid_request" | "quota_exceeded" | "rate_limited" | "server_error" | "timeout" | "aborted" | "network" | "unsupported" | "unknown";
-/** Extra context attached to an error, useful for logs and for the CLI. */
+/** Extra context attached to an error, useful for logs. */
 export interface OmsErrorContext {
     /** HTTP method of the failing request, when there was one. */
     readonly method?: string;
@@ -38,9 +38,9 @@ export declare class OmsError extends Error {
      * This class's own name, as a LITERAL.
      *
      * `this.name = new.target.name` would be the obvious way to do this and it
-     * is wrong here: `bun build --minify` renames the classes, so the shipped
-     * `oms` binary reported `name: "A"` in its JSON error envelope while a dev
-     * run reported `OmsNetworkError`. A minifier renames identifiers, never
+     * is wrong here: `bun build --minify` renames the classes, so a minified
+     * build reported `name: "A"` in its JSON error envelope while a dev run
+     * reported `OmsNetworkError`. A minifier renames identifiers, never
      * string literals or property names, so a static literal survives the build.
      *
      * Every subclass shadows this, and `new.target` is the constructor that was
@@ -95,9 +95,6 @@ export declare class OmsApiError extends OmsError {
 }
 /**
  * 401 or 403: the credential is missing, expired, or not allowed to do this.
- *
- * The CLI turns this into "run `oms auth login`"; the MCP server turns it into
- * a device-flow prompt.
  */
 export declare class OmsAuthError extends OmsApiError {
     static readonly errorName: string;
@@ -107,10 +104,10 @@ export declare class OmsAuthError extends OmsApiError {
 /**
  * 429, or a documented daily-quota rejection.
  *
- * Two different producers land here and they do not look alike:
- * rack-attack answers `{"error":"rate_limited","retry_after":37}` with a
- * `Retry-After` header, while a controller quota gate answers a bare string
- * such as `"Daily edit quota reached (5/day)"` with no header at all. Read
+ * Two different producers land here and they do not look alike: a rate limit
+ * answers `{"error":"rate_limited","retry_after":37}` with a `Retry-After`
+ * header, while a daily quota answers a bare string such as
+ * `"Daily edit quota reached (5/day)"` with no header at all. Read
  * {@link retryAfterMs}; it is `undefined` in the second case.
  */
 export declare class OmsQuotaError extends OmsApiError {
@@ -160,7 +157,7 @@ export interface NormalizedError {
     readonly message: string;
     /** A code the server named itself (`{"error":"rate_limited"}`), if any. */
     readonly serverCode: string | undefined;
-    /** Per-field messages, when the body was shaped like ActiveModel errors. */
+    /** Per-field messages, when the body was a field-to-messages map. */
     readonly fieldErrors: Record<string, string[]> | undefined;
 }
 /**
@@ -179,7 +176,7 @@ export interface NormalizedError {
 export declare function normalizeErrorBody(body: unknown, fallback?: string): NormalizedError;
 /**
  * Reads a `Retry-After` header. RFC 9110 allows both delay-seconds and an
- * HTTP-date; rack-attack sends seconds, but a proxy in front may not.
+ * HTTP-date; the API sends seconds, but a proxy in front may not.
  *
  * @returns Milliseconds to wait, or `undefined` when the header is absent or junk.
  */