@gemmein/sdk 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -2,6 +2,37 @@ export type GemmeinOptions = {
     appKey: string;
     apiUrl?: string;
     tokenStore?: TokenStore;
+    /**
+     * W10 §1 A — the fetch EVERY request this client makes goes through.
+     * Defaults to `globalThis.fetch`, read at CALL time so a polyfill
+     * installed after construction still counts. Expo passes `expo/fetch`,
+     * whose streaming answers React Native's own fetch cannot give.
+     */
+    fetch?: typeof fetch;
+    /**
+     * W10 §1 A — where "is the app in front of the user?" comes from, for
+     * `watch()`'s sleep-while-hidden. Absent, it is the browser's
+     * `document.visibilityState`, exactly as before. Expo passes an
+     * AppState-driven hook.
+     */
+    visibility?: VisibilityHook;
+    /**
+     * W10 §1 A — the platform appended to `x-client-info`
+     * (`gemmein-sdk/<version> expo-ios`). A report of which build called,
+     * never a proof. Cleaned and capped here — see `clientInfoFor`.
+     */
+    platform?: string;
+};
+/**
+ * W10 §1 A — a platform's answer to "is the app in front of the user?".
+ * The browser answers it with `document.visibilityState`; React Native
+ * answers it with `AppState`. `onChange` registers a listener and returns
+ * the function that removes it — one shape, so `watch()` never has to know
+ * which platform it is running on.
+ */
+export type VisibilityHook = {
+    isHidden(): boolean;
+    onChange(cb: () => void): () => void;
 };
 export type TokenStore = {
     get(): string | undefined | Promise<string | undefined>;
@@ -101,10 +132,18 @@ export type CurrentUser = {
     authenticated: true;
     userId: string;
     email: string;
+    /**
+     * W10 — the store account token, when the engine carries one. It is
+     * passed through exactly as `GET /auth/current-user` sent it, never
+     * synthesised here; an engine that does not send it leaves this
+     * absent — read that as "not carried", never as "no account".
+     */
+    storeAccountToken?: string | null;
 } | {
     authenticated: false;
     userId?: undefined;
     email?: undefined;
+    storeAccountToken?: undefined;
 };
 export type AuthSession = {
     token: string;
@@ -120,13 +159,21 @@ export type AuthSession = {
  *  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 declare const SDK_VERSION = "0.8.0";
+export declare const SDK_VERSION = "0.10.0";
 /** 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 declare const CLIENT_INFO = "gemmein-sdk/0.8.0";
+export declare const CLIENT_INFO = "gemmein-sdk/0.10.0";
+/** 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 declare function clientInfoFor(platform?: string): string;
 export declare class GemmeinError extends Error {
     readonly status: number;
     readonly code: string;
@@ -141,12 +188,19 @@ export declare class GemmeinError extends Error {
      * plans by name through checkout, the server never hands out the list.
      */
     readonly requires?: string;
+    /**
+     * Present on `network_unreachable` — the fetch implementation's own throw,
+     * kept so a bug report can say WHICH transport failure it was. Read it for
+     * a log; never branch on it (its shape is the runtime's, not Gemmein's).
+     */
+    readonly cause?: unknown;
     constructor(input: {
         status: number;
         code: string;
         message: string;
         resetAt?: string;
         requires?: string;
+        cause?: unknown;
     });
 }
 export declare class MemoryTokenStore implements TokenStore {
@@ -159,6 +213,16 @@ export declare class BrowserTokenStore implements TokenStore {
     private readonly key;
     constructor(appKey: string);
     get(): string | 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: string): void;
     clear(): void;
 }
@@ -208,6 +272,12 @@ type ClientConfig = {
     apiUrl: string;
     appKey: string;
     tokenStore: TokenStore;
+    /** W10 §1 A — always present: the injected fetch, or the lazy default. */
+    fetch: typeof fetch;
+    /** W10 §1 A — absent in a browser; `watch()` falls back to `document`. */
+    visibility?: VisibilityHook | undefined;
+    /** W10 §1 A — `CLIENT_INFO`, plus the platform when one was named. */
+    clientInfo: string;
 };
 export declare class AuthClient {
     private readonly config;
@@ -217,6 +287,17 @@ export declare class AuthClient {
         email: string;
         code: string;
     }): Promise<AuthSession>;
+    /**
+     * 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.
+     */
     logout(): Promise<void>;
     currentUser(): Promise<CurrentUser>;
     private request;
@@ -275,7 +356,7 @@ export declare class PurchasesClient {
     }>>;
 }
 /**
- * A file reference — `file:01K…`. What `upload()` gives you and what your
+ * A file reference — `file:<uuid>`. What `upload()` gives you and what your
  * record should store.
  *
  * Branded so it cannot be mistaken for a URL: `<img src={record.poster}>` is a
@@ -285,6 +366,33 @@ export declare class PurchasesClient {
 export type FileRef = string & {
     readonly __gemmeinFileRef: unique symbol;
 };
+/**
+ * W10 §1 A — what `upload()` takes. A browser hands it a `File` or a
+ * `Blob`.
+ *
+ * On a phone the thing a picker returns is a `{ uri, name, type, size }`
+ * object, and it reaches the wire two ways (W10 row 9, found by driving
+ * the Expo app):
+ *
+ *  * through `@gemmein/sdk/expo` — `createExpoGemmein` turns the picker
+ *    shape into an `expo-file-system` `File`, which IS a `Blob`, before it
+ *    reaches here. This is the path an Expo app has: Expo's own fetch (the
+ *    entry's default, and the only one that can stream an AI answer)
+ *    refuses a bare picker part with
+ *    `Unsupported FormDataPart implementation`.
+ *  * through a client given React Native's own fetch
+ *    (`gemmein(key, { fetch })`) — RN's `FormData` reads the bytes at
+ *    `uri` itself, so the part is appended exactly as the picker gave it.
+ *
+ * Carry the picker's `size` with it — the server refuses a presign that
+ * declares nothing (it cannot accept an empty file).
+ */
+export type UploadInput = Blob | File | {
+    uri: string;
+    name?: string;
+    type?: string;
+    size?: number;
+};
 /**
  * Turn a stored file reference into a URL you can actually use.
  *
@@ -360,9 +468,14 @@ export declare 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`.
      */
     buy(product: string, options?: {
         item?: string;
@@ -387,6 +500,23 @@ export declare class AccountClient {
     delete(): Promise<unknown>;
 }
 export type AiProvider = "openai" | "anthropic" | "google";
+/** W9.6 §16: one of the person's own AI calls, as `g.ai.calls()` lists them. */
+export type AiCallRecord = {
+    id: string;
+    tool: string;
+    kind: string;
+    provider: string;
+    model: string | null;
+    tokensIn: number | null;
+    tokensOut: number | null;
+    credits: number;
+    outcome: "ok" | "refused" | "provider_error" | "unreachable" | "client_closed" | "stream_ended";
+    refusalCode: string | null;
+    latencyMs: number | null;
+    prompt: string | null;
+    answer: string | null;
+    createdAt: string;
+};
 export type AiChatOptions = {
     /** Which configured provider answers. Optional when exactly one key is
      *  set; refused `provider_required` (400) when it is ambiguous. Refused
@@ -396,7 +526,10 @@ export type AiChatOptions = {
     /** W9.3b: a named AI tool (owner-configured in the console — credits,
      *  gate and provider/model are the tool's, not this call's). Sent as
      *  `?tool=`, never in the body. Omitted → the implicit default tool: one
-     *  credit, any allowed model, no gate. */
+     *  credit, any allowed model, no gate. With or without `tool`, `chat` is
+     *  a RAW call — off by default (`raw_calls_off`, 403) until the founder
+     *  switches raw calls on for that provider's key on the AI tools page;
+     *  the normal path to a named tool is `run(name, inputs)`. */
     tool?: string;
     /** Abort the call — the stream closes; a call that dies mid-stream is
      *  not refunded. */
@@ -433,16 +566,24 @@ export declare class CreditsClient {
     }>;
 }
 /**
- * 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 declare class AiClient {
     private readonly config;
@@ -452,7 +593,10 @@ export declare 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) ·
@@ -472,6 +616,63 @@ export declare class AiClient {
      * on the implicit default.
      */
     chat(body: Record<string, unknown>, options?: AiChatOptions): Promise<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.
+     */
+    run(tool: string, inputs?: Record<string, string | number | boolean>, options?: {
+        stream?: boolean;
+        signal?: AbortSignal;
+    }): Promise<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 });
+     */
+    runText(tool: string, inputs?: Record<string, string | number | boolean>, options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    /**
+     * 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();
+     */
+    calls(options?: {
+        limit?: number;
+        before?: string | null;
+    }): Promise<{
+        calls: AiCallRecord[];
+        nextCursor: string | null;
+    }>;
     /**
      * 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
@@ -600,7 +801,7 @@ export declare class CollectionClient<T extends Record<string, unknown> = Record
     }): Promise<GemmeinRecord<T>>;
     delete(id: string): Promise<void>;
     /**
-     * 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
@@ -627,7 +828,7 @@ export declare class CollectionClient<T extends Record<string, unknown> = Record
      * There is deliberately no `url` here. A URL that outlives a refund is the
      * bug this replaced.
      */
-    upload(file: Blob | File, options?: {
+    upload(file: UploadInput, options?: {
         name?: string;
         contentType?: string;
         for?: string;
@@ -642,6 +843,11 @@ export declare class CollectionClient<T extends Record<string, unknown> = Record
 export type GemmeinServerOptions = {
     secretKey: string;
     apiUrl?: string;
+    /** The same seam the client has: a `fetch` to use instead of the global
+     *  one. Every request this class makes goes through `resolveFetch`, so a
+     *  transport failure is a `GemmeinError` `network_unreachable` here too
+     *  (W10 review row 14a — the parity law: one seam, both rails). */
+    fetch?: typeof fetch;
 };
 /**
  * Where a grant came from — the KIND only. The gate never returns the
@@ -680,6 +886,13 @@ export type Holdings = {
         balance: number;
     } | null;
 };
+/**
+ * The person behind a token or an id. The role you read here is the EFFECTIVE
+ * one — account membership (owner/admin) wins over the stored role, so
+ * a founder signed into their own app reads `owner` here and not the `member`
+ * every person is born as. `verifySession` and `holdings` answer with
+ * the same one — one person has one role, whichever door asked for it.
+ */
 export type GatePerson = {
     id: string;
     email: string;
@@ -698,6 +911,12 @@ export type InvitedPerson = GatePerson & {
 export declare class GemmeinServer {
     private readonly apiUrl;
     private readonly secretKey;
+    /** W10 review row 14a: THE ONE TRANSPORT SEAM, on this rail too. Every
+     *  call below goes through it, so a refused connection is a typed
+     *  `network_unreachable` and never a raw `TypeError` — the same law the
+     *  client rail has held since row 9, and what makes "everything the
+     *  package throws is a GemmeinError" true of the whole package. */
+    private readonly fetch;
     constructor(options: GemmeinServerOptions);
     collection(name: string): ServerCollectionClient;
     /**
@@ -929,7 +1148,10 @@ declare class ServerCollectionClient {
     private readonly apiUrl;
     private readonly secretKey;
     private readonly name;
-    constructor(apiUrl: string, secretKey: string, name: string);
+    /** Handed down from `GemmeinServer` — never resolved again here, so one
+     *  client has one transport and a test's injected fetch reaches it. */
+    private readonly fetch;
+    constructor(apiUrl: string, secretKey: string, name: string, fetchImpl: typeof fetch);
     get(id: string): Promise<unknown>;
     list(options?: {
         limit?: number;