@byokit/accounts 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## Unreleased
+
+## 0.4.0
+
+- Each catalogue row carries its billing (`subscription`, `api`); show `billingWords(p)` next to every provider you list.
+- FIX: OpenRouter (API billing) is no longer offered by default on computers; `offered()` without keys returns subscription rows only. Name it explicitly (`offer: ['openrouter']`) to keep offering it.
+- FIX: a locked-keychain read (iOS returns "User interaction is not allowed" while the phone is locked) no longer signs the person out: `keepFresh` treats it as unknown and tries later, only a refused refresh fires `onExpired`.
+- `secureStore(secure, name, options?)` passes `options` (e.g. `{ keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY }`) to every keychain get, set and delete; the default is unchanged.
+## 0.3.1
+
+- `respond(member, { instructions, input, onText })` asks ChatGPT with the member's own sign-in, the answer streaming in over an injected `fetch` (whole answer at once when the fetch can't stream); limits and lapsed sign-ins are acted on as `failed()` does.
+- FIX: a plain HTTP 429 or an undated `rate_limit_exceeded` is a temporary rate limit, not "plan doesn't include this"; a streamed error keeps its code.
+- FIX: a refresh that fails on the network before asking is reported as network trouble; a refused refresh signs the account out.
+
+## 0.3.0
+
+- FIX: `@byokit/accounts/testing` `decoy()` now requires a caller-owned root; migrate from `decoy()` to `decoy(root)` and clean up that root when done.

package/README.md

@@ -1,7 +1,7 @@
 # @byokit/accounts
 
-Sign in with the AI plan you already pay for (ChatGPT on every platform; OpenRouter on computers; Grok and GitHub
-Copilot hidden by default), inside your own app, into your app's own store: on a computer (Node, Electron), in a browser
+Sign in with the AI plan you already pay for (ChatGPT on every platform; OpenRouter on computers when an app offers it
+(API billing, never by default); Grok and GitHub Copilot hidden by default), inside your own app, into your app's own store: on a computer (Node, Electron), in a browser
 (a PWA, Electron's renderer) and on a
 phone (React Native and Expo, iOS and Android). One import; your bundler picks the platform's side
 (`package.json`'s `react-native` and `browser` conditions).
@@ -25,13 +25,22 @@ Node), into the phone's secure storage or the browser's IndexedDB:
 
 ```ts
 import * as SecureStore from 'expo-secure-store';
+import { fetch as streamingFetch } from 'expo/fetch'; // optional: React Native's fetch returns the answer at once
 import { Accounts, secureStore } from '@byokit/accounts';
 
-const accounts = new Accounts({ store: (member) => secureStore(SecureStore, `byokit.${member}`) });
+const accounts = new Accounts({ store: (member) => secureStore(SecureStore, `byokit.${member}`), fetch: streamingFetch as unknown as typeof fetch });
 const shown = await accounts.login(1, 'chatgpt'); // { state: 'waiting', via: 'code', code, url }: open url, show code
 ```
 
-Examples: [`examples/expo`](../../examples/expo) (iOS and Android bundles; Android emulator sign-in) and
+Then ask ChatGPT with that sign-in, showing streamed pieces while it runs and the returned final answer when it finishes
+(the completion can correct earlier pieces):
+
+```ts
+const answer = await accounts.respond(1, { instructions: 'Answer briefly.', input: 'Plan my day', onText: (d) => show(d) });
+show(answer);
+```
+
+Examples: [`examples/expo`](../../examples/expo) (iOS and Android bundles; Android emulator sign-in, asking, pairing) and
 [`examples/pwa`](../../examples/pwa) (browser sign-in).
 
 ## Which sign-in works where
@@ -39,7 +48,7 @@ Examples: [`examples/expo`](../../examples/expo) (iOS and Android bundles; Andro
 | | Computer (Node, Electron main) | Browser (PWA, Electron renderer) | Phone (React Native: iOS, Android) |
 |---|---|---|---|
 | ChatGPT | Its own page, straight back to this computer (port 1455); a code when asked or stuck | Device code | Device code |
-| OpenRouter | Its own page, back to this computer (Pi's flow) | Not yet | Not yet |
+| OpenRouter | Its own page, back to this computer (Pi's flow), when an app offers it (API billing, never by default) | Not yet | Not yet |
 | Grok, Copilot (hidden) | Pi's flows | No | No |
 | Where sign-ins are kept | `fileStore(path)`, sealed with Electron's `safeStorage` when given | `browserStore(name)` (IndexedDB) | `secureStore(SecureStore, name)` (Keychain, Keystore) |
 
@@ -48,10 +57,12 @@ listener on the computer the browser runs on, so it is desktop only: ChatGPT sen
 `localhost:1455`, fixed for the client this signs in as. A web page can't call ChatGPT's model endpoint itself (it
 doesn't answer other web pages), so a PWA's model calls go through the app's own server or relay.
 
-- **Catalogue** (`catalogue.json`): each provider with its terms status (`allowed`, `grey`, `partner`), a one-line reason
-  and a source. The kit labels; your app decides what to offer (`new Accounts({ offer: ['chatgpt'] })`). Without an
-  explicit `offer`, only sign-ins supported on this platform are shown; an explicit list is not platform-filtered, so
-  choose from the table above. Claude plan sign-in is never offered: Anthropic reserves it for its own apps.
+- **Catalogue** (`catalogue.json`): each provider with its billing (`subscription`, `api`) and terms status (`allowed`,
+  `grey`, `partner`), a one-line reason and a source. The kit labels; your app decides what to offer
+  (`new Accounts({ offer: ['chatgpt'] })`). Without an explicit `offer`, only subscription sign-ins supported on this
+  platform are shown: OpenRouter is API-billed and never offered by default. An explicit list is not
+  platform-filtered, so choose from the table above. Show `billingWords(p)` next to every provider you list.
+  Claude plan sign-in is never offered: Anthropic reserves it for its own apps.
 - **Sign-in**: on computers, the provider's own page by default. For ChatGPT, whose page returns to this computer's
   port 1455, the kit listens there itself, so the tab shows your app's words (`new Accounts({ app: 'My App' })`) and only once they are
   true. A code takes over when asked ("Having trouble?"), when the page never comes back, or when the port is taken by
@@ -63,11 +74,22 @@ doesn't answer other web pages), so a PWA's model calls go through the app's own
   sign-out uses its rotated token. If a cancelled sign-in finishes late, `onSignOutError` reports a failed revoke of its
   discarded credential (or it is logged when no handler is set).
 - **One person, one store**: `memoryStore()`, `fileStore(path)` (0600, the same shape as Pi's `auth.json`),
-  `secureStore(SecureStore, name)` or `browserStore(name)`; any other storage with `recordStore(load, save)`. Writes are
+  `secureStore(SecureStore, name, options?)` or `browserStore(name)`; any other storage with `recordStore(load, save)`. Writes are
   serialized within a store instance; `browserStore` also uses Web Locks across tabs for the same provider when available.
-  Never a shared fallback. Browser storage is readable by scripts on your page: avoid untrusted scripts. Using another
+  Never a shared fallback. Browser storage is readable by scripts on your page: avoid untrusted scripts. On a phone, pass
+  `{ keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY }` as `options` (to every get, set and delete) so
+  tokens never migrate to a new device through an iCloud/iTunes backup; without it Expo's default (`WHEN_UNLOCKED`)
+  applies. iOS Keychain items survive an app reinstall under the same bundle id (Android data is gone): apps that must
+  forget on reinstall keep a first-run marker outside the Keychain (e.g. `expo-file-system` or `AsyncStorage`) and, when
+  it is missing, call `accounts.logout(member, key)` for each offered key before first use, which revokes and wipes. Using another
   engine with the same seam (Pi's coding-agent `ModelRuntime`)? Override `open(member)` with an engine whose
   `credentialStore` is made with `boundStore(member, engineStore)` and whose `readCredential(id)` reads that store.
+- **Asking**: `respond(member, { instructions, input, model?, onText?, signal? })` asks ChatGPT's own answers endpoint
+  with the member's sign-in, refreshed first when due, and returns the whole text (`onText` gets each piece as it
+  streams; the returned completion is authoritative). A limit or a lapsed sign-in is acted on as `failed()` does, then
+  thrown as a `ResponseError` with the words to show and the kind acted on. Rules: [conformance fixtures](../../fixtures/README.md).
+  A web page can't call this endpoint itself (it answers no other web page): ask from the app's own server or over
+  `@byokit/link`.
 - **Limits**: `failed(member, key, error)` rests an account until the provider said (or a default), marks a plan that
   doesn't include this use, and signs out only a sign-in that no longer refreshes. `ladder()` picks the next usable
   account; `keepFresh()` refreshes ahead of expiry. Limits come from errors only; no undocumented usage endpoint is read.
@@ -75,5 +97,6 @@ doesn't answer other web pages), so a PWA's model calls go through the app's own
   `@byokit/accounts/testing` has the decoy-HOME harness and fs tracer to prove it in your own tests. `decoy(root)`
   writes only under the caller-supplied root; the caller owns its creation and cleanup.
 - **A stand-in OpenAI**: `mockOpenAI()` from `@byokit/accounts/testing` (or `node .../testing/mock-openai.ts [port]`)
-  answers device code, its page where a person types the code, token exchange, refresh and revoke, so tests and demos
-  sign in end to end with no account. Point the kit at it with `new Accounts({ authBase })`.
+  answers device code, its page where a person types the code, token exchange, refresh, revoke and streamed answers
+  (echoing the question), so tests and demos sign in and ask end to end with no account. Point the kit at it with
+  `new Accounts({ authBase, apiBase })`.

package/dist/accounts.d.ts

@@ -1,6 +1,7 @@
 import type { CredentialStore, Models } from '@earendil-works/pi-ai';
 import { type Provider } from './catalogue.ts';
 import { type Kind } from './limits.ts';
+import { ResponseError, type Ask } from './responses.ts';
 import { type EndingStore } from './stores.ts';
 import { type Why } from './words.ts';
 /** What signing in needs from an engine: Pi's `Models`, or anything shaped like it (the coding agent's `ModelRuntime`). */
@@ -62,6 +63,10 @@ export type AccountsOptions<M extends Member = Member> = {
      *  Phones and browsers sign in and sign out there; on a computer Pi's engine always calls OpenAI, and only sign-out's
      *  revoke goes here. */
     authBase?: string;
+    /** Where ChatGPT answers `respond`, for a stand-in in tests and demos. */
+    apiBase?: string;
+    /** The fetch `respond` asks with: one that streams on a phone (Expo's `expo/fetch`). Default: the platform's. */
+    fetch?: typeof fetch;
 };
 /** The ChatGPT plan behind a sign-in, from its own token: a work plan (Business, Enterprise, Edu) follows the employer's rules. */
 export declare function planOf(access: string): {
@@ -123,7 +128,11 @@ export declare class Accounts<R extends AuthHost = AuthHost, M extends Member =
      *  use is marked so. A refusal is checked: a sign-in that no longer refreshes is signed out for real, one that still
      *  does was a passing refusal and rests a few minutes (kind `overloaded`) rather than loop. Returns the kind acted on,
      *  or null for an error that is not about the account; `network` changes nothing. */
-    failed(member: M, key: string, error: string): Promise<{
+    /** Ask ChatGPT with this member's own sign-in, the answer streaming into `onText`; refreshed first when due. A
+     *  failure about the account (a limit, a lapsed sign-in) is acted on as `failed()` does, then thrown as a
+     *  ResponseError with the words to show. */
+    respond(member: M, ask: Ask): Promise<string>;
+    failed(member: M, key: string, error: string | ResponseError): Promise<{
         kind: Kind;
         until: number;
     } | null>;

package/dist/accounts.js

@@ -1,6 +1,7 @@
 import { offered, provider } from "./catalogue.js";
 import { claims, PORTABLE, portableEngine } from "./engine.js";
 import { classify, REST_MS } from "./limits.js";
+import { respond, ResponseError } from "./responses.js";
 import { memoryStore } from "./stores.js";
 import { callbackPage, clock, failure, say, signInError } from "./words.js";
 /** Phones and browsers: ChatGPT by device code, no listener. */
@@ -219,8 +220,42 @@ export class Accounts {
      *  use is marked so. A refusal is checked: a sign-in that no longer refreshes is signed out for real, one that still
      *  does was a passing refusal and rests a few minutes (kind `overloaded`) rather than loop. Returns the kind acted on,
      *  or null for an error that is not about the account; `network` changes nothing. */
+    /** Ask ChatGPT with this member's own sign-in, the answer streaming into `onText`; refreshed first when due. A
+     *  failure about the account (a limit, a lapsed sign-in) is acted on as `failed()` does, then thrown as a
+     *  ResponseError with the words to show. */
+    async respond(member, ask) {
+        const key = 'chatgpt';
+        const p = this.offer(key);
+        const rt = await this.runtime(member);
+        let access;
+        try {
+            access = (await rt.getAuth(p.pi))?.auth?.apiKey;
+        }
+        catch (e) {
+            if ([400, 401, 403].includes(e?.status)) {
+                await rt.credentialStore.delete(p.pi);
+                this.forget(member, key);
+                throw new ResponseError(say('status.needsAgain', { name: p.name }), 'signed_out');
+            }
+            throw new ResponseError('ChatGPT could not refresh its sign-in. Try again when the network is back.', 'network');
+        }
+        const c = await rt.readCredential(p.pi).catch(() => undefined);
+        if (!access || c?.type !== 'oauth')
+            throw new ResponseError(say('status.signedOut', { name: p.name }), 'signed_out');
+        try {
+            return await respond({ ...ask, access, accountId: String(c.accountId ?? ''), model: ask.model ?? p.models.strong, base: this.opts.apiBase, fetch: this.opts.fetch });
+        }
+        catch (e) {
+            if (e instanceof ResponseError && e.kind && e.kind !== 'network') {
+                const acted = await this.failed(member, key, e);
+                if (acted && acted.kind !== e.kind)
+                    throw new ResponseError(e.message, acted.kind, acted.until);
+            }
+            throw e;
+        }
+    }
     async failed(member, key, error) {
-        const c = classify(error);
+        const c = error instanceof ResponseError ? error.kind && { kind: error.kind, until: error.until } : classify(error);
         if (!c || c.kind === 'network')
             return c;
         if (c.kind === 'signed_out' && await this.recheck(member, key))
@@ -420,10 +455,14 @@ export class Accounts {
         return (await this.runtime(member)).getAuth(pi, { minOAuthValidityMs }).then(Boolean, async (e) => {
             if (offline(e))
                 return true;
-            if (e?.message !== `OAuth refresh returned a token that expires too soon for ${pi}`)
-                return false;
-            const c = await this.store(member).read(pi);
-            return c?.type === 'oauth' && c.expires > Date.now();
+            if (e?.message === `OAuth refresh returned a token that expires too soon for ${pi}`) {
+                const c = await this.store(member).read(pi);
+                return c?.type === 'oauth' && c.expires > Date.now();
+            }
+            // Only the provider refusing (400-403) counts as expiry. Anything else (a locked keychain read, storage failing)
+            // is unknown: try later, never sign the person out.
+            const status = e?.status;
+            return typeof status !== 'number' || status < 400 || status > 403;
         });
     }
     /** Refresh every signed-in account an hour ahead of expiry (call it now and then), so a sign-in never lapses while

package/dist/catalogue.d.ts

@@ -1,4 +1,6 @@
 export type Terms = 'allowed' | 'grey' | 'partner' | 'forbidden';
+/** How the person pays: their plan (`subscription`), or per-use charges to their account (`api`, never offered by default). */
+export type Billing = 'subscription' | 'api';
 /** `callbackPort`: where the provider sends the browser back after its own sign-in page, fixed for the client Pi signs in as.
  *  `revoke`: where signing out ends the sign-in on the provider's side too, for the client `clientId`. */
 export type Provider = {
@@ -13,6 +15,7 @@ export type Provider = {
     callbackPort?: number;
     clientId?: string;
     revoke?: string;
+    billing: Billing;
     terms: Terms;
     hidden: boolean;
     why: string;
@@ -20,5 +23,6 @@ export type Provider = {
 };
 export declare const PROVIDERS: Record<string, Provider>;
 export declare function provider(key: string): Provider;
-/** What an app offers: the keys it names, in its order, or every provider not hidden by default. */
+/** What an app offers: the keys it names, in its order, or every subscription provider not hidden by default.
+ *  API-billed rows are never in the default: an app offers them only by naming them. */
 export declare const offered: (keys?: readonly string[]) => Provider[];

package/dist/catalogue.js

@@ -1,7 +1,8 @@
-// The AI accounts a person can bring, by the name they know, with each provider's terms status as data (catalogue.json,
-// readable from Kotlin too). The kit labels; the app decides what to offer. Claude plan sign-in is absent on purpose:
-// Anthropic reserves it for its own apps, so no app can wire it by mistake. Meta and Kimi are left out too (a
-// competitor by the owner's choice; Kimi refuses anything but coding agents).
+// The AI accounts a person can bring, by the name they know, with each provider's billing and terms status as data
+// (catalogue.json, readable from Kotlin too). The kit labels; the app decides what to offer. API-billed rows are never
+// offered by default; an app names them explicitly. Claude plan sign-in is absent on purpose: Anthropic reserves it for
+// its own apps, so no app can wire it by mistake. Meta and Kimi are left out too (a competitor by the owner's choice;
+// Kimi refuses anything but coding agents).
 import CATALOGUE from './catalogue.json' with { type: 'json' };
 export const PROVIDERS = Object.fromEntries(Object.entries(CATALOGUE).map(([key, p]) => [key, { key, ...p }]));
 export function provider(key) {
@@ -10,5 +11,6 @@ export function provider(key) {
         throw Object.assign(new Error('no such AI account'), { status: 404 });
     return p;
 }
-/** What an app offers: the keys it names, in its order, or every provider not hidden by default. */
-export const offered = (keys) => keys ? keys.map(provider) : Object.values(PROVIDERS).filter((p) => !p.hidden);
+/** What an app offers: the keys it names, in its order, or every subscription provider not hidden by default.
+ *  API-billed rows are never in the default: an app offers them only by naming them. */
+export const offered = (keys) => keys ? keys.map(provider) : Object.values(PROVIDERS).filter((p) => !p.hidden && p.billing === 'subscription');

package/dist/catalogue.json

@@ -10,6 +10,7 @@
         "callbackPort": 1455,
         "clientId": "app_EMoamEEZ73f0CkXaXp7hrann",
         "revoke": "https://auth.openai.com/oauth/revoke",
+        "billing": "subscription",
         "terms": "grey",
         "hidden": false,
         "why": "Signs in through Codex's own sign-in. OpenAI documents it for Codex, not for other apps, and has endorsed one other app using it.",
@@ -22,6 +23,7 @@
         "models": {
             "strong": "moonshotai/kimi-k2.6"
         },
+        "billing": "api",
         "terms": "allowed",
         "hidden": false,
         "why": "Documented sign-in for any app, no registration. Pay-as-you-go credits, not a subscription.",
@@ -34,6 +36,7 @@
         "models": {
             "strong": "grok-4.7"
         },
+        "billing": "subscription",
         "terms": "partner",
         "hidden": true,
         "why": "xAI allows plan sign-in only in apps it has partnered with.",
@@ -46,6 +49,7 @@
         "models": {
             "strong": "gpt-5.4"
         },
+        "billing": "subscription",
         "terms": "partner",
         "hidden": true,
         "why": "GitHub allows Copilot sign-in only in apps it has partnered with; this uses VS Code's client.",

package/dist/engine.js

@@ -82,7 +82,7 @@ export function portableEngine(credentials, { base = 'https://auth.openai.com' }
     };
     const tokens = async (what, r) => {
         if (r.status < 200 || r.status > 299)
-            throw new Error(`OpenAI Codex token ${what} failed (${r.status})`);
+            throw Object.assign(new Error(`OpenAI Codex token ${what} failed (${r.status})`), { status: r.status });
         return credentialOf(json(r.body));
     };
     const refresh = async (c) => {
@@ -92,7 +92,7 @@ export function portableEngine(credentials, { base = 'https://auth.openai.com' }
             return await tokens('refresh', await post('/oauth/token', { grant_type: 'refresh_token', refresh_token: c.refresh, client_id: CLIENT_ID }, true, stop.signal));
         }
         catch (e) {
-            throw new Error(`OAuth refresh failed for openai-codex: ${e?.message ?? e}`);
+            throw Object.assign(new Error(`OAuth refresh failed for openai-codex: ${e?.message ?? e}`), { status: e?.status });
         }
         finally {
             clearTimeout(t);

package/dist/limits.js

@@ -4,9 +4,7 @@ export const REST_MS = { rate_limit: 60 * 60_000, overloaded: 5 * 60_000, signed
 export function classify(error) {
     const m = /try again in ~?(\d+)\s*(min|h)/i.exec(error);
     const until = m ? Date.now() + Number(m[1]) * (m[2].toLowerCase() === 'h' ? 3_600_000 : 60_000) : 0;
-    // ChatGPT words "your plan doesn't include this" (usage_not_included) like a limit, but with no time to come back.
-    // ponytail: told apart by the missing "try again"; a real limit always says when it resets.
-    if (/usage limit/i.test(error) && !m)
+    if (/your plan doesn't include/i.test(error))
         return { kind: 'not_included', until };
     if (/usage limit|rate.?limit|quota|too many requests|\b429\b/i.test(error))
         return { kind: 'rate_limit', until };

package/dist/portable.d.ts

@@ -1,6 +1,7 @@
 export { Accounts, planOf, portable, type AccountsOptions, type AuthHost, type Loopback, type Member, type Platform, type SignIn, type Status } from './accounts.ts';
-export { PROVIDERS, offered, provider, type Provider, type Terms } from './catalogue.ts';
+export { PROVIDERS, offered, provider, type Billing, type Provider, type Terms } from './catalogue.ts';
 export { PORTABLE, claims, credentialOf, devicePoll, deviceStart, portableEngine, type EngineOptions, type Poll } from './engine.ts';
 export { REST_MS, classify, type Kind } from './limits.ts';
+export { ResponseError, limitResponse, respond, sseReader, type Ask } from './responses.ts';
 export { browserStore, memoryStore, recordStore, secureStore, type SecureStoreLike } from './stores.ts';
-export { WORDS, callbackPage, clock, failure, say, signInError, type WordKey, type Why } from './words.ts';
+export { WORDS, billingWords, callbackPage, clock, failure, say, signInError, type WordKey, type Why } from './words.ts';

package/dist/portable.js

@@ -4,5 +4,6 @@ export { Accounts, planOf, portable } from "./accounts.js";
 export { PROVIDERS, offered, provider } from "./catalogue.js";
 export { PORTABLE, claims, credentialOf, devicePoll, deviceStart, portableEngine } from "./engine.js";
 export { REST_MS, classify } from "./limits.js";
+export { ResponseError, limitResponse, respond, sseReader } from "./responses.js";
 export { browserStore, memoryStore, recordStore, secureStore } from "./stores.js";
-export { WORDS, callbackPage, clock, failure, say, signInError } from "./words.js";
+export { WORDS, billingWords, callbackPage, clock, failure, say, signInError } from "./words.js";

package/dist/responses.d.ts

@@ -0,0 +1,39 @@
+import { type Kind } from './limits.ts';
+/** A failed answer: the words to show, and the kind an app acts on (null for one that isn't about the account). */
+export declare class ResponseError extends Error {
+    kind: Kind | null;
+    /** When the provider said to come back (epoch ms), or 0. */
+    until: number;
+    constructor(message: string, kind: Kind | null, until?: number);
+}
+/** A ChatGPT HTTP error as the kind, when to come back, and the message (fixtures/conformance/limit-responses.json). */
+export declare function limitResponse(status: number, body: string, now?: number): {
+    kind: Kind | null;
+    until: number | null;
+    message: string;
+};
+/** Reads a streamed answer (fixtures/conformance/sse.json): `push` each piece as it arrives, `end` for the whole text.
+ *  An error event throws a ResponseError. */
+export declare function sseReader(onText?: (delta: string) => void): {
+    push(chunk: string): void;
+    end(): string;
+};
+export type Ask = {
+    /** What the model is told to be. */
+    instructions: string;
+    /** The person's words. */
+    input: string;
+    /** Default: the provider's strong model in the catalogue. */
+    model?: string;
+    /** Each piece of the answer as it streams. */
+    onText?: (delta: string) => void;
+    signal?: AbortSignal;
+};
+/** Ask ChatGPT with a signed-in token. `fetch`: pass one that streams (Expo's `expo/fetch`); any fetch works. */
+export declare function respond(o: Ask & {
+    access: string;
+    accountId: string;
+    model: string;
+    base?: string;
+    fetch?: typeof fetch;
+}): Promise<string>;

package/dist/responses.js

@@ -0,0 +1,114 @@
+// One question to ChatGPT, answered as it streams, with fetch alone: what a phone or browser app asks the model with
+// the sign-in it holds. Rules are the shared fixtures (sse.json, limit-responses.json). A fetch that can't stream (React
+// Native's own) still works: the whole answer arrives at once. Expo's `fetch` from 'expo/fetch' streams.
+import { classify } from "./limits.js";
+const limitKind = (code) => code === 'usage_not_included' ? 'not_included'
+    : /^(usage_limit_reached|rate_limit_exceeded)$/.test(code) ? 'rate_limit' : null;
+/** A failed answer: the words to show, and the kind an app acts on (null for one that isn't about the account). */
+export class ResponseError extends Error {
+    kind;
+    /** When the provider said to come back (epoch ms), or 0. */
+    until;
+    constructor(message, kind, until = 0) { super(message); this.kind = kind; this.until = until; }
+}
+/** A ChatGPT HTTP error as the kind, when to come back, and the message (fixtures/conformance/limit-responses.json). */
+export function limitResponse(status, body, now = Date.now()) {
+    let err = {};
+    try {
+        err = JSON.parse(body)?.error ?? {};
+    }
+    catch { }
+    const code = String(err.code || err.type || '');
+    if (limitKind(code) || status === 429) {
+        const resets = typeof err.resets_at === 'number' ? err.resets_at * 1000 : null;
+        const message = 'You have hit your ChatGPT usage limit' + (err.plan_type ? ` (${String(err.plan_type).toLowerCase()} plan)` : '') + '.' +
+            (resets ? ` Try again in ~${Math.max(0, Math.round((resets - now) / 60_000))} min.` : '');
+        return { kind: limitKind(code) ?? 'rate_limit', until: resets, message };
+    }
+    const kind = status === 401 || status === 403 ? 'signed_out' : [500, 502, 503, 504].includes(status) ? 'overloaded' : null;
+    return { kind, until: null, message: (typeof err.message === 'string' && err.message) || body || 'Request failed' };
+}
+/** Reads a streamed answer (fixtures/conformance/sse.json): `push` each piece as it arrives, `end` for the whole text.
+ *  An error event throws a ResponseError. */
+export function sseReader(onText) {
+    let buffer = '', text = '', completed;
+    let done = false;
+    const event = (block) => {
+        const data = block.split('\n').filter((l) => l.startsWith('data:')).map((l) => l.slice(5).replace(/^ /, '')).join('\n');
+        if (!data || data === '[DONE]')
+            return;
+        let e;
+        try {
+            e = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        if (e.type === 'response.output_text.delta' && typeof e.delta === 'string') {
+            text += e.delta;
+            onText?.(e.delta);
+        }
+        if (e.type === 'response.completed') {
+            done = true;
+            if (Array.isArray(e.response?.output))
+                completed = e.response.output.flatMap((o) => o?.content ?? []).filter((c) => c?.type === 'output_text').map((c) => c.text ?? '').join('');
+        }
+        const failed = e.type === 'error' ? e : e.type === 'response.failed' ? e.response?.error : undefined;
+        if (failed) {
+            const message = String(failed.message ?? 'Request failed');
+            const c = classify(message);
+            throw new ResponseError(message, limitKind(String(failed.code ?? failed.type ?? '')) ?? c?.kind ?? null, c?.until ?? 0);
+        }
+    };
+    const drain = (final) => {
+        const blocks = buffer.replace(/\r\n/g, '\n').split('\n\n');
+        buffer = final ? '' : blocks.pop();
+        for (const b of blocks)
+            event(b);
+    };
+    return {
+        push(chunk) { buffer += chunk; drain(false); },
+        end() {
+            drain(true);
+            if (!done)
+                throw new ResponseError('ChatGPT stopped before completing its answer.', 'network');
+            if (completed !== undefined && completed !== text) {
+                if (completed.startsWith(text))
+                    onText?.(completed.slice(text.length));
+                return completed;
+            }
+            return text;
+        },
+    };
+}
+/** Ask ChatGPT with a signed-in token. `fetch`: pass one that streams (Expo's `expo/fetch`); any fetch works. */
+export async function respond(o) {
+    const res = await (o.fetch ?? fetch)(`${o.base ?? 'https://chatgpt.com/backend-api'}/codex/responses`, {
+        method: 'POST', signal: o.signal,
+        headers: {
+            'content-type': 'application/json', accept: 'text/event-stream', authorization: `Bearer ${o.access}`,
+            'chatgpt-account-id': o.accountId, 'OpenAI-Beta': 'responses=experimental', originator: 'byokit',
+        },
+        body: JSON.stringify({
+            model: o.model, store: false, stream: true, instructions: o.instructions,
+            input: [{ role: 'user', content: [{ type: 'input_text', text: o.input }] }],
+            text: { verbosity: 'low' }, reasoning: { effort: 'none' },
+        }),
+    });
+    if (!res.ok) {
+        const e = limitResponse(res.status, await res.text().catch(() => ''));
+        throw new ResponseError(e.message, e.kind, e.until ?? 0);
+    }
+    const reader = sseReader(o.onText);
+    const body = res.body;
+    if (body?.getReader && typeof TextDecoder !== 'undefined') {
+        const r = body.getReader();
+        const decoder = new TextDecoder();
+        for (let c = await r.read(); !c.done; c = await r.read())
+            reader.push(typeof c.value === 'string' ? c.value : decoder.decode(c.value, { stream: true }));
+    }
+    else {
+        reader.push(await res.text()); // a fetch that can't stream: the whole answer at once
+    }
+    return reader.end();
+}

package/dist/stores.d.ts

@@ -9,16 +9,19 @@ export type EndingStore = CredentialStore & {
  *  re-reads first, so a sign-in that took minutes never overwrites a provider that changed meanwhile. */
 export declare function recordStore(load: () => Promise<Record>, save: (data: Record) => Promise<void>): EndingStore;
 export declare function memoryStore(): CredentialStore;
-/** The parts of `expo-secure-store` this uses (Keychain on iOS, Keystore-encrypted on Android); pass the module itself. */
+/** The parts of `expo-secure-store` this uses (Keychain on iOS, Keystore-encrypted on Android); pass the module itself.
+ *  Every method takes the same optional `options` (e.g. `{ keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY }`). */
 export type SecureStoreLike = {
-    getItemAsync(key: string): Promise<string | null>;
-    setItemAsync(key: string, value: string): Promise<void>;
-    deleteItemAsync(key: string): Promise<void>;
+    getItemAsync(key: string, options?: object): Promise<string | null>;
+    setItemAsync(key: string, value: string, options?: object): Promise<void>;
+    deleteItemAsync(key: string, options?: object): Promise<void>;
 };
 /** One person's sign-ins in the phone's secure storage: `secureStore(SecureStore, 'byokit.1')`. Keys may hold letters,
  *  digits, `.`, `-` and `_`. The record is split into pieces under the 2048 bytes expo-secure-store warns about, written
- *  as a new generation, then `name` is pointed at it: a crash mid-write leaves the old sign-ins whole. */
-export declare function secureStore(secure: SecureStoreLike, name: string): CredentialStore;
+ *  as a new generation, then `name` is pointed at it: a crash mid-write leaves the old sign-ins whole. `options` (e.g.
+ *  `{ keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY }`) is passed to every get, set and delete;
+ *  without it Expo's default (`WHEN_UNLOCKED`) applies. */
+export declare function secureStore(secure: SecureStoreLike, name: string, options?: object): CredentialStore;
 /** One person's sign-ins in the browser's IndexedDB (a PWA, or Electron's renderer), under `name`. A browser has no
  *  keychain: anything running on this page could read them, so keep the page free of scripts you don't control. */
 export declare function browserStore(name: string, db?: string): EndingStore;

package/dist/stores.js

@@ -40,14 +40,16 @@ export function memoryStore() {
 }
 /** One person's sign-ins in the phone's secure storage: `secureStore(SecureStore, 'byokit.1')`. Keys may hold letters,
  *  digits, `.`, `-` and `_`. The record is split into pieces under the 2048 bytes expo-secure-store warns about, written
- *  as a new generation, then `name` is pointed at it: a crash mid-write leaves the old sign-ins whole. */
-export function secureStore(secure, name) {
-    const head = async () => { const [gen = '0', n = '0'] = (await secure.getItemAsync(name))?.split(':') ?? []; return { gen: Number(gen), n: Number(n) }; };
+ *  as a new generation, then `name` is pointed at it: a crash mid-write leaves the old sign-ins whole. `options` (e.g.
+ *  `{ keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY }`) is passed to every get, set and delete;
+ *  without it Expo's default (`WHEN_UNLOCKED`) applies. */
+export function secureStore(secure, name, options) {
+    const head = async () => { const [gen = '0', n = '0'] = (await secure.getItemAsync(name, options))?.split(':') ?? []; return { gen: Number(gen), n: Number(n) }; };
     const load = async () => {
         const { gen, n } = await head();
         let text = '';
         for (let i = 0; i < n; i++)
-            text += (await secure.getItemAsync(`${name}.${gen}.${i}`)) ?? '';
+            text += (await secure.getItemAsync(`${name}.${gen}.${i}`, options)) ?? '';
         return text ? JSON.parse(text) : {};
     };
     const save = async (data) => {
@@ -55,13 +57,13 @@ export function secureStore(secure, name) {
         const gen = old.gen + 1;
         const parts = (Object.keys(data).length ? JSON.stringify(data) : '').match(/[\s\S]{1,1800}/g) ?? [];
         for (const [i, part] of parts.entries())
-            await secure.setItemAsync(`${name}.${gen}.${i}`, part);
-        await secure.setItemAsync(name, `${gen}:${parts.length}`);
+            await secure.setItemAsync(`${name}.${gen}.${i}`, part, options);
+        await secure.setItemAsync(name, `${gen}:${parts.length}`, options);
         for (let i = 0; i < old.n; i++)
-            await secure.deleteItemAsync(`${name}.${old.gen}.${i}`);
+            await secure.deleteItemAsync(`${name}.${old.gen}.${i}`, options);
         // Leftovers of a write that crashed at this generation before.
-        for (let i = parts.length; (await secure.getItemAsync(`${name}.${gen}.${i}`)) !== null; i++)
-            await secure.deleteItemAsync(`${name}.${gen}.${i}`);
+        for (let i = parts.length; (await secure.getItemAsync(`${name}.${gen}.${i}`, options)) !== null; i++)
+            await secure.deleteItemAsync(`${name}.${gen}.${i}`, options);
     };
     return recordStore(load, save);
 }

package/dist/testing/mock-openai.d.ts

@@ -23,6 +23,11 @@ export declare function mockOpenAI({ port, host, plan, email, expiresIn, log }?:
         expiresIn: number;
         /** Drop this many device-code polls on the floor, as a phone does to a backgrounded app. */
         dropPolls: number;
+        /** Answer the next question with this HTTP error instead (a limit, a lapsed sign-in), then answer normally. */
+        fail: {
+            status: number;
+            body: string;
+        } | undefined;
     };
     approve: (userCode: string, deny?: boolean) => boolean;
     /** The code most recently handed out. */

package/dist/testing/mock-openai.js

@@ -1,5 +1,6 @@
 // OpenAI's sign-in, stood in for: device code, its page where a person types the code, token exchange and refresh
-// (rotating), revoke, and the same CORS answer the real endpoints give, so a web page, a phone app or a test signs in
+// (rotating), revoke, ChatGPT's streamed answers (`/codex/responses`, echoing the question), and the same CORS answer the
+// real sign-in endpoints give (the answers endpoint, like the real one, answers no web page), so a web page, a phone app or a test signs in
 // end to end with no account and no real network. Run it alone for a demo or an emulator:
 //   node packages/accounts/src/testing/mock-openai.ts [port]      (21455 by default, never ChatGPT's own 1455)
 import { createServer } from 'node:http';
@@ -23,11 +24,15 @@ export async function mockOpenAI({ port = 0, host = '127.0.0.1', plan = 'plus',
         expiresIn,
         /** Drop this many device-code polls on the floor, as a phone does to a backgrounded app. */
         dropPolls: 0,
+        /** Answer the next question with this HTTP error instead (a limit, a lapsed sign-in), then answer normally. */
+        fail: undefined,
     };
+    const accessOf = new Map(); // refresh token → the access token issued with it
     const issue = () => {
         const refresh = `rt_${++issued}`;
         state.live.add(refresh);
-        return { access_token: mockJwt(plan, email, issued), refresh_token: refresh, expires_in: state.expiresIn, id_token: 'x' };
+        accessOf.set(refresh, mockJwt(plan, email, issued));
+        return { access_token: accessOf.get(refresh), refresh_token: refresh, expires_in: state.expiresIn, id_token: 'x' };
     };
     const approve = (userCode, deny = false) => {
         const c = codes.get(userCode.trim().toUpperCase());
@@ -86,6 +91,23 @@ export async function mockOpenAI({ port = 0, host = '127.0.0.1', plan = 'plus',
                 if (state.refuse || !state.live.delete(form.get('refresh_token') ?? ''))
                     return send(401, { error: { code: 'refresh_token_reused', message: 'invalid_grant' } });
                 return send(200, issue());
+            case '/codex/responses': {
+                const bearer = req.headers.authorization?.replace(/^Bearer /, '');
+                if (state.fail) {
+                    const f = state.fail;
+                    state.fail = undefined;
+                    return send(f.status, f.body);
+                }
+                if (![...state.live].some((r) => accessOf.get(r) === bearer) || req.headers['chatgpt-account-id'] !== 'acct-1')
+                    return send(401, { error: { message: 'Provided authentication token is expired. Please try signing in again.' } });
+                const text = `You said: ${json().input?.[0]?.content?.[0]?.text ?? ''}`;
+                res.writeHead(200, { 'content-type': 'text/event-stream' });
+                for (const delta of text.match(/[\s\S]{1,4}/g) ?? []) {
+                    res.write(`event: response.output_text.delta\ndata: ${JSON.stringify({ type: 'response.output_text.delta', delta })}\n\n`);
+                    await new Promise((r) => setTimeout(r, 5));
+                }
+                return res.end('event: response.completed\ndata: {"type":"response.completed","response":{"status":"completed"}}\n\ndata: [DONE]\n\n');
+            }
             case '/oauth/revoke':
                 state.live.delete(json().token);
                 return send(200, {});

package/dist/words.d.ts

@@ -1,4 +1,5 @@
 import WORDS from './words.json';
+import type { Provider } from './catalogue.ts';
 export type WordKey = keyof typeof WORDS;
 export { WORDS };
 /** A sentence with its `{slots}` filled. */
@@ -8,6 +9,8 @@ export declare const clock: (t: number) => string;
 /** Why a sign-in failed, from the engine's own error. */
 export type Why = 'expired' | 'declined' | 'offline' | 'deviceCodeOff' | 'busy' | 'tooLong' | 'failed';
 export declare function failure(error: string): Why;
+/** What the person pays, in one plain sentence to show next to the provider. */
+export declare const billingWords: (p: Provider) => string;
 /** A failed sign-in in one plain sentence with one next step. */
 export declare const signInError: (name: string, error: string) => string;
 /** The app's own page for the browser tab a provider sends back: it says how it really went, never "success" before it is. */

package/dist/words.js

@@ -20,6 +20,8 @@ export function failure(error) {
         return 'deviceCodeOff';
     return 'failed';
 }
+/** What the person pays, in one plain sentence to show next to the provider. */
+export const billingWords = (p) => say(`billing.${p.billing}`, { name: p.name, company: p.company });
 /** A failed sign-in in one plain sentence with one next step. */
 export const signInError = (name, error) => say(`signIn.${failure(error)}`, { name });
 /** The app's own page for the browser tab a provider sends back: it says how it really went, never "success" before it is. */

package/dist/words.json

@@ -18,6 +18,8 @@
     "status.signedOut": "{name} isn't signed in yet.",
     "status.needsAgain": "{name} needs you to sign in again.",
     "terms.grey": "Uses your {name} plan. {company} may change this at any time.",
+    "billing.subscription": "Uses your {name} plan.",
+    "billing.api": "Charged per use to your {company} account, not a plan.",
     "status.notIncluded": "Your {name} plan doesn't include this yet.",
     "callback.done": "You're signed in. You can go back to {app} now.",
     "callback.declined": "No problem. Nothing was changed. You can go back to {app}.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/accounts",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Sign in with the AI plan you already pay for, into your app's own store.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,7 +35,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "prepack": "tsc -b"