@byokit/accounts 0.3.0 → 0.3.1

package/README.md

@@ -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
@@ -68,6 +77,12 @@ doesn't answer other web pages), so a PWA's model calls go through the app's own
   Never a shared fallback. Browser storage is readable by scripts on your page: avoid untrusted scripts. 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 +90,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))

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

@@ -2,5 +2,6 @@ export { Accounts, planOf, portable, type AccountsOptions, type AuthHost, type L
 export { PROVIDERS, offered, provider, 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';

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";

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/accounts",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Sign in with the AI plan you already pay for, into your app's own store.",
   "license": "Apache-2.0",
   "type": "module",