@gemmein/sdk 0.9.0 → 0.10.0

package/dist/expo.d.ts

@@ -0,0 +1,152 @@
+import { Gemmein } from "./index.js";
+import type { GemmeinOptions, TokenStore, UploadInput, VisibilityHook } from "./index.js";
+export * from "./index.js";
+export { Gemmein, GemmeinError, AuthClient, PurchasesClient, FilesClient, SubscriptionsClient, PaymentsClient, AccountClient, CreditsClient, AiClient, StorageClient, CollectionClient, GemmeinServer, } from "./index.js";
+/** The slice of `expo-secure-store` this entry calls. */
+export type SecureStoreModule = {
+    getItemAsync(key: string, options?: Record<string, unknown>): Promise<string | null>;
+    setItemAsync(key: string, value: string, options?: Record<string, unknown>): Promise<void>;
+    deleteItemAsync(key: string, options?: Record<string, unknown>): Promise<void>;
+    /** `WHEN_UNLOCKED_THIS_DEVICE_ONLY` — read off the module when present. */
+    WHEN_UNLOCKED_THIS_DEVICE_ONLY?: unknown;
+};
+/** The slice of React Native's `AppState` this entry subscribes to. */
+export type AppStateModule = {
+    currentState: string | null;
+    addEventListener(type: string, handler: (state: string) => void): {
+        remove(): void;
+    } | (() => void);
+};
+/** The slice of React Native's `Platform` this entry reads. */
+export type PlatformModule = {
+    OS: string;
+};
+/**
+ * The slice of `expo-file-system` this entry calls: its `File` class.
+ *
+ * `new File(uri)` — the constructor takes the `file:///` URI a picker or a
+ * camera handed back (it accepts more segments, and a `Directory`/`File`
+ * first argument, which this entry never needs). The instance implements
+ * `Blob` and carries `uri`, `name`, `type` and `size`, which is exactly
+ * what `upload()` reads.
+ */
+export type FileSystemModule = {
+    File: new (uri: string) => Blob & {
+        uri?: string;
+        name?: string;
+        type?: string | null;
+        size?: number | null;
+    };
+};
+/** Everything an Expo app can hand in instead of letting this file resolve
+ *  it. Tests pass fakes here; an app may pass its own static imports, which
+ *  is the fastest path (no dynamic resolution at all). */
+export type ExpoModules = {
+    SecureStore?: SecureStoreModule;
+    AppState?: AppStateModule;
+    Platform?: PlatformModule;
+    /** `expo-file-system`, for `upload()`'s picker shape — see `expoUploadPart`. */
+    FileSystem?: FileSystemModule;
+    fetch?: typeof fetch;
+};
+/**
+ * iOS refuses a Keychain value much over 2 KB through expo-secure-store,
+ * and the failure is a native throw the app cannot read. A Gemmein session
+ * token is a short opaque string — two orders of magnitude under this — so
+ * anything at this size is a caller storing the wrong thing. It is refused
+ * HERE, with a sentence, rather than on a device the author cannot see.
+ */
+export declare const SECURE_STORE_VALUE_LIMIT = 2048;
+/**
+ * The session, kept in the iOS Keychain / Android Keystore through
+ * `expo-secure-store`. Keyed per app key exactly as `BrowserTokenStore`
+ * keys localStorage, so two Gemmein apps in one binary never share a
+ * token.
+ *
+ * `keychainAccessible: WHEN_UNLOCKED_THIS_DEVICE_ONLY` — the token is
+ * readable only while the device is unlocked AND never travels in an
+ * iCloud/iTunes backup or to a restored device. A session that survives a
+ * device restore is a session the person cannot revoke by losing the
+ * phone.
+ *
+ * Reads and clears are guarded: a locked keychain, a wiped entry, or a
+ * runtime with no secure store at all degrades to "signed out", never to
+ * a crash. A WRITE the device refuses throws `secure_store_unavailable` —
+ * see the note on `set`.
+ */
+export declare class SecureStoreTokenStore implements TokenStore {
+    private readonly key;
+    private readonly injected?;
+    constructor(appKey: string, secureStore?: SecureStoreModule);
+    private store;
+    /** The accessibility class, read off the module so a version that renames
+     *  the constant does not silently fall back to the iCloud-backed default. */
+    private options;
+    get(): Promise<string | undefined>;
+    set(token: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * The `VisibilityHook` `watch()` sleeps on, answered by React Native's
+ * `AppState` instead of the browser's `document.visibilityState`.
+ *
+ * `AppState.currentState` is `"active" | "background" | "inactive"` (and
+ * `null` before the first read). Only `"active"` is in front of the
+ * person: `"inactive"` is the app-switcher card, a phone call, the
+ * Control Center pulled down — a screen the person is not reading, so
+ * polling there burns battery for nothing.
+ *
+ * Before the module has resolved the app is treated as VISIBLE, which is
+ * the browser default and the safe one: a watcher that wrongly believes
+ * it is hidden goes quiet, and quiet is the failure nobody notices.
+ */
+export declare function appStateVisibility(appState?: AppStateModule): VisibilityHook;
+/**
+ * `expo/fetch` — the WinterCG fetch Expo ships. React Native's own fetch
+ * is XHR-backed and cannot give a streaming body, which is what
+ * `g.ai.chat({ stream: true })` and `g.ai.run(..., { stream: true })`
+ * return. Resolved on the first request; `globalThis.fetch` if Expo's is
+ * not there, so a bare React Native app still works for everything that
+ * is not a stream.
+ */
+export declare function expoFetch(injected?: typeof fetch): typeof fetch;
+/**
+ * The `x-client-info` platform tag: `expo-ios`, `expo-android`, `expo-web`.
+ *
+ * It is baked into the header when the client is CONSTRUCTED, so it cannot
+ * wait on a dynamic import. Pass `Platform` from `react-native` (a static
+ * import that costs an Expo app nothing) and the tag names the OS; without
+ * it the tag is the honest `expo`. Either way it is a report, never a
+ * proof — the ledger stores it as one.
+ */
+export declare function expoPlatformTag(platform?: PlatformModule): string;
+/**
+ * W10 row 9, found by driving the Expo app: `upload()` takes the picker's
+ * `{ uri, name, type, size }`, but `expo/fetch` — the fetch this entry
+ * hands the client, and the only one that can stream an AI answer — refuses
+ * that part when its `FormData` serialises it:
+ * `Unsupported FormDataPart implementation`. React Native's own fetch reads
+ * the bytes at `uri`; Expo's will not.
+ *
+ * So the shape is converted here, before it ever reaches core `upload()`:
+ * `new File(uri)` from `expo-file-system` is a real `Blob` that carries
+ * `uri`, `name`, `type` and `size` — the three fields the presign reads,
+ * plus bytes any FormData can serialise. The picker shape therefore works
+ * through `@gemmein/sdk/expo` exactly as the docs say it does.
+ *
+ * Anything that already carries its own bytes — a `Blob`, a browser `File`,
+ * an `expo-file-system` `File` — is passed through untouched.
+ */
+export declare function expoUploadPart(file: UploadInput, modules?: ExpoModules): Promise<UploadInput>;
+/**
+ * The Expo client. Identical to `gemmein()` in every method, because it IS
+ * `Gemmein` — the only difference is where the session is kept, how "is
+ * the app in front?" is answered, which fetch carries the bytes, and what
+ * the client tag says.
+ *
+ *   const g = createExpoGemmein({ appKey: "pk_live_..." }, { Platform });
+ *
+ * Every default is overridable: pass your own `tokenStore`, `visibility`,
+ * `fetch` or `platform` in `options` and it wins.
+ */
+export declare function createExpoGemmein(options: GemmeinOptions, modules?: ExpoModules): Gemmein;

package/dist/expo.js

@@ -0,0 +1,387 @@
+// W10 §1 A — `@gemmein/sdk/expo`: the SAME package, a second entry point.
+//
+// The core entry (`@gemmein/sdk`) stays platform-neutral and keeps ZERO
+// dependency on Expo or React Native: every platform seam it needs is an
+// option it already takes — `tokenStore`, `visibility`, `fetch`,
+// `platform`. This file is nothing but those four options filled in with
+// a phone's answers, plus the whole core surface re-exported so an Expo
+// app never has to import from two places.
+//
+// Three rules this file keeps:
+//
+//  1. NOTHING is imported from Expo or React Native at module load. The
+//     modules are resolved lazily, inside a try, the first time a method
+//     that needs one runs — so importing this entry in Node (the tests
+//     below, an SSR pass, a script) resolves and runs without any of them
+//     installed. The specifiers are static strings so Metro can still see
+//     and bundle them in a real app.
+//  2. Every module is INJECTABLE. Tests pass fakes; nothing here reaches
+//     for a global to decide what platform it is on.
+//  3. A failure to READ the secure store degrades to "signed out" — the
+//     same law `BrowserTokenStore` keeps for a browser with storage
+//     blocked. A crash on a locked keychain would lock the app out. A
+//     failure to WRITE throws `secure_store_unavailable` (W10 row 9c): a
+//     store that cannot keep the session has broken the promise it exists
+//     for, and silence there signs the person out on the next launch with
+//     nothing anywhere saying why.
+//
+// One thing beyond those four seams: `upload()`'s picker shape. Expo's
+// fetch refuses a bare `{ uri, name, type, size }` part, so the collections
+// this entry hands out convert it to an `expo-file-system` `File` first —
+// see `expoUploadPart`.
+//
+// Install in the app, not here (they are optional peer dependencies):
+//   npx expo install expo-secure-store expo-file-system
+//
+//   import { createExpoGemmein } from "@gemmein/sdk/expo";
+//   import { Platform } from "react-native";
+//   export const g = createExpoGemmein({ appKey: "pk_live_..." }, { Platform });
+import { Gemmein, GemmeinError } from "./index.js";
+// The full core surface, re-exported. `export *` carries the types and the
+// helpers; the explicit list below names every client class the SDK
+// registry knows about (ops/docs/facts.ts SDK_CLASSES), which is what
+// tests/security/sdkParity.test.ts reads to prove this entry is not a
+// smaller SDK wearing the same name.
+export * from "./index.js";
+export { Gemmein, GemmeinError, AuthClient, PurchasesClient, FilesClient, SubscriptionsClient, PaymentsClient, AccountClient, CreditsClient, AiClient, StorageClient, CollectionClient, GemmeinServer, } from "./index.js";
+/**
+ * The lazy resolver. Static specifiers so Metro bundles them; a `catch`
+ * so Node — where none of them exist — gets `undefined` rather than an
+ * unhandled rejection. Resolved once per specifier and remembered.
+ */
+const resolved = new Map();
+function loadModule(name) {
+    const cached = resolved.get(name);
+    if (cached)
+        return cached;
+    const attempt = (async () => {
+        try {
+            switch (name) {
+                // @ts-ignore optional peer dependency — present only in an Expo app
+                case "expo-secure-store": return (await import("expo-secure-store"));
+                // @ts-ignore optional peer dependency — present only in a React Native app
+                case "react-native": return (await import("react-native"));
+                // @ts-ignore optional peer dependency — present only in an Expo app
+                case "expo/fetch": return (await import("expo/fetch"));
+                // @ts-ignore optional peer dependency — present only in an Expo app
+                case "expo-file-system": return (await import("expo-file-system"));
+                default: return undefined;
+            }
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    resolved.set(name, attempt);
+    return attempt;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// SecureStoreTokenStore — the session in the Keychain / Keystore
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * iOS refuses a Keychain value much over 2 KB through expo-secure-store,
+ * and the failure is a native throw the app cannot read. A Gemmein session
+ * token is a short opaque string — two orders of magnitude under this — so
+ * anything at this size is a caller storing the wrong thing. It is refused
+ * HERE, with a sentence, rather than on a device the author cannot see.
+ */
+export const SECURE_STORE_VALUE_LIMIT = 2048;
+/**
+ * The one sentence a refused WRITE reads as (W10 row 9c). The device's own
+ * throw travels on `cause`, so an app that logs it keeps the native message
+ * — `errSecMissingEntitlement`, a locked keychain, a Keystore that is not
+ * there — instead of a Gemmein sentence standing in for it.
+ */
+function secureStoreUnavailable(cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    return new GemmeinError({
+        status: 0,
+        code: "secure_store_unavailable",
+        message: `The session could not be stored: expo-secure-store is not available or refused the write (${detail}) ` +
+            "— install expo-secure-store, or pass a tokenStore",
+        cause,
+    });
+}
+/**
+ * The session, kept in the iOS Keychain / Android Keystore through
+ * `expo-secure-store`. Keyed per app key exactly as `BrowserTokenStore`
+ * keys localStorage, so two Gemmein apps in one binary never share a
+ * token.
+ *
+ * `keychainAccessible: WHEN_UNLOCKED_THIS_DEVICE_ONLY` — the token is
+ * readable only while the device is unlocked AND never travels in an
+ * iCloud/iTunes backup or to a restored device. A session that survives a
+ * device restore is a session the person cannot revoke by losing the
+ * phone.
+ *
+ * Reads and clears are guarded: a locked keychain, a wiped entry, or a
+ * runtime with no secure store at all degrades to "signed out", never to
+ * a crash. A WRITE the device refuses throws `secure_store_unavailable` —
+ * see the note on `set`.
+ */
+export class SecureStoreTokenStore {
+    constructor(appKey, secureStore) {
+        // The same derivation as BrowserTokenStore (packages/sdk/src/index.ts):
+        // one law, two platforms. Every character a pk_ key can carry is legal
+        // in a SecureStore key.
+        this.key = `gemmein_session_${appKey.slice(0, 20)}`;
+        this.injected = secureStore;
+    }
+    async store() {
+        if (this.injected)
+            return this.injected;
+        const mod = await loadModule("expo-secure-store");
+        if (!mod)
+            return undefined;
+        const candidate = (mod.default ?? mod);
+        return typeof candidate?.getItemAsync === "function" ? candidate : undefined;
+    }
+    /** The accessibility class, read off the module so a version that renames
+     *  the constant does not silently fall back to the iCloud-backed default. */
+    options(mod) {
+        const accessible = mod.WHEN_UNLOCKED_THIS_DEVICE_ONLY;
+        return accessible === undefined ? {} : { keychainAccessible: accessible };
+    }
+    async get() {
+        try {
+            const mod = await this.store();
+            if (!mod)
+                return undefined;
+            return (await mod.getItemAsync(this.key, this.options(mod))) ?? undefined;
+        }
+        catch {
+            return undefined; // locked, missing, or unavailable — signed out
+        }
+    }
+    async set(token) {
+        // Measured in BYTES: the limit is the platform's, not JavaScript's.
+        const bytes = new TextEncoder().encode(token).length;
+        if (bytes > SECURE_STORE_VALUE_LIMIT) {
+            throw new GemmeinError({
+                status: 0,
+                code: "token_too_large",
+                message: `This value is ${bytes} bytes; the device secure store holds ${SECURE_STORE_VALUE_LIMIT}. ` +
+                    "A Gemmein session token is far smaller — store the token, not the session payload.",
+            });
+        }
+        // W10 row 9c. This used to return silently on both arms below, so an app
+        // signed in, stored nothing, and reported itself signed out on the next
+        // launch with nothing anywhere saying why — the same silence the Swift
+        // `KeychainTokenStore` kept, found by driving the reference app on an
+        // unsigned simulator build. A store that cannot PERSIST the session has
+        // broken the one promise it exists for, so it says so. Reads and clears
+        // stay lenient: unreadable means signed out, which every app handles.
+        //
+        // The session is real either way — it was minted server-side and
+        // `verifyEmailCode` never gets to return it — so an app that would rather
+        // run than stop can catch this one code and rebuild its client with a
+        // `MemoryTokenStore`: sign-in works, and ends with the process.
+        let mod;
+        try {
+            mod = await this.store();
+        }
+        catch (cause) {
+            throw secureStoreUnavailable(cause);
+        }
+        if (!mod)
+            throw secureStoreUnavailable(new Error("expo-secure-store did not resolve"));
+        try {
+            await mod.setItemAsync(this.key, token, this.options(mod));
+        }
+        catch (cause) {
+            throw secureStoreUnavailable(cause);
+        }
+    }
+    async clear() {
+        try {
+            const mod = await this.store();
+            if (!mod)
+                return;
+            await mod.deleteItemAsync(this.key, this.options(mod));
+        }
+        catch {
+            /* nothing to clear */
+        }
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════
+// appStateVisibility — "is the app in front of the person?"
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * The `VisibilityHook` `watch()` sleeps on, answered by React Native's
+ * `AppState` instead of the browser's `document.visibilityState`.
+ *
+ * `AppState.currentState` is `"active" | "background" | "inactive"` (and
+ * `null` before the first read). Only `"active"` is in front of the
+ * person: `"inactive"` is the app-switcher card, a phone call, the
+ * Control Center pulled down — a screen the person is not reading, so
+ * polling there burns battery for nothing.
+ *
+ * Before the module has resolved the app is treated as VISIBLE, which is
+ * the browser default and the safe one: a watcher that wrongly believes
+ * it is hidden goes quiet, and quiet is the failure nobody notices.
+ */
+export function appStateVisibility(appState) {
+    let mod = appState;
+    const waiting = [];
+    if (!mod) {
+        void loadModule("react-native").then((rn) => {
+            const candidate = rn?.AppState;
+            if (!candidate || typeof candidate.addEventListener !== "function")
+                return;
+            mod = candidate;
+            for (const attach of waiting.splice(0))
+                attach(candidate);
+        });
+    }
+    return {
+        isHidden() {
+            return mod ? mod.currentState !== "active" : false;
+        },
+        onChange(cb) {
+            let remove;
+            let cancelled = false;
+            const attach = (m) => {
+                if (cancelled)
+                    return;
+                // RN ≥ 0.65 returns a subscription with `.remove()`; older builds
+                // returned nothing and were removed by `removeEventListener`. Both
+                // shapes collapse to one remover here.
+                const subscription = m.addEventListener("change", () => cb());
+                remove = typeof subscription === "function"
+                    ? subscription
+                    : subscription && typeof subscription.remove === "function"
+                        ? () => subscription.remove()
+                        : undefined;
+            };
+            if (mod)
+                attach(mod);
+            else
+                waiting.push(attach);
+            return () => {
+                cancelled = true;
+                const off = remove;
+                remove = undefined;
+                off?.();
+            };
+        },
+    };
+}
+// ═══════════════════════════════════════════════════════════════════════
+// The fetch and the platform tag
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * `expo/fetch` — the WinterCG fetch Expo ships. React Native's own fetch
+ * is XHR-backed and cannot give a streaming body, which is what
+ * `g.ai.chat({ stream: true })` and `g.ai.run(..., { stream: true })`
+ * return. Resolved on the first request; `globalThis.fetch` if Expo's is
+ * not there, so a bare React Native app still works for everything that
+ * is not a stream.
+ */
+export function expoFetch(injected) {
+    let impl = injected;
+    return (async (input, init) => {
+        if (!impl) {
+            const mod = await loadModule("expo/fetch");
+            const candidate = mod?.fetch;
+            impl = typeof candidate === "function" ? candidate : (i, n) => globalThis.fetch(i, n);
+        }
+        return impl(input, init);
+    });
+}
+/**
+ * The `x-client-info` platform tag: `expo-ios`, `expo-android`, `expo-web`.
+ *
+ * It is baked into the header when the client is CONSTRUCTED, so it cannot
+ * wait on a dynamic import. Pass `Platform` from `react-native` (a static
+ * import that costs an Expo app nothing) and the tag names the OS; without
+ * it the tag is the honest `expo`. Either way it is a report, never a
+ * proof — the ledger stores it as one.
+ */
+export function expoPlatformTag(platform) {
+    const os = typeof platform?.OS === "string" ? platform.OS : "";
+    return os ? `expo-${os}` : "expo";
+}
+// ═══════════════════════════════════════════════════════════════════════
+// The upload part — the picker's `{ uri }`, turned into bytes
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * W10 row 9, found by driving the Expo app: `upload()` takes the picker's
+ * `{ uri, name, type, size }`, but `expo/fetch` — the fetch this entry
+ * hands the client, and the only one that can stream an AI answer — refuses
+ * that part when its `FormData` serialises it:
+ * `Unsupported FormDataPart implementation`. React Native's own fetch reads
+ * the bytes at `uri`; Expo's will not.
+ *
+ * So the shape is converted here, before it ever reaches core `upload()`:
+ * `new File(uri)` from `expo-file-system` is a real `Blob` that carries
+ * `uri`, `name`, `type` and `size` — the three fields the presign reads,
+ * plus bytes any FormData can serialise. The picker shape therefore works
+ * through `@gemmein/sdk/expo` exactly as the docs say it does.
+ *
+ * Anything that already carries its own bytes — a `Blob`, a browser `File`,
+ * an `expo-file-system` `File` — is passed through untouched.
+ */
+export async function expoUploadPart(file, modules = {}) {
+    const part = file;
+    // Already byte-bearing: a Blob, a File, an expo-file-system File. Duck-typed
+    // rather than `instanceof Blob`, because the class a phone's runtime has is
+    // not always the one this module can see.
+    const carriesBytes = typeof part.arrayBuffer === "function" || typeof part.stream === "function" ||
+        typeof part.slice === "function" || typeof part.bytes === "function";
+    if (carriesBytes || typeof part.uri !== "string")
+        return file;
+    const injected = modules.FileSystem;
+    const mod = injected ?? (await loadModule("expo-file-system"));
+    const FileClass = mod?.File;
+    if (typeof FileClass !== "function") {
+        throw new GemmeinError({
+            status: 0,
+            code: "upload_input_unsupported",
+            message: "This upload input cannot be read on Expo — pass a Blob or an expo-file-system File; " +
+                "the picker's { uri } needs expo-file-system installed (npx expo install expo-file-system)",
+        });
+    }
+    return new FileClass(part.uri);
+}
+/**
+ * Every collection this client hands out gets the conversion above in front
+ * of its `upload`. It is wrapped on the ONE factory both spellings go
+ * through — `g.collection(name)` delegates to `g.storage.collection(name)`
+ * — so there is one seam, not two, and every other method is the core
+ * client's own, untouched.
+ */
+function wrapUploads(client, modules) {
+    const storage = client.storage;
+    const core = storage.collection.bind(client.storage);
+    storage.collection = (name, options) => {
+        const collection = core(name, options);
+        const upload = collection.upload.bind(collection);
+        collection.upload = async (file, uploadOptions) => upload(await expoUploadPart(file, modules), uploadOptions);
+        return collection;
+    };
+    return client;
+}
+// ═══════════════════════════════════════════════════════════════════════
+// createExpoGemmein — the four options, filled in
+// ═══════════════════════════════════════════════════════════════════════
+/**
+ * The Expo client. Identical to `gemmein()` in every method, because it IS
+ * `Gemmein` — the only difference is where the session is kept, how "is
+ * the app in front?" is answered, which fetch carries the bytes, and what
+ * the client tag says.
+ *
+ *   const g = createExpoGemmein({ appKey: "pk_live_..." }, { Platform });
+ *
+ * Every default is overridable: pass your own `tokenStore`, `visibility`,
+ * `fetch` or `platform` in `options` and it wins.
+ */
+export function createExpoGemmein(options, modules = {}) {
+    return wrapUploads(new Gemmein({
+        tokenStore: new SecureStoreTokenStore(options.appKey, modules.SecureStore),
+        visibility: appStateVisibility(modules.AppState),
+        fetch: expoFetch(modules.fetch),
+        platform: expoPlatformTag(modules.Platform),
+        ...options,
+    }), modules);
+}