@omelhorsite/sdk 0.3.0 → 0.4.1

package/README.md

@@ -1,7 +1,6 @@
 # `@omelhorsite/sdk`
 
-The TypeScript client for the omelhorsite API. The CLI and the MCP server are
-clients of this package, not the other way round.
+The TypeScript client for the omelhorsite API.
 
 ```ts
 import { Oms } from "@omelhorsite/sdk";
@@ -12,33 +11,23 @@ const me = await oms.auth.whoami();
 const link = await oms.shortLinks.create({ url: "https://example.com" });
 ```
 
-## Three rules that shape every signature
-
-**1. It runs in a Cloudflare-Worker-class isolate.** No `node:*`, no `process`,
-no filesystem, no `console`. Only platform APIs: `fetch`, Web Streams,
-WebCrypto, `Blob`, `FormData`, `AbortController`. This is enforced at compile
-time - `src/isolate-guard.d.ts` declares a poisoned `process`, so reaching for
-one is a type error, not a runtime surprise in production.
-
-**2. Files are values, never paths.** `Blob`, `Uint8Array`, `ReadableStream` in;
-`Blob` out. Turning a path into bytes is the host's job, because the isolate has
-no path to turn.
-
-**3. The types are the public interface.** Everything is re-exported flat from
-the package root; there is no deep import into `src/`. In code mode a model
-reads the `.d.ts` and nothing else, so the JSDoc carries the rate limits, the
-quota units and the places the backend surprises you.
+```sh
+bun add @omelhorsite/sdk
+```
 
-## Installing
+## What shapes every signature
 
-Today it is a workspace dependency:
+**It runs anywhere `fetch` runs.** Browsers, Bun, Node 18+, React Native and
+Cloudflare-Worker-class isolates. Nothing in the package touches `node:*`,
+`process`, the filesystem or `console`; `fetch` is injectable.
 
-```json
-{ "dependencies": { "@omelhorsite/sdk": "workspace:*" } }
-```
+**Files are values, never paths.** `Blob`, `Uint8Array` or `ReadableStream`
+in; `Blob` out. On React Native a picked `{ uri, name, type }` is accepted as
+it is and streamed by the platform.
 
-It ships as TypeScript source, no build step. Bun and any bundler resolve it
-directly. Nothing is published to a registry yet.
+**The types are the documentation.** Everything is exported flat from the
+package root, and the JSDoc on each method carries the rate limits, quota
+units and traps of the endpoint behind it.
 
 ## Constructing a client
 
@@ -50,22 +39,22 @@ 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
 });
 ```
 
 Constructing does no I/O. `oms.withToken(other)` returns a copy under a
-different identity rather than mutating one, so an in-flight request can never
-finish under the wrong credential.
+different identity rather than mutating one.
 
 Omitting the token is legitimate: short links, notepads, chests, IP lookup and
-the captcha-gated tools all work anonymously, at a smaller daily quota.
+the captcha-gated tools all work anonymously, at a smaller daily quota. A
+browser on the API's own site can use the session cookie instead with
+`new Oms({ sessionCookie: true })`.
 
-**Injecting `fetch` is the extension point.** A Worker that wants a cache, a
-test that wants a double, a host that wants a proxy - none of them patch a
-global:
+**Injecting `fetch` is the extension point.** A cache, a test double, a proxy:
+none of them patch a global.
 
 ```ts
 const oms = new Oms({
@@ -74,8 +63,7 @@ const oms = new Oms({
 });
 ```
 
-An endpoint the SDK has not wrapped yet is still reachable, which beats forking
-the package to add one call:
+An endpoint the SDK has not wrapped yet is still reachable:
 
 ```ts
 const rows = await oms.http.get<{ id: string }[]>("/some/new/path");
@@ -85,22 +73,62 @@ const rows = await oms.http.get<{ id: string }[]>("/some/new/path");
 
 | | |
 | --- | --- |
-| `oms.auth` | Device grant, refresh, revoke, `whoami`, `userinfo`. |
-| `oms.account` | The signed-in user, their profile, their usage report. |
+| `oms.auth` | OAuth: device grant, refresh, revoke, `whoami`, `userinfo`. |
+| `oms.sessions` `oms.passkeys` | Session sign-in, sign-up, OTP, passkeys. |
+| `oms.account` | The signed-in user, their profile, sessions and usage. |
 | `oms.storage` | The virtual filesystem: nodes, uploads, downloads, grants. |
+| `oms.media` | Resolving stored media to URLs. |
+| `oms.music` | Songs, artists, playlists, imports, likes, jams, the social feed. |
+| `oms.movies` | Addons, collections, watch progress. |
+| `oms.library` | Books, shelves, annotations, the study assistant. |
+| `oms.social` | Direct messages, relationships, group chats. |
+| `oms.content` | Blogs, notifications, feedbacks, jokes, site status, intel. |
 | `oms.tools` | The metered media tools, each with its own daily quota. |
-| `oms.quotas` | Every ceiling on the account - tools, storage and music - in one call. |
-| `oms.jobs` | Background jobs: list, get, wait, watch. The API has no cancel. |
+| `oms.jobs` | Background jobs: list, get, wait, watch. |
+| `oms.quotas` | Every ceiling on the account in one call. |
 | `oms.tickets` | Support tickets and their message threads. |
 | `oms.shortLinks` `oms.notepads` `oms.dynamicQrs` `oms.chests` `oms.forms` `oms.linkTrees` | Everything that ends in a shareable URL. |
 | `oms.ipLookup` | Geolocation and network metadata for an IP. |
+| `oms.admin` | Administrator-only views and actions. |
+| `oms.realtime` | The WebSocket channel: notifications, jobs, jams. |
 | `oms.local` | Pure client-side helpers. No network, no credential. |
 
+## Listing and filtering
+
+Every `list()` takes the same query language, typed per resource:
+
+```ts
+const page = await oms.library.books.list({
+  search: { title: "maias" },            // partial, accent-insensitive
+  exactSearch: { format: "epub" },       // equality; an array is IN, null is IS NULL
+  extraOptions: { scope: "mine" },       // endpoint-specific, only where declared
+  order: "created_at:desc",              // "column:asc" | "column:desc"
+  page: 2,
+  pageSize: 50,                          // capped at 500 by the server
+});
+```
+
+The columns each resource accepts are string-literal unions, so a key the
+server would reject with `400` is a compile error instead. Most resources also
+offer camelCased shortcuts (`userId`, `withUser`, `ownerHandle`) that write
+into the same buckets.
+
+The result is a `Paginated<T>`: `items`, `page`, `pageSize`, `hasMore` and
+`next()`. Two helpers walk it:
+
+```ts
+import { collect, pages } from "@omelhorsite/sdk";
+
+const all = await collect(page, 5000);           // flatten, up to a limit
+for await (const p of pages(page)) { ... }       // or one page at a time
+```
+
+Always pass a limit to `collect`; a listing can be very long.
+
 ## Files
 
-A `FileInput` always carries a filename, because the API derives the stored name
-and, for the media tools, the container format from it. The `file()` helper
-exists so that requirement stays visible at the call site:
+A `FileInput` always carries a filename, because the API derives the stored
+name and, for the media tools, the container format from it:
 
 ```ts
 import { file } from "@omelhorsite/sdk";
@@ -110,22 +138,21 @@ const bytes = file(new Uint8Array(buffer), "dump.sql", { contentType: "applicati
 const streamed = file(response.body!, "big.mov", { size: contentLength });
 ```
 
-Pass `size` when you know it: it lets `storage.upload` pick the multipart path
-(anything from 32 MiB up) without buffering the stream to measure it. A stream
-without a size gets buffered, which for a 2 GB file is not what you want.
+Pass `size` when you know it: it lets `storage.upload` choose the multipart
+path (32 MiB and up) without buffering the stream to measure it.
 
 Downloads come back as a `Blob`, or as a `FileOutput` when the server's
 filename and content type matter:
 
 ```ts
-const out = await oms.storage.download(nodeId);   // { data, filename, contentType, size }
-const { stream } = await oms.storage.downloadStream(nodeId);  // for large files
+const out = await oms.storage.download(nodeId);
+const { stream } = await oms.storage.downloadStream(nodeId);
 ```
 
 ## Uploading to storage
 
-Bytes never pass through Rails. `upload` mints a plan, sends the bytes straight
-to object storage with a presigned URL, and binds the blob at the end.
+Bytes go straight to object storage through a presigned URL and are bound to
+the node at the end.
 
 ```ts
 const roots = await oms.storage.roots();
@@ -136,66 +163,30 @@ const nodes = await oms.storage.upload(
 );
 ```
 
-Progress arrives per finished file or part, never per byte: `fetch` has no
-upload-progress event, and faking one would be a lie. A file rejected on its own
-(quota, name collision) does not throw - it is simply missing from the returned
-array, so compare lengths when partial success matters.
-
-## Pagination
-
-Every listing returns a `Paginated<T>` with a `load` function, and two helpers
-consume it:
-
-```ts
-import { collect, pages } from "@omelhorsite/sdk";
-
-const first = await oms.storage.list({ parentId, pageSize: 500 });
-
-const all = await collect(first, 5000);          // flatten, up to a limit
-for await (const page of pages(first)) { ... }   // or one page at a time
-```
-
-Always pass a limit to `collect`. A directory with 300k nodes is a real thing
-that has happened here.
+Progress arrives per finished file or part, never per byte. A file rejected on
+its own (quota, name collision) does not throw; it is missing from the
+returned array, so compare lengths when partial success matters.
 
 ## Long jobs: `create` / `get`, and `run`
 
-Every metered tool is asynchronous. The server enqueues work and answers
-immediately with a row in `"pending"`, plus a `job_id` and - for an anonymous
-caller - a `watch_token` scoped to that one job.
-
-So every tool namespace has the same three-part shape:
+Every metered tool is asynchronous: the server enqueues the work and answers
+with a row in `"pending"`, plus a `job_id` and, for an anonymous caller, a
+`watch_token` scoped to that one job.
 
 ```ts
-// start: returns as soon as the work is enqueued
 const started = await oms.tools.transcription.create({ audio, language: "pt" });
-
-// poll: one request, no waiting
 const now = await oms.tools.transcription.get(started.id);
 
-// or let the SDK poll for you
 const done = await oms.tools.transcription.run(
   { audio, language: "pt" },
   { onProgress: (p) => report(p.status), waitTimeoutMs: 15 * 60_000 },
 );
 ```
 
-`run` is `create` plus `jobs.wait`, and it is the right call in a script or at a
-terminal. **The split exists because in half the places this SDK is meant to
-run, `run` is unusable:**
-
-- **A Worker has a wall-clock budget.** Holding a poll loop open for a
-  five-minute transcription burns the invocation and then dies without the
-  result. Start the job, return the id, and pick it up on the next request.
-- **A request/response host has nowhere to put the wait.** An HTTP handler, an
-  MCP tool call and a queue consumer all want to hand back an id now and answer
-  later. That is what `oms tools ... --no-wait` and `oms tools status` are built
-  on.
-- **The polling policy belongs in one place.** `jobs.wait` starts at
-  `pollIntervalMs`, backs off towards a ceiling, honours the caller's `signal`,
-  and gives up at `waitTimeoutMs`. No tool module opens a second loop.
-
-Waiting resolves for **both** `"completed"` and `"failed"`: a failed job is an
+`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 `"complete"` and `"failed"`: a failed job is an
 answer, not a transport error. Check the status before reading the result.
 
 ```ts
@@ -203,13 +194,11 @@ 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 trap worth naming once.** A finished tool row says `status: "complete"`. A
-finished row in the generic job table says `"completed"`. The downloader's
-sidecar says `"done"`. Three spellings of one idea, in three different tables.
-Compare against the constants, never against a literal you typed from memory.
+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. The unit differs per tool -
-seconds of media for the audio and video tools, edits for jumpstyle:
+Check the quota before starting something expensive:
 
 ```ts
 const quota = await oms.tools.transcription.quota();
@@ -218,7 +207,7 @@ if (!quota.unlimited && (quota.remaining_seconds ?? 0) < 60) return;
 
 ## Errors
 
-Every failure is an `OmsError` subclass carrying the context needed to decide
+Every failure is an `OmsError` subclass carrying what is needed to decide
 between retrying, re-scoping and giving up.
 
 ```ts
@@ -230,7 +219,7 @@ try {
   if (thrown instanceof OmsQuotaError) return retryAfter(thrown.retryAfterMs);
 
   const missing = readInsufficientScope(thrown);
-  if (missing) return askForScopes(missing.scope);   // 403 with a scope requirement
+  if (missing) return askForScopes(missing.scope);
 
   if (thrown instanceof OmsAuthError) return signInAgain();
   if (thrown instanceof OmsApiError) log(thrown.status, thrown.fieldErrors);
@@ -240,49 +229,48 @@ try {
 
 `OmsNetworkError` means the API was never reached; `OmsTimeoutError` with
 `code === "aborted"` means your own `signal` fired. Retries are on by default
-for idempotent requests with backoff and jitter. **Pass `retry: false` to any
-create you would rather see fail than duplicate** - a replayed short link mints
-a second one under a different endpoint.
+for idempotent requests, with backoff and jitter. Pass `retry: false` to any
+create you would rather see fail than duplicate.
 
-## Auth
+## OAuth
 
-The device grant, in full. Note which calls carry a credential and which must
-not: `/oauth/token` authenticates with `client_id` in the form body and a
-stray `Authorization` header breaks it.
+The device grant, in full. `/oauth/token` authenticates with `client_id` in
+the form body; a stray `Authorization` header breaks it, so start from a
+client with no token.
 
 ```ts
 import { Oms, OAuthTokenProvider, decodeIdToken } from "@omelhorsite/sdk";
 
-const anon = new Oms({ baseUrl, fetch });            // NO token
+const anon = new Oms({ baseUrl, fetch });
 
-const grant = await anon.auth.device.start({ clientId: "oms-cli", scope: "openid storage:read" });
+const grant = await anon.auth.device.start({ clientId, scope: "openid storage:read" });
 show(grant.verificationUriComplete ?? grant.verificationUri, grant.userCode);
 
 const set = await anon.auth.device.wait({
-  clientId: "oms-cli",
+  clientId,
   deviceCode: grant.deviceCode,
   intervalMs: grant.intervalMs,
   expiresAt: grant.expiresAt,
 });
 
 const tokens = new OAuthTokenProvider({
-  store: myTokenStore,                                // yours: the SDK writes no files
-  refresh: (refreshToken) => anon.auth.refresh(refreshToken, { clientId: "oms-cli" }),
+  store: myTokenStore,
+  refresh: (refreshToken) => anon.auth.refresh(refreshToken, { clientId }),
 });
 await tokens.set(set);
 
 const oms = new Oms({ baseUrl, fetch, tokens });     // refreshes itself on a 401
 ```
 
-`decodeIdToken(set.idToken)` reads the claims. **`sub` is `users.id`** - stable,
-and the only identifier safe to key on. The handle and the email are mutable.
+`decodeIdToken(set.idToken)` reads the claims. `sub` is the user id, stable
+and the only identifier safe to key on; the handle and the email are mutable.
 
-Access tokens live two hours. `OMS_SCOPES` is the full list the server defines;
-ask for the narrowest set that does the job.
+Access tokens live two hours. `OMS_SCOPES` is the full list the server
+defines; ask for the narrowest set that does the job.
 
 ## Local helpers
 
-No network, no credential, importable on their own:
+No network, no credential:
 
 ```ts
 import { generatePassphrase, generatePassword, passwordStrength, qrToSvg } from "@omelhorsite/sdk";
@@ -294,29 +282,23 @@ const svg = qrToSvg("https://example.com");
 
 ## Testing against it
 
-Inject a fetch. There is no global to stub and no network to mock at a lower
-level:
+Inject a fetch. There is no global to stub:
 
 ```ts
 const oms = new Oms({
   token: "test",
-  fetch: async (url, init) => new Response(JSON.stringify({ id: "1" }), {
+  fetch: async () => new Response(JSON.stringify({ id: "1" }), {
     status: 200,
     headers: { "content-type": "application/json" },
   }),
 });
 ```
 
+## Developing
+
 ```sh
 bun test
 bun run typecheck
+bun run check:isolate
+bun run build
 ```
-
-**After any change to `src/`, regenerate the MCP server's type catalogue:**
-
-```sh
-bun run --filter '@omelhorsite/mcp' build:types
-```
-
-The MCP server serves these declarations to models as its entire interface. A
-stale catalogue means the model is reading a signature that no longer exists.