@gemmein/sdk 0.8.0 → 0.10.0

package/dist/index.js

@@ -4,13 +4,83 @@
  *  second module). `scripts/sync-version.mjs` rewrites the literal from
  *  package.json before every build (`prebuild`), and a test pins the two
  *  equal, so a bump can never ship with a stale header. */
-export const SDK_VERSION = "0.8.0"; // synced from package.json — do not edit by hand
+export const SDK_VERSION = "0.10.0"; // synced from package.json — do not edit by hand
 /** W9.1 / CLIENT-INFO-1: every request the SDK makes to Gemmein carries
  *  `x-client-info: gemmein-sdk/<version>`. The server records it on the
  *  secret-key usage ledger ("last seen from gemmein-sdk/0.5.0"), so a
  *  misbehaving integration can be attributed to an SDK version from day
  *  one. It is a report, not a proof — any caller can set it. */
 export const CLIENT_INFO = `gemmein-sdk/${SDK_VERSION}`;
+/** W10 §1 A: a mobile entry adds its platform — `gemmein-sdk/<version>
+ *  expo-ios`. The ledger that records this header caps it at 64 characters
+ *  and strips control characters (`MAX_CLIENT_LENGTH` / `capClient`,
+ *  packages/db/src/keyUsageStore.ts), so the value is cleaned and capped
+ *  HERE: a tag that arrives truncated attributes nothing. Anything outside
+ *  `[A-Za-z0-9._/-]` collapses to a hyphen, so the label can never carry a
+ *  newline — or a second space — into the ledger. */
+export function clientInfoFor(platform) {
+    if (typeof platform !== "string")
+        return CLIENT_INFO;
+    const clean = platform.replace(/[^A-Za-z0-9._/-]+/g, "-").replace(/^-+|-+$/g, "");
+    if (clean.length === 0)
+        return CLIENT_INFO;
+    return `${CLIENT_INFO} ${clean}`.slice(0, 64);
+}
+/** W10 §1 A: every request goes through ONE function, so a platform that
+ *  needs its own fetch injects it once. The default reads `globalThis.fetch`
+ *  at call time (a polyfill installed later still counts), and both forms
+ *  are invoked as plain calls — which is what keeps a browser's
+ *  `window.fetch` legal when it is handed over as a bare reference.
+ *
+ *  W10 row 9, found by driving the Expo app with the engine stopped: a
+ *  transport failure — connection refused, no DNS, no Wi-Fi, an `apiUrl`
+ *  pointing at nothing — never reaches `handleResponse`, so whatever the
+ *  fetch implementation threw came out unchanged (a `TypeError` in a
+ *  browser and on Expo's fetch). An app branching on `err.code`, which is
+ *  what every teaching tells it to do, got `undefined` there and nowhere
+ *  else. EVERY request the client makes — the runtime clients, a
+ *  collection, the S3 upload POST, both AI streams — goes through this one
+ *  wrapper, so every one of them now answers a `GemmeinError`
+ *  `network_unreachable` (status 0, the SDK's convention for "no HTTP
+ *  status applies"), with the fetch's own error kept on `err.cause`.
+ *
+ *  Two throws pass through untouched: an `AbortError` — the caller
+ *  cancelled on purpose, and `{ signal }` is a documented option on the AI
+ *  calls — and a `GemmeinError` an injected fetch raised itself. */
+function resolveFetch(injected, apiUrl) {
+    const call = injected
+        ? (input, init) => injected(input, init)
+        : (input, init) => globalThis.fetch(input, init);
+    // The host is read ONCE, here, and only for the sentence: a client whose
+    // `apiUrl` is unparseable still gets a readable error, never a second throw.
+    const host = (() => {
+        try {
+            return new URL(apiUrl).host;
+        }
+        catch {
+            return apiUrl;
+        }
+    })();
+    return (async (input, init) => {
+        try {
+            return await call(input, init);
+        }
+        catch (cause) {
+            // The caller's own cancel, and an SDK refusal an injected fetch chose
+            // to raise, are both already typed — re-typing them would lie.
+            if (cause instanceof GemmeinError)
+                throw cause;
+            if (typeof cause === "object" && cause !== null && cause.name === "AbortError")
+                throw cause;
+            throw new GemmeinError({
+                status: 0,
+                code: "network_unreachable",
+                message: `Gemmein could not be reached — check the connection and the apiUrl (${host})`,
+                cause,
+            });
+        }
+    });
+}
 export class GemmeinError extends Error {
     constructor(input) {
         super(input.message);
@@ -19,6 +89,7 @@ export class GemmeinError extends Error {
         this.code = input.code;
         this.resetAt = input.resetAt;
         this.requires = input.requires;
+        this.cause = input.cause;
     }
 }
 export class MemoryTokenStore {
@@ -35,8 +106,15 @@ export class MemoryTokenStore {
 // Persists the session across page reloads — the default in browsers.
 // Sessions are long-lived server-side; a memory-only default would log
 // users out on every refresh. Keyed per app key so two Gemmein apps on
-// one origin never share a token. All storage access is guarded: private
-// modes and blocked storage degrade to "signed out", never to a crash.
+// one origin never share a token.
+//
+// READS AND CLEARS ARE LENIENT, WRITES ARE NOT — the same law the two
+// mobile stores keep (`SecureStoreTokenStore` in `@gemmein/sdk/expo`,
+// `KeychainTokenStore` in GemmeinSwift). A store that cannot be READ means
+// signed out, which every app already handles; a store that cannot KEEP
+// the session has broken the promise it exists for, and silence there
+// signs the person out on the next reload with nothing anywhere saying
+// why.
 export class BrowserTokenStore {
     constructor(appKey) {
         this.key = `gemmein_session_${appKey.slice(0, 20)}`;
@@ -49,11 +127,30 @@ export class BrowserTokenStore {
             return undefined;
         }
     }
+    /**
+     * A blocked `localStorage` — Safari's private mode past its quota, a
+     * browser set to block site data, a sandboxed iframe whose access throws
+     * — throws `secure_store_unavailable` (status 0), the same code the
+     * mobile stores answer, with the browser's own error on `cause`.
+     * `auth.verifyEmailCode()` carries it to the caller: the session is real
+     * (the server minted it), so an app that would rather run than stop
+     * catches this one code and rebuilds its client with a
+     * `MemoryTokenStore`, which never throws.
+     */
     set(token) {
         try {
             window.localStorage.setItem(this.key, token);
         }
-        catch { /* storage blocked — session lives for this page only */ }
+        catch (cause) {
+            const detail = cause instanceof Error ? cause.message : String(cause);
+            throw new GemmeinError({
+                status: 0,
+                code: "secure_store_unavailable",
+                message: `The session could not be stored: this browser refused the localStorage write (${detail}) ` +
+                    "— pass a tokenStore, e.g. new MemoryTokenStore()",
+                cause,
+            });
+        }
     }
     clear() {
         try {
@@ -104,10 +201,14 @@ export class Gemmein {
                     'copy the key from the Setup page. Then: gemmein("pk_...")'
             });
         }
+        const apiUrl = options.apiUrl ?? "https://api.gemmein.com";
         const config = {
-            apiUrl: options.apiUrl ?? "https://api.gemmein.com",
+            apiUrl,
             appKey: options.appKey,
-            tokenStore: options.tokenStore ?? defaultTokenStore(options.appKey)
+            tokenStore: options.tokenStore ?? defaultTokenStore(options.appKey),
+            fetch: resolveFetch(options.fetch, apiUrl),
+            visibility: options.visibility,
+            clientInfo: clientInfoFor(options.platform)
         };
         this.auth = new AuthClient(config);
         this.storage = new StorageClient(config);
@@ -129,6 +230,7 @@ export class Gemmein {
      * suggestion attached — always pass it when you aren't certain the
      * collection exists yet. The cloud ignores it.
      */
+    // route: none
     collection(name, options = {}) {
         return this.storage.collection(name, options);
     }
@@ -153,6 +255,7 @@ export class AuthClient {
     constructor(config) {
         this.config = config;
     }
+    // route: POST /auth/email/start
     async sendEmailCode(email) {
         await this.request("/auth/email/start", {
             method: "POST",
@@ -160,6 +263,7 @@ export class AuthClient {
             headers: { "content-type": "application/json" }
         });
     }
+    // route: POST /auth/email/verify
     async verifyEmailCode(input) {
         const result = await this.request("/auth/email/verify", {
             method: "POST",
@@ -180,15 +284,33 @@ export class AuthClient {
             message: "Gemmein auth response did not include a session token"
         });
     }
+    /**
+     * End this device's session. IDEMPOTENT: signing out of a session that is
+     * already gone is the outcome asked for, not a failure.
+     *
+     * W10 row 9, found by driving the Expo app: the commonest way this
+     * round-trip fails is `401 auth_expired` — the owner already signed this
+     * person out everywhere from the console, which is the remedy for a
+     * stolen phone. The session IS ended; throwing there made an app that did
+     * everything right show an error for the thing it asked for. Every other
+     * failure still throws, and the token store is cleared either way.
+     */
+    // route: POST /auth/logout
     async logout() {
         try {
             await this.request("/auth/logout", { method: "POST" });
         }
+        catch (err) {
+            const alreadyEnded = err instanceof GemmeinError && err.status === 401 && err.code === "auth_expired";
+            if (!alreadyEnded)
+                throw err;
+        }
         finally {
             // Even if the network call fails, the user asked to be signed out.
             await this.config.tokenStore.clear();
         }
     }
+    // route: GET /auth/current-user
     async currentUser() {
         // Contract: "who am I?" never throws for session state — the server
         // answers 200 {authenticated:false} for a token it won't honour right
@@ -245,6 +367,7 @@ export class PurchasesClient {
      * or `{ type: "external_url", url }` (a plain handover). A refunded
      * purchase never carries delivery.
      */
+    // route: GET /auth/purchases
     async mine() {
         const result = (await runtimeRequest(this.config, "/auth/purchases"));
         return result.purchases;
@@ -276,6 +399,7 @@ export class FilesClient {
     constructor(config) {
         this.config = config;
     }
+    // route: GET /files/{ref}/link
     async link(ref, options = {}) {
         const query = options.intent === "download" ? "?intent=download" : "";
         return (await runtimeRequest(this.config, `/files/${encodeURIComponent(String(ref))}/link${query}`));
@@ -292,6 +416,7 @@ export class SubscriptionsClient {
      * nobody is signed in — a data route, not the never-throw current-user
      * contract.
      */
+    // route: GET /auth/subscription
     async mine() {
         const result = (await runtimeRequest(this.config, "/auth/subscription"));
         return result.subscription;
@@ -305,6 +430,7 @@ export class SubscriptionsClient {
      * and a plan whose Payment Link the app owner has pasted in their
      * dashboard; omit `plan` to buy the app's paid plan.
      */
+    // route: GET /auth/checkout
     async checkout(plan) {
         const query = plan ? `?plan=${encodeURIComponent(plan)}` : "";
         const result = (await runtimeRequest(this.config, `/auth/checkout${query}`));
@@ -325,10 +451,16 @@ export class PaymentsClient {
      * WHAT is being bought when one product covers many things (e.g. a
      * license tier across a catalog):
      * `g.payments.buy("premium license", { item: "beat_37" })`.
-     * A completed payment writes a receipt record addressed to the buyer in
-     * the owner's receipts collection; gate downloads/fulfilment on that
-     * receipt, never on the redirect coming back.
+     * Gemmein records every completed payment itself: `g.purchases.mine()` is
+     * the buyer's proof, and a product that delivers a file carries
+     * `delivery` on it. Gate fulfilment on the purchase (or the entitlement it
+     * granted), never on the redirect coming back. A receipts collection is
+     * optional, for proof records only.
+     *
+     * A product sold via a RELAY, or not sold yet, has no Payment Link to
+     * open: this answers 409 `product_not_sellable`.
      */
+    // route: GET /auth/pay
     async buy(product, options) {
         const params = new URLSearchParams({ product });
         if (options?.item)
@@ -353,6 +485,7 @@ export class AccountClient {
      * subscription row removed. Irreversible — put a real confirm in front
      * of it.
      */
+    // route: POST /auth/delete-account
     async delete() {
         const result = await runtimeRequest(this.config, "/auth/delete-account", { method: "POST" });
         await this.config.tokenStore.clear();
@@ -370,21 +503,30 @@ export class CreditsClient {
      *
      *   const { balance } = await g.credits.balance();
      */
+    // route: GET /auth/credits
     async balance() {
         return runtimeRequest(this.config, "/auth/credits");
     }
 }
 /**
- * The AI route. `chat` takes the provider's own request body — exactly what
- * you would POST to OpenAI's /v1/chat/completions, Anthropic's /v1/messages
- * or Google's generateContent — and answers with the fetch `Response`
- * untouched, streaming intact (SSE stays SSE). Gemmein spends a credit,
- * adds the owner's key, forwards, and passes status and bytes back. Pass
- * `tool` (W9.3b) to run a named, owner-priced-and-gated operation instead
- * of the implicit default (one credit, any allowed model, no gate).
- * Response headers: `x-gemmein-credits-remaining` on every answer that
- * passed the spend; `x-gemmein-credit: refunded` when the provider failed
- * before its first byte.
+ * The AI route. The primary path is a NAMED TOOL defined on the server:
+ * `run(name, inputs)` sends a name and inputs, the server composes the
+ * provider request from the tool's own instructions and template (never
+ * the browser), gates it, spends the tool's credits and streams the
+ * answer back; `runText` is the same call collected to one string;
+ * `calls()` is the signed-in person's own history. `chat` is the RAW
+ * call: it takes the provider's own request body — exactly what you would
+ * POST to OpenAI's /v1/chat/completions, Anthropic's /v1/messages or
+ * Google's generateContent — and answers with the fetch `Response`
+ * untouched, streaming intact (SSE stays SSE). Raw calls are off by
+ * default for every provider key (`raw_calls_off`, 403) until the founder
+ * switches them on for that key on the AI tools page. Gemmein spends a
+ * credit, adds the owner's key, forwards, and passes status and bytes
+ * back. Pass `tool` (W9.3b) to a raw call to price and gate it as a named
+ * tool instead of the implicit default (one credit, any allowed model, no
+ * gate). Response headers: `x-gemmein-credits-remaining` on every answer
+ * that passed the spend; `x-gemmein-credit: refunded` when the provider
+ * failed before its first byte.
  */
 export class AiClient {
     constructor(config) {
@@ -395,7 +537,10 @@ export class AiClient {
      *   for await (const chunk of res.body) { … }
      *
      * Browser sessions only — a server key is refused (`scope_denied`, 403).
-     * Refusals, all `GemmeinError`: `session_required` (401) ·
+     * Refusals, all `GemmeinError`: `raw_calls_off` (403 — raw calls are off
+     * for this provider until the founder switches them on for its key on
+     * the AI tools page; call a named tool with `run` instead) ·
+     * `session_required` (401) ·
      * `credits_exhausted` (402 — the message carries the balance; show your
      * own "buy more" door, which is a product checkout) · `ai_not_configured`
      * (409 — the owner has set no key) · `provider_required` (400) ·
@@ -414,12 +559,13 @@ export class AiClient {
      * `x-gemmein-credit: refunded`). `x-gemmein-tool` names the tool; absent
      * on the implicit default.
      */
+    // route: POST /ai/chat
     async chat(body, options = {}) {
         const payload = options.provider ? { provider: options.provider, ...body } : body;
         const url = new URL("/ai/chat", this.config.apiUrl);
         if (options.tool)
             url.searchParams.set("tool", options.tool);
-        const response = await fetch(url, {
+        const response = await this.config.fetch(url, {
             method: "POST",
             body: JSON.stringify(payload),
             headers: await runtimeHeaders(this.config, { "content-type": "application/json" }),
@@ -441,6 +587,94 @@ export class AiClient {
         }
         return response;
     }
+    /**
+     * W9.6: run a named tool with INPUTS — the server composes the provider
+     * request from the tool's own instructions and template (never the
+     * browser), gates it, spends its credits and streams the answer back.
+     * The answer is the provider's own shape for the tool's provider (SSE
+     * when `stream`), so read it as you would `chat()`'s.
+     *
+     *   const res = await g.ai.run("summarise", { text }, { stream: true });
+     *
+     * Browser sessions only — a server key is refused (`scope_denied`, 403).
+     * Refusals, all `GemmeinError`: `session_required` (401 — sign in
+     * first) · `ai_capped` (429 — 20 calls a minute per person;
+     * `err.resetAt`) · `unknown_tool` (404 — no tool by that name in this
+     * environment) · `tool_disabled` (403 — the owner switched it off) ·
+     * `entitlement_required` (403 — the message names the plan or product
+     * it needs) · `payload_too_large` (413 — inputs over 64 KB) ·
+     * `invalid_body` (400 — the body must be a JSON object
+     * `{ inputs, stream? }`) · `invalid_inputs` (400 — the message names the
+     * input and the rule) · `tool_incomplete` (409 — the tool composes
+     * nothing; a founder's fix) · `ai_not_configured` (409 — the tool's
+     * provider has no key set; the owner pastes one) · `credits_exhausted`
+     * (402 — the message names the tool, its price and the balance) ·
+     * `provider_unreachable` (502 — no answer before the first byte; the
+     * tool's credits are refunded, header `x-gemmein-credit: refunded`).
+     * The provider's own answer — 2xx or not — is returned as it came; read
+     * `res.ok` yourself. `x-gemmein-tool` names the tool.
+     */
+    // route: POST /ai/run/{tool}
+    async run(tool, inputs = {}, options = {}) {
+        const url = new URL(`/ai/run/${encodeURIComponent(tool)}`, this.config.apiUrl);
+        const response = await this.config.fetch(url, {
+            method: "POST",
+            body: JSON.stringify({ inputs, ...(options.stream ? { stream: true } : {}) }),
+            headers: await runtimeHeaders(this.config, { "content-type": "application/json" }),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        if (!response.ok) {
+            if (isForwardedAnswer(response)) {
+                const peek = (await response.clone().json().catch(() => null));
+                if (peek?.code !== "provider_unreachable")
+                    return response;
+            }
+            const errorBody = await readErrorBody(response);
+            if (errorBody.code === "auth_expired")
+                await this.config.tokenStore.clear();
+            throw new GemmeinError({ status: response.status, ...errorBody });
+        }
+        return response;
+    }
+    /**
+     * W9.6: `run()` without a stream, as one string — the text lifted out
+     * of the tool's provider's answer (the same readers `text()` uses).
+     * `run()`'s refusals, plus: a provider's own non-2xx throws
+     * `provider_error` with the provider's status and message; an answer
+     * with no text to lift out throws `invalid_response` (status 0).
+     *
+     *   const summary = await g.ai.runText("summarise", { text });
+     */
+    // route: POST /ai/run/{tool}
+    async runText(tool, inputs = {}, options = {}) {
+        const response = await this.run(tool, inputs, options);
+        if (!response.ok) {
+            throw new GemmeinError({ status: response.status, code: "provider_error", message: await providerErrorMessage(response) });
+        }
+        const data = (await response.json());
+        const text = extractAiText(data);
+        if (text === null) {
+            throw new GemmeinError({ status: 0, code: "invalid_response", message: "the provider answered without any text — use g.ai.run() with { stream: true } and read the stream" });
+        }
+        return text;
+    }
+    /**
+     * W9.6 §16: the signed-in person's OWN AI calls, newest first — what they
+     * ran, when, what it cost, how it ended; the prompt and answer only where
+     * the tool keeps them. Session required.
+     *
+     *   const { calls, nextCursor } = await g.ai.calls();
+     */
+    // route: GET /auth/ai-calls
+    async calls(options = {}) {
+        const params = new URLSearchParams();
+        if (options.limit)
+            params.set("limit", String(options.limit));
+        if (options.before)
+            params.set("before", options.before);
+        const query = params.toString();
+        return runtimeRequest(this.config, `/auth/ai-calls${query ? `?${query}` : ""}`);
+    }
     /**
      * The non-streaming convenience: one call, one string. Pass a body that
      * does NOT stream (`stream` unset or false); the provider's JSON answer is
@@ -454,6 +688,7 @@ export class AiClient {
      *
      *   const answer = await g.ai.text({ model: "claude-sonnet-4-5", max_tokens: 400, messages });
      */
+    // route: POST /ai/chat
     async text(body, options = {}) {
         const response = await this.chat(body, options);
         if (!response.ok) {
@@ -541,6 +776,7 @@ export class StorageClient {
         this.config = config;
     }
     /** Optionally type your fields: `g.storage.collection<{ title: string }>("notes")`. */
+    // route: none
     collection(name, options = {}) {
         assertCollectionName(name);
         return new CollectionClient(this.config, name, options);
@@ -584,6 +820,7 @@ export class CollectionClient {
      * fake drafts with a data field + client-side filtering: on a public
      * collection the data still reaches everyone.
      */
+    // route: POST /storage/{collection}
     async create(data, options = {}) {
         const query = new URLSearchParams();
         if (options.key !== undefined)
@@ -603,6 +840,7 @@ export class CollectionClient {
      * rule (the app owner sees everyone's). Returns `{ records, hasMore }` —
      * an object, not a bare array.
      */
+    // route: GET /storage/{collection}
     async list(options = {}) {
         const query = new URLSearchParams();
         if (options.limit !== undefined)
@@ -643,6 +881,7 @@ export class CollectionClient {
      * doubling up to 60s, and honours a rate limit's reset time. One watch per
      * page is the intended shape — share its result, don't stack watchers.
      */
+    // route: GET /storage/{collection}
     watch(onChange, options = {}) {
         const asked = options.every;
         const every = Math.max(5000, Math.min(300000, Number.isFinite(asked) ? asked : 10000));
@@ -650,6 +889,11 @@ export class CollectionClient {
         let stopped = false;
         let timer;
         let delayMs = every;
+        // W10 §1 A: the platform's own answer to "is the app in front of the
+        // user?" when one was injected — `document` when it wasn't. One
+        // `unsubscribe` either way, so every teardown path is the same line.
+        const vis = this.config.visibility;
+        let unsubscribe;
         let watermark;
         // One tick at a time. A visibility flip mid-tick sets resyncPending
         // instead of racing a second loop into existence (each raced loop would
@@ -715,9 +959,8 @@ export class CollectionClient {
                         clearTimeout(timer);
                         timer = undefined;
                     }
-                    if (typeof document !== "undefined") {
-                        document.removeEventListener("visibilitychange", onVisibility);
-                    }
+                    unsubscribe?.();
+                    unsubscribe = undefined;
                     if (typeof console !== "undefined")
                         console.warn(`gemmein watch stopped: ${err.code} — start a new watch after signing in`);
                     return;
@@ -741,7 +984,9 @@ export class CollectionClient {
             }
             schedule();
         };
-        const hidden = () => typeof document !== "undefined" && document.visibilityState === "hidden";
+        const hidden = () => (vis
+            ? vis.isHidden()
+            : typeof document !== "undefined" && document.visibilityState === "hidden");
         const schedule = () => {
             if (stopped || hidden() || timer !== undefined)
                 return;
@@ -775,8 +1020,12 @@ export class CollectionClient {
                 void tick(true);
             }
         };
-        if (typeof document !== "undefined") {
+        if (vis) {
+            unsubscribe = vis.onChange(onVisibility);
+        }
+        else if (typeof document !== "undefined") {
             document.addEventListener("visibilitychange", onVisibility);
+            unsubscribe = () => document.removeEventListener("visibilitychange", onVisibility);
         }
         // Born hidden: wait for the tab — the visibility handler runs the first
         // sync when the user actually looks.
@@ -790,12 +1039,12 @@ export class CollectionClient {
                 if (timer !== undefined)
                     clearTimeout(timer);
                 timer = undefined;
-                if (typeof document !== "undefined") {
-                    document.removeEventListener("visibilitychange", onVisibility);
-                }
+                unsubscribe?.();
+                unsubscribe = undefined;
             },
         };
     }
+    // route: GET /storage/{collection}/{id}
     async get(id, options = {}) {
         const qs = options.expand && options.expand.length > 0 ? `?expand=${encodeURIComponent(options.expand.join(","))}` : "";
         return this.request(`/${encodeURIComponent(id)}${qs}`);
@@ -815,6 +1064,7 @@ export class CollectionClient {
      * docs), pass `{ ifVersion: record.version }` — a stale save gets a 409
      * `conflict` instead of clobbering; re-read, reapply, retry.
      */
+    // route: PATCH /storage/{collection}/{id}
     async update(id, data, options = {}) {
         const query = new URLSearchParams();
         if (options.ifVersion !== undefined)
@@ -827,11 +1077,12 @@ export class CollectionClient {
             body: JSON.stringify(data)
         });
     }
+    // route: DELETE /storage/{collection}/{id}
     async delete(id) {
         await this.request(`/${encodeURIComponent(id)}`, { method: "DELETE" });
     }
     /**
-     * Upload a file and get back a REFERENCE — `file:01K…` — not a URL.
+     * Upload a file and get back a REFERENCE — `file:<uuid>` — not a URL.
      *
      * Store the reference. It never expires, it is safe to log and export, and
      * it grants nothing on its own. To show or download the file, call
@@ -858,23 +1109,43 @@ export class CollectionClient {
      * There is deliberately no `url` here. A URL that outlives a refund is the
      * bug this replaced.
      */
+    // route: POST /storage/{collection}/upload
+    // route: POST /storage/{collection}/upload/{fileId}/confirm
     async upload(file, options) {
-        const name = options?.name ?? (file instanceof File ? file.name : "upload");
+        // W10 §1 A: `File` is a browser class. Where it does not exist — React
+        // Native — a bare `instanceof File` is a ReferenceError, not a false,
+        // so the guard comes first. The three fields the presign needs are then
+        // read the same way off every shape: a File, a Blob, an
+        // `expo-file-system` File, or the picker's `{ uri, name, type, size }`.
+        const part = file;
+        const name = options?.name
+            ?? (typeof File !== "undefined" && file instanceof File
+                ? file.name
+                : typeof part.name === "string" ? part.name : "upload");
         // A Blob built from bytes has type "" — `contentType` names it. The
         // server proves the bytes either way.
-        const contentType = options?.contentType ?? file.type;
+        const contentType = options?.contentType ?? part.type ?? "";
+        // A presign under one byte is refused ("file must not be empty"): a
+        // Blob knows its own size, a React Native part carries the picker's.
+        const size = typeof part.size === "number" ? part.size : 0;
         // Step 1: Get presigned upload URL
         const presign = await this.request("/upload", {
             method: "POST",
-            body: JSON.stringify({ name, size: file.size, contentType, ...(options?.for ? { for: options.for } : {}) }),
+            body: JSON.stringify({ name, size, contentType, ...(options?.for ? { for: options.for } : {}) }),
         });
         // Step 2: Upload directly to S3 via presigned POST
         const form = new FormData();
         for (const [key, value] of Object.entries(presign.fields)) {
             form.append(key, value);
         }
-        form.append("file", file); // Must be last — S3 presigned POST requirement
-        const s3Response = await fetch(presign.uploadUrl, { method: "POST", body: form });
+        // Must be last — S3 presigned POST requirement. Whatever arrived is
+        // appended AS IT IS: a Blob, a File, or — on a client given React
+        // Native's own fetch — the picker's `{ uri, ... }` part, whose bytes
+        // RN's FormData reads off the device when it serialises. Expo's fetch
+        // refuses that part, so `@gemmein/sdk/expo` has already turned it into
+        // an `expo-file-system` `File` by the time it gets here.
+        form.append("file", file);
+        const s3Response = await this.config.fetch(presign.uploadUrl, { method: "POST", body: form });
         if (!s3Response.ok) {
             throw new GemmeinError({
                 status: s3Response.status,
@@ -889,7 +1160,7 @@ export class CollectionClient {
         return confirmed;
     }
     async request(suffix, init = {}) {
-        const response = await fetch(new URL(`/storage/${encodeURIComponent(this.name)}${suffix}`, this.config.apiUrl), {
+        const response = await this.config.fetch(new URL(`/storage/${encodeURIComponent(this.name)}${suffix}`, this.config.apiUrl), {
             ...init,
             headers: await runtimeHeaders(this.config, {
                 "content-type": "application/json",
@@ -918,10 +1189,12 @@ export class GemmeinServer {
         }
         this.apiUrl = options.apiUrl ?? "https://api.gemmein.com";
         this.secretKey = options.secretKey;
+        this.fetch = resolveFetch(options.fetch, this.apiUrl);
     }
+    // route: none
     collection(name) {
         assertCollectionName(name);
-        return new ServerCollectionClient(this.apiUrl, this.secretKey, name);
+        return new ServerCollectionClient(this.apiUrl, this.secretKey, name, this.fetch);
     }
     /**
      * Mint a member session for a test email WITHOUT an OTP round-trip — so a CI
@@ -931,6 +1204,7 @@ export class GemmeinServer {
      * `sk_live` key, and the server refuses it too. Never ship this in app code.
      * Pass the returned `token` to `gemmein(pk, { tokenStore })` to act as that user.
      */
+    // route: POST /server/test-session
     async testSession(email) {
         if (this.secretKey.startsWith("sk_live")) {
             throw new GemmeinError({
@@ -939,7 +1213,7 @@ export class GemmeinServer {
                 message: "test sessions are only available in a development environment — never with a live (sk_live) key",
             });
         }
-        const response = await fetch(new URL("/server/test-session", this.apiUrl), {
+        const response = await this.fetch(new URL("/server/test-session", this.apiUrl), {
             method: "POST",
             headers: { "x-app-key": this.secretKey, "x-client-info": CLIENT_INFO, "content-type": "application/json" },
             body: JSON.stringify({ email }),
@@ -976,8 +1250,9 @@ export class GemmeinServer {
      * (a security notice must never lose to five order emails); misusing it
      * for campaigns is visible in your own audit trail.
      */
+    // route: POST /server/notify
     async notify(personId, input) {
-        const response = await fetch(new URL("/server/notify", this.apiUrl), {
+        const response = await this.fetch(new URL("/server/notify", this.apiUrl), {
             method: "POST",
             headers: { "x-app-key": this.secretKey, "x-client-info": CLIENT_INFO, "content-type": "application/json" },
             body: JSON.stringify({ personId, subject: input.subject, text: input.text, ...(input.kind ? { kind: input.kind } : {}), ...(input.key ? { key: input.key } : {}) }),
@@ -1014,6 +1289,7 @@ export class GemmeinServer {
      * off until the owner reactivates them in the dashboard) ·
      * `invalid_body` (token missing, not a string, or over 512 chars).
      */
+    // route: POST /server/verify-session
     async verifySession(token) {
         return this.gate("/server/verify-session", {
             method: "POST",
@@ -1043,6 +1319,7 @@ export class GemmeinServer {
      * `invite_capped` (429 — 500 invite calls per app per day, a fetch of an existing person counting too; the message says
      * where to write to raise it; `err.resetAt` says when the window ends).
      */
+    // route: POST /server/people
     async invitePerson(email) {
         return this.gate("/server/people", {
             method: "POST",
@@ -1065,6 +1342,7 @@ export class GemmeinServer {
      * `person_not_found` (404 — no person with this id in this app and
      * environment; existence is never leaked).
      */
+    // route: GET /server/people/{personId}/holdings
     async holdings(personId) {
         return this.gate(`/server/people/${encodeURIComponent(personId)}/holdings`);
     }
@@ -1097,6 +1375,7 @@ export class GemmeinServer {
      * `invalid_entitlement` / `unknown_plan` (no plan or product by that
      * name — the owner adds it on the Payments page) · `person_not_found`.
      */
+    // route: POST /server/people/{personId}/grants
     async grantAccess(personId, input) {
         return this.gate(`/server/people/${encodeURIComponent(personId)}/grants`, {
             method: "POST",
@@ -1135,6 +1414,7 @@ export class GemmeinServer {
      * `invalid_reason` / `invalid_key` (400) · `dedupe_conflict` (409 — the
      * key already names a different movement).
      */
+    // route: POST /server/people/{personId}/credits/spend
     async spendCredits(personId, input) {
         return this.gate(`/server/people/${encodeURIComponent(personId)}/credits/spend`, {
             method: "POST",
@@ -1162,6 +1442,7 @@ export class GemmeinServer {
      * `grant_not_found` (404 — not this person's grant, in this app and
      * environment; existence is never leaked) · `already_revoked` (409).
      */
+    // route: POST /server/people/{personId}/grants/{grantId}/revoke
     async revokeAccess(personId, grantId, input = {}) {
         return this.gate(`/server/people/${encodeURIComponent(personId)}/grants/${encodeURIComponent(grantId)}/revoke`, { method: "POST", body: JSON.stringify({ ...(input.reason ? { reason: input.reason } : {}) }) });
     }
@@ -1173,7 +1454,7 @@ export class GemmeinServer {
         const headers = { "x-app-key": this.secretKey, "x-client-info": CLIENT_INFO };
         if (init.body)
             headers["content-type"] = "application/json";
-        const response = await fetch(new URL(path, this.apiUrl), { ...init, headers });
+        const response = await this.fetch(new URL(path, this.apiUrl), { ...init, headers });
         if (!response.ok) {
             throw new GemmeinError({ status: response.status, ...(await readErrorBody(response)) });
         }
@@ -1181,14 +1462,17 @@ export class GemmeinServer {
     }
 }
 class ServerCollectionClient {
-    constructor(apiUrl, secretKey, name) {
+    constructor(apiUrl, secretKey, name, fetchImpl) {
         this.apiUrl = apiUrl;
         this.secretKey = secretKey;
         this.name = name;
+        this.fetch = fetchImpl;
     }
+    // route: GET /storage/{collection}/{id}
     async get(id) {
         return this.request(`/${encodeURIComponent(id)}`);
     }
+    // route: GET /storage/{collection}
     async list(options = {}) {
         const query = new URLSearchParams();
         if (options.limit !== undefined)
@@ -1210,6 +1494,7 @@ class ServerCollectionClient {
         const qs = query.toString();
         return this.request(qs ? `?${qs}` : "");
     }
+    // route: PATCH /storage/{collection}/{id}
     async update(id, data) {
         return this.request(`/${encodeURIComponent(id)}`, {
             method: "PATCH",
@@ -1224,7 +1509,7 @@ class ServerCollectionClient {
         if (init.body) {
             headers["content-type"] = "application/json";
         }
-        const response = await fetch(new URL(`/storage/${encodeURIComponent(this.name)}${suffix}`, this.apiUrl), { ...init, headers });
+        const response = await this.fetch(new URL(`/storage/${encodeURIComponent(this.name)}${suffix}`, this.apiUrl), { ...init, headers });
         if (response.status === 204)
             return undefined;
         if (!response.ok) {
@@ -1284,7 +1569,7 @@ async function readErrorBody(response) {
 // One request path for every runtime client (auth, subscriptions,
 // payments, account) — same headers, same error handling, same signposts.
 async function runtimeRequest(config, path, init = {}) {
-    const response = await fetch(new URL(path, config.apiUrl), {
+    const response = await config.fetch(new URL(path, config.apiUrl), {
         ...init,
         headers: await runtimeHeaders(config, init.headers)
     });
@@ -1295,7 +1580,7 @@ async function runtimeHeaders(config, headers) {
     return {
         ...headers,
         "x-app-key": config.appKey,
-        "x-client-info": CLIENT_INFO,
+        "x-client-info": config.clientInfo,
         ...(token ? { authorization: `Bearer ${token}` } : {})
     };
 }