@byokit/accounts 0.3.1 → 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).
@@ -48,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) |
 
@@ -57,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
@@ -72,9 +74,14 @@ 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

package/dist/accounts.js

@@ -455,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/portable.d.ts

@@ -1,7 +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

@@ -6,4 +6,4 @@ export { PORTABLE, claims, credentialOf, devicePoll, deviceStart, portableEngine
 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/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/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.1",
+  "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"