@gemmein/sdk 0.9.0 → 0.10.0

package/dist/index.d.cts

@@ -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.9.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.9.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;
@@ -688,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
@@ -715,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;
@@ -730,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
@@ -768,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;
@@ -786,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;
     /**
@@ -1017,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;

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.9.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.9.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;
@@ -688,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
@@ -715,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;
@@ -730,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
@@ -768,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;
@@ -786,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;
     /**
@@ -1017,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;