aisubs 0.1.0 → 0.3.0

package/README.md

@@ -1,543 +1,618 @@
 <table>
   <tr>
     <td><img src="./dashboard/public/aisubs-mark.svg" alt="AISubs icon" width="72"></td>
-    <td>
-      <h1>AISubs</h1>
-      <strong>Connect your AI subscriptions. Use them anywhere.</strong>
-    </td>
+    <td><h1>AISubs</h1><strong>Connect your AI subscriptions. Use them anywhere.</strong></td>
   </tr>
 </table>
 
-Connect once, then use your subscriptions through an SDK in your app, a local
-API, cURL, or any compatible tool.
+AISubs connects provider accounts once and exposes each account through a local,
+account-scoped API. Every generative account has an OpenAI-compatible surface,
+while native Responses, Anthropic Messages, Google `generateContent`, Realtime,
+and provider-specific endpoints remain available. Use it from an SDK, cURL, or
+an app that accepts a custom API base URL.
 
 <p align="center">
-  <img src="./public/aisubs-dashboard.png" alt="AISubs dashboard showing connected accounts" width="100%" />
+  <img src="./public/aisubs-dashboard.png" alt="AI Subs dashboard with provider connections and local API access" width="100%" />
 </p>
 
 <p align="center">
-  <img src="./public/aisubs-chatgpt-account.png" alt="AISubs ChatGPT account details showing plan, usage, and integration examples" width="33%" />
-  <img src="./public/aisubs-grok-account.png" alt="AISubs Grok account details showing plan, usage, and integration examples" width="33%" />
-  <img src="./public/aisubs-copilot-account.png" alt="AISubs GitHub Copilot account details showing credits and integration examples" width="33%" />
+  <img src="./public/aisubs-chatgpt-account.png" alt="AISubs ChatGPT demo account details" width="100%" />
 </p>
 
-> AISubs keeps credentials on your computer. It collects no telemetry, analytics, request logs, or activity history.
+<p align="center">
+  <img src="./public/aisubs-copilot-account.png" alt="AISubs GitHub Copilot demo account details" width="100%" />
+</p>
+
+<p align="center">
+  <img src="./public/aisubs-grok-account.png" alt="AISubs Grok demo account details" width="100%" />
+</p>
+
+> Credentials, API keys, and requests remain on your computer. AISubs collects no
+> telemetry or analytics. The dashboard keeps up to 200 redacted account request logs in memory for debugging.
 
 ## Quick start
 
+AISubs requires [Node.js 24 or newer](https://nodejs.org/en/download/). Run it
+without adding it to a project:
+
 ```bash
-nubx aisubs dashboard       # Nub (recommended)
-npx aisubs dashboard        # npm
-pnpm exec aisubs dashboard  # pnpm
-bunx aisubs dashboard       # Bun
+nubx aisubs@latest dashboard       # Nub
+npx aisubs@latest dashboard        # npm
+pnpm dlx aisubs@latest dashboard   # pnpm
+bunx aisubs@latest dashboard       # Bun
 ```
 
-Click **Add account**, choose a provider, complete sign-in, and give the
-account a local name such as `personal` or `work`.
+The terminal prints only the local dashboard URL. Open it, click **Add account**,
+and complete the provider sign-in. The dashboard manages the persistent local API
+key: reveal it, copy it, or deliberately regenerate it there.
+
+The default URL is `http://127.0.0.1:4319`. Credentials and the API key are stored
+under `~/.aisubs` and reused on later starts.
 
-## The idea
+Supported subscription/account providers are ChatGPT, Claude, GitHub Copilot,
+Grok, OpenCode Go, and OpenCode Zen. Google `generateContent` is a supported
+wire protocol only for Google models surfaced by one of those connected
+providers; AISubs does not connect or claim a Google subscription account.
 
-1. Connect a provider account and give it a local name, such as `personal`.
-2. Ask AISubs which models and request format that account supports.
-3. Send the provider-native request through that account.
+## Use an account from any compatible app
 
-One provider can have many accounts:
+Open an account in the dashboard and copy its base URL:
 
 ```text
-ChatGPT / personal
-ChatGPT / work
-Claude  / team
+http://127.0.0.1:4319/aisubs/PROVIDER/ACCOUNT/v1
 ```
 
-AISubs never silently switches accounts. Your application chooses the account
-for each request.
-
-## Providers
-
-| Provider       | ID             | Sign-in                | Request format              |
-| -------------- | -------------- | ---------------------- | --------------------------- |
-| ChatGPT        | `chatgpt`      | Browser or device code | Responses                   |
-| Claude         | `claude`       | Browser                | Anthropic Messages          |
-| GitHub Copilot | `copilot`      | Device code            | Read from the model catalog |
-| Grok           | `grok`         | Device code            | Read from the model catalog |
-| OpenCode Go    | `opencode-go`  | API key                | Read from the model catalog |
-| OpenCode Zen   | `opencode-zen` | API key                | Read from the model catalog |
+Then configure the app with:
 
-Provider model lists and protocols can change. Discover models at runtime and
-pin the AISubs version your application has tested.
+```text
+API base URL: the account URL copied from AISubs
+API key:      the persistent key shown on the AISubs dashboard
+Model:        an exact model ID shown for that account
+```
 
-## Fastest start: direct Node.js
+For apps configured with environment variables:
 
-This is the simplest integration. It needs no local server and no AISubs API
-key.
+```bash
+export OPENAI_BASE_URL="http://127.0.0.1:4319/aisubs/grok/personal/v1"
+export OPENAI_API_KEY="aisubs_..."
+```
 
-### 1. Create AISubs once
+AISubs removes its local key before forwarding a request and adds only the
+selected account's provider credential.
+
+## Desktop app examples
+
+Keep AISubs running, then give the app the three values from the connected
+account: its base URL, the AISubs API key, and an exact model ID.
+
+### [Handy](https://handy.computer/download) (macOS)
+
+Open **Post Process** and set:
+
+| Handy field | Value                                                    |
+| ----------- | -------------------------------------------------------- |
+| Provider    | `Custom`                                                 |
+| Base URL    | `http://127.0.0.1:4319/aisubs/chatgpt/default/v1`        |
+| API Key     | Your `aisubs_...` key from the AISubs dashboard          |
+| Model       | An exact Dashboard model ID, for example `gpt-5.6-terra` |
+
+Click Handy’s refresh button beside **Model**, select the model, then choose a
+prompt and test it. Replace `chatgpt/default` with the provider and account
+segment copied from your AISubs dashboard when using a different account.
+
+### [Raycast](https://www.raycast.com/download) AI custom provider
+
+Create or edit `~/.config/raycast/ai/providers.yaml` and add a provider like
+this. Keep the API key private—use the value from your AISubs dashboard, never
+one copied from an example or screenshot.
+
+```yaml
+providers:
+  - id: ai-subs
+    name: AI Subs
+    base_url: http://127.0.0.1:4319/aisubs/chatgpt/default/v1
+    api_keys:
+      default: aisubs_REPLACE_WITH_YOUR_DASHBOARD_KEY
+    models:
+      - id: gpt-5.6-terra
+        name: AISubs GPT-5.6 Terra
+        context: 272000
+        description: ChatGPT subscription via AISubs
+        abilities:
+          vision:
+            supported: true
+          system_message:
+            supported: true
+          tools:
+            supported: true
+          reasoning_effort:
+            supported: true
+```
 
-```js
-// subscriptions.js
-import { chatGptProvider, createSubscriptionAuth } from "aisubs";
+Restart Raycast after saving. Replace the base URL, model ID, context, and
+abilities with the values shown for your connected account. Do not enable an
+ability that the selected model does not report.
+
+[Cline](https://cline.bot/) also accepts a custom OpenAI-compatible endpoint;
+use the same base URL, local AISubs key, and model ID. Exact settings labels can
+change between client releases, so the account dashboard remains the source of
+truth for the three values.
+
+### Compatibility contract
+
+Use Chat Completions when an app offers only an “OpenAI-compatible” provider.
+AISubs discovers the selected model's native protocol and translates the
+request and response when necessary. Calling a model's native protocol remains
+a pass-through, which preserves provider-specific fields and streaming events.
+
+| Integration path                   | Example full URL                                                                       | Request example                         |
+| ---------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------- |
+| OpenAI Responses                   | `http://127.0.0.1:4319/aisubs/chatgpt/default/v1/responses`                            | `POST /responses`                       |
+| OpenAI-compatible Chat Completions | `http://127.0.0.1:4319/aisubs/chatgpt/default/v1/chat/completions`                     | `POST /chat/completions`                |
+| Anthropic Messages                 | `http://127.0.0.1:4319/aisubs/claude/default/v1/messages`                              | `POST /messages`                        |
+| Google generateContent             | `http://127.0.0.1:4319/aisubs/opencode-zen/default/v1/models/MODEL_ID:generateContent` | `POST /models/MODEL_ID:generateContent` |
+| Model discovery                    | `http://127.0.0.1:4319/aisubs/chatgpt/default/v1/models`                               | `GET /models`                           |
+| Model details                      | `http://127.0.0.1:4319/aisubs/chatgpt/default/v1/models/MODEL_ID`                      | `GET /models/MODEL_ID`                  |
+| OpenAI Realtime                    | `ws://127.0.0.1:4319/aisubs/PROVIDER/ACCOUNT/v1/realtime?model=MODEL_ID`               | WebSocket                               |
+
+Replace the provider, account (`default`), and model ID with the values shown
+for your connected account in the AISubs dashboard.
+
+Cross-protocol translation covers text and system messages, streaming, function
+tools and tool results, image/file/audio input where both protocols support it,
+JSON-schema output, reasoning effort, stop conditions, and usage including
+cached and reasoning tokens. If a feature has no safe equivalent, AISubs returns
+an explicit `unsupported_feature` error instead of silently dropping it.
+
+Provider-native routes—including embeddings, image/audio generation, batches,
+files, and Realtime—are forwarded when that connected provider exposes them.
+AISubs cannot add a capability that the provider, subscription, or selected
+model does not have. Native requests preserve provider-specific cache controls;
+translated requests preserve shared fields and cache-usage counters. Other than
+Responses-to-Chat streaming, cross-protocol streams may be emitted after the
+native response completes; use the native endpoint when event-level streaming
+or provider-specific fields matter.
+
+## SDK examples
+
+Set the key once for the shell running your client:
 
-export const subscriptions = createSubscriptionAuth({
-  providers: [chatGptProvider()],
-});
+```bash
+export AISUBS_API_KEY="aisubs_..."
 ```
 
-By default, credentials are stored at `~/.aisubs/credentials.json`.
+<details>
+<summary><strong>Official OpenAI JavaScript SDK: Responses and Chat Completions</strong></summary>
 
-Keep this object in trusted backend code. Do not send it to a browser.
+Install:
 
-### 2. Connect an account
+```bash
+nub install openai
+npm install openai
+pnpm add openai
+bun add openai
+```
 
 ```js
-import { subscriptions } from "./subscriptions.js";
-
-const account = subscriptions.account("chatgpt", "personal");
+import OpenAI from "openai";
 
-if (!(await account.status()).authenticated) {
-  const login = await account.signIn();
+const client = new OpenAI({
+  baseURL: "http://127.0.0.1:4319/aisubs/chatgpt/personal/v1",
+  apiKey: process.env.AISUBS_API_KEY,
+});
 
-  if (login.prompt.mode === "browser") {
-    console.log("Open:", login.prompt.authorizationUri);
-  }
-  if (login.prompt.mode === "device") {
-    console.log("Open:", login.prompt.verificationUri);
-    console.log("Code:", login.prompt.userCode);
-  }
+const stream = await client.responses.create({
+  model: "MODEL_ID_FROM_DASHBOARD",
+  input: "Hello from AISubs",
+  store: false,
+  stream: true,
+});
 
-  await login.wait();
-}
+for await (const event of stream) console.log(event);
 ```
 
-### 3. Discover a model and send a request
-
-This example selects the first available ChatGPT model, so it does not depend
-on a model ID that may change:
+Chat Completions uses the same client with any generative model. AISubs
+translates to the selected model's native protocol when needed:
 
 ```js
-const catalog = await account.getModels();
-if (!catalog) throw new Error("This provider does not expose models");
-console.log(
-  "Available model IDs:",
-  catalog.models.map((item) => item.id),
-);
-
-const modelId = catalog.models.find((item) => item.selectable !== false)?.id;
-if (!modelId) throw new Error("No ChatGPT model is available");
-console.log("Using model:", modelId);
-
-const response = await account.proxy("responses", {
-  method: "POST",
-  headers: { "content-type": "application/json" },
-  body: JSON.stringify({
-    model: modelId,
-    store: false,
-    stream: true,
-    input: "Hello from AISubs",
-  }),
+const response = await client.chat.completions.create({
+  model: "MODEL_ID_FROM_DASHBOARD",
+  messages: [{ role: "user", content: "Hello from AISubs" }],
 });
 
-if (!response.ok) throw new Error(await response.text());
-if (response.body) {
-  for await (const chunk of response.body) process.stdout.write(Buffer.from(chunk));
-}
+console.log(response.choices[0]?.message.content);
 ```
 
-Here, `modelId` is the exact ID returned by `account.getModels()`. Model IDs
-belong to the connected provider account and can change, so list them first
-instead of copying a fixed ID from documentation.
-
-`store: false` is a request option for the Responses API; it is unrelated to
-AISubs credential storage and keeps response storage disabled. `stream: true`
-asks for incremental output, which is why the example reads `response.body` in
-chunks. Keep both options for ChatGPT subscription Responses requests.
-
-AISubs refreshes expired credentials automatically and retries a provider `401`
-once.
+</details>
 
 <details>
-<summary><strong>Use another provider</strong></summary>
+<summary><strong>Official Anthropic JavaScript SDK</strong></summary>
 
-Add its provider factory when creating AISubs:
+Install:
 
-```js
-import {
-  chatGptProvider,
-  claudeProvider,
-  copilotProvider,
-  createSubscriptionAuth,
-  grokProvider,
-  openCodeGoProvider,
-  openCodeZenProvider,
-} from "aisubs";
-
-const subscriptions = createSubscriptionAuth({
-  providers: [
-    chatGptProvider(),
-    claudeProvider(),
-    copilotProvider(),
-    grokProvider(),
-    openCodeGoProvider(),
-    openCodeZenProvider(),
-  ],
-});
+```bash
+nub install @anthropic-ai/sdk
+npm install @anthropic-ai/sdk
+pnpm add @anthropic-ai/sdk
+bun add @anthropic-ai/sdk
 ```
 
-To use a different file, pass a custom store:
-
 ```js
-import { chatGptProvider, createSubscriptionAuth, FileCredentialStore } from "aisubs";
+import Anthropic from "@anthropic-ai/sdk";
 
-const subscriptions = createSubscriptionAuth({
-  store: new FileCredentialStore("./data/aisubs-credentials.json"),
-  providers: [chatGptProvider()],
+const client = new Anthropic({
+  baseURL: "http://127.0.0.1:4319/aisubs/claude/team",
+  apiKey: process.env.AISUBS_API_KEY,
 });
-```
 
-Then select the account by provider ID:
+const message = await client.messages.create({
+  model: "MODEL_ID_FROM_DASHBOARD",
+  max_tokens: 1024,
+  messages: [{ role: "user", content: "Hello from AISubs" }],
+});
 
-```js
-const claude = subscriptions.account("claude", "team");
-const copilot = subscriptions.account("copilot", "github");
-const grok = subscriptions.account("grok", "personal");
-const go = subscriptions.account("opencode-go", "team");
-const zen = subscriptions.account("opencode-zen", "lab");
+console.log(message.content);
 ```
 
-OpenCode uses an API key:
+</details>
 
-```js
-const login = await go.signIn({ apiKey: process.env.OPENCODE_API_KEY });
-await login.wait();
+<details>
+<summary><strong>Vercel AI SDK</strong></summary>
+
+For a Responses model:
+
+```bash
+nub install ai @ai-sdk/openai
+npm install ai @ai-sdk/openai
+pnpm add ai @ai-sdk/openai
+bun add ai @ai-sdk/openai
 ```
 
-For ChatGPT on a headless machine, use `signIn({ mode: "device" })`. Copilot
-also accepts `enterpriseDomain` for a supported GitHub Enterprise Cloud domain.
+```js
+import { createOpenAI } from "@ai-sdk/openai";
+import { streamText } from "ai";
 
-Provider request paths are:
+const aisubs = createOpenAI({
+  baseURL: "http://127.0.0.1:4319/aisubs/chatgpt/personal/v1",
+  apiKey: process.env.AISUBS_API_KEY,
+});
+
+const result = streamText({
+  model: aisubs.responses("MODEL_ID_FROM_DASHBOARD"),
+  prompt: "Hello from AISubs",
+  providerOptions: { openai: { store: false } },
+});
 
-| Model catalog endpoint | `account.proxy()` path            |
-| ---------------------- | --------------------------------- |
-| `responses`            | `responses`                       |
-| `chat/completions`     | `chat/completions`                |
-| `messages`             | `messages`                        |
-| `models/MODEL_ID`      | `models/MODEL_ID:generateContent` |
+for await (const text of result.textStream) process.stdout.write(text);
+```
 
-Use `account.getModels()` first for Copilot, Grok, and OpenCode because one
-provider can expose more than one request format.
+For the universal Chat Completions surface, install
+`@ai-sdk/openai-compatible`, create the provider with the same account base URL,
+and select the model with `provider("MODEL_ID")`.
 
 </details>
 
 <details>
-<summary><strong>Read account, usage, and model information</strong></summary>
+<summary><strong>TanStack AI: Chat Completions</strong></summary>
 
-```js
-const details = await account.details();
+TanStack's generic compatibility adapter targets Chat Completions. AISubs
+translates it to the selected model's native protocol.
 
-console.log(details.session); // connection state and safe account identity
-console.log(details.credential); // expiry and refresh state, never token values
-console.log(details.usage); // limits and reset information, or null
-console.log(details.models); // available models, or null
+```bash
+nub install @tanstack/ai @tanstack/ai-openai
+npm install @tanstack/ai @tanstack/ai-openai
+pnpm add @tanstack/ai @tanstack/ai-openai
+bun add @tanstack/ai @tanstack/ai-openai
 ```
 
-Useful methods:
+```ts
+import { chat } from "@tanstack/ai";
+import { openaiCompatible } from "@tanstack/ai-openai/compatible";
 
-| Method                       | Purpose                                                |
-| ---------------------------- | ------------------------------------------------------ |
-| `account.status()`           | Check whether the account is connected                 |
-| `account.signIn(options?)`   | Start a browser, device-code, or API-key login         |
-| `account.signOut()`          | Remove this account's locally stored credentials       |
-| `account.getModels()`        | Get the provider's current model catalog               |
-| `account.getUsage()`         | Get current plan usage, if supported                   |
-| `account.details()`          | Get safe session, credential, usage, and model data    |
-| `account.fetch(url, init?)`  | Make an authorized request to an allowed provider URL  |
-| `account.proxy(path, init?)` | Make a provider-native request without handling tokens |
+const aisubs = openaiCompatible({
+  name: "aisubs",
+  baseURL: "http://127.0.0.1:4319/aisubs/grok/personal/v1",
+  apiKey: process.env.AISUBS_API_KEY!,
+  models: ["MODEL_ID_FROM_DASHBOARD"],
+});
 
-`details()`, `getUsage()`, and `getModels()` never return access or refresh
-tokens. `getAccessToken()` exists for advanced backend integrations; keep its
-result secret and prefer `fetch()` or `proxy()` when possible.
+const stream = chat({
+  adapter: aisubs("MODEL_ID_FROM_DASHBOARD"),
+  messages: [{ role: "user", content: "Hello from AISubs" }],
+});
+
+for await (const event of stream) console.log(event);
+```
 
 </details>
 
 <details>
-<summary><strong>Use multiple accounts</strong></summary>
+<summary><strong>Python OpenAI SDK</strong></summary>
 
-```js
-const personal = subscriptions.account("chatgpt", "personal");
-const work = subscriptions.account("chatgpt", "work");
-
-const selected = user.isWorkAccount ? work : personal;
-const response = await selected.proxy("responses", requestOptions);
+```bash
+python -m pip install openai
 ```
 
-Account names are 1–128 characters and cannot contain control characters.
-Each account has separate credentials, refresh state, usage, and model data.
-
-</details>
+```python
+import os
+from openai import OpenAI
 
-## Dashboard
+client = OpenAI(
+    base_url="http://127.0.0.1:4319/aisubs/grok/personal/v1",
+    api_key=os.environ["AISUBS_API_KEY"],
+)
 
-### Requirements and installation
+response = client.chat.completions.create(
+    model="MODEL_ID_FROM_DASHBOARD",
+    messages=[{"role": "user", "content": "Hello from AISubs"}],
+)
+print(response.choices[0].message.content)
+```
 
-- [Node.js 24 or newer](https://nodejs.org/en/download/).
-- A terminal and a browser for provider sign-in.
-- [Nub 0.6 or newer](https://nubjs.com/docs/install) is recommended. It is not
-  required; [pnpm](https://pnpm.io/installation),
-  [npm](https://docs.npmjs.com/cli/install/), and
-  [Bun](https://bun.sh/docs/installation) also work.
-- An API key for OpenCode Go or OpenCode Zen; the other providers use browser
-  or device-code sign-in.
+</details>
 
-Install AISubs in your project:
+<details>
+<summary><strong>cURL: Responses, Chat Completions, Anthropic, and Google</strong></summary>
 
 ```bash
-nub install aisubs       # Nub (recommended)
-npm install aisubs       # npm
-pnpm add aisubs          # pnpm
-bun add aisubs           # Bun
+curl "http://127.0.0.1:4319/aisubs/chatgpt/personal/v1/responses" \
+  -H "Authorization: Bearer $AISUBS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"MODEL_ID_FROM_DASHBOARD","store":false,"input":"Hello"}'
 ```
 
-Use the dashboard when you want to connect accounts without writing login UI:
+Chat Completions:
 
 ```bash
-nubx aisubs dashboard       # Nub (recommended)
-npx aisubs dashboard        # npm
-pnpm exec aisubs dashboard  # pnpm
-bunx aisubs dashboard       # Bun
+curl "http://127.0.0.1:4319/aisubs/grok/personal/v1/chat/completions" \
+  -H "Authorization: Bearer $AISUBS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"MODEL_ID_FROM_DASHBOARD","messages":[{"role":"user","content":"Hello from AISubs"}]}'
 ```
 
-Then click **Add account**, choose a provider, finish sign-in, and choose a
-local account name. The dashboard shows safe account details, usage, models,
-and copy-ready integration examples.
-
-By default, AISubs uses Node.js 24 or newer, listens on
-`127.0.0.1:4319`, and stores credentials at `~/.aisubs/credentials.json`.
-
-To use another directory, choose an available port, or prevent the browser
-from opening:
+Anthropic Messages:
 
 ```bash
-nubx aisubs dashboard \
-  --data-dir ./data/aisubs \
-  --port 0 \
-  --no-open
+curl "http://127.0.0.1:4319/aisubs/claude/team/v1/messages" \
+  -H "x-api-key: $AISUBS_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"MODEL_ID_FROM_DASHBOARD","max_tokens":1024,"messages":[{"role":"user","content":"Hello from AISubs"}]}'
 ```
 
-Use the equivalent `npx`, `pnpm exec`, or `bunx` command if you use npm, pnpm,
-or Bun.
-
-The dashboard prints the secure link when `--no-open` is used. Credentials stay
-on your computer; do not commit the data directory or expose the dashboard to
-the network.
-
-Use `AISUBS_DATA_DIR` or `--data-dir` to choose another data directory. Use
-`--port 0` for an available port and `--no-open` to print the secure link
-without opening a browser.
-
-## Local HTTP bridge
-
-Use the bridge for an existing SDK, Python, cURL, or another program that
-cannot import AISubs:
+Google `generateContent`:
 
 ```bash
-nubx aisubs dashboard       # Nub (recommended)
-npx aisubs dashboard        # npm
-pnpm exec aisubs dashboard  # pnpm
-bunx aisubs dashboard       # Bun
-export AISUBS_API_KEY="the-control-key-printed-by-aisubs"
+curl "http://127.0.0.1:4319/aisubs/opencode-zen/lab/v1/models/MODEL_ID_FROM_DASHBOARD:generateContent" \
+  -H "Authorization: Bearer $AISUBS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"contents":[{"role":"user","parts":[{"text":"Hello from AISubs"}]}]}'
 ```
 
-The base URL chooses the provider and account. Append the provider's request
-path shown by `getModels()` or the dashboard:
-
-```text
-http://127.0.0.1:4319/aisubs/chatgpt/personal/responses
-http://127.0.0.1:4319/aisubs/claude/team/messages
-http://127.0.0.1:4319/aisubs/grok/personal/chat/completions
-```
+</details>
 
-The account name is URL-decoded by AISubs, so URL-encode names containing
-spaces or other URL characters. AISubs removes the control key before sending
-the request to a provider.
+## Direct AISubs SDK
 
-<details>
-<summary><strong>Vercel AI SDK</strong></summary>
+Use the in-process SDK when AISubs is part of your trusted Node.js backend. It
+needs no local server, AISubs API key, or app-specific integration. Direct SDK
+requests use the provider-native endpoint; the local server is the surface that
+adds cross-protocol compatibility for third-party clients.
 
-For a `responses` model:
+Install the package in a project:
 
 ```bash
-nub install ai @ai-sdk/openai
+nub install aisubs
+npm install aisubs
+pnpm add aisubs
+bun add aisubs
 ```
 
 ```js
-import { createOpenAI } from "@ai-sdk/openai";
-import { streamText } from "ai";
+import { chatGptProvider, createSubscriptionAuth } from "aisubs";
 
-const provider = createOpenAI({
-  baseURL: "http://127.0.0.1:4319/aisubs/chatgpt/personal",
-  apiKey: process.env.AISUBS_API_KEY,
-});
+const subscriptions = createSubscriptionAuth({ providers: [chatGptProvider()] });
+const account = subscriptions.account("chatgpt", "personal");
 
-const result = streamText({
-  model: provider.responses("MODEL_ID"),
-  prompt: "Hello",
-  providerOptions: { openai: { store: false } },
+if (!(await account.status()).authenticated) {
+  const login = await account.signIn();
+  console.log(login.prompt);
+  await login.wait();
+}
+
+const catalog = await account.getModels();
+const selected = catalog?.models.find((item) => item.selectable !== false);
+if (!selected) throw new Error("No selectable model is available");
+
+// ChatGPT models are native Responses models. Other providers report their
+// native endpoint in selected.endpoints; use the matching native SDK adapter.
+const model = selected.id;
+
+const response = await account.proxy("responses", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ model, input: "Hello", store: false, stream: true }),
 });
 
-for await (const text of result.textStream) process.stdout.write(text);
+if (!response.ok) throw new Error(await response.text());
+for await (const chunk of response.body ?? []) process.stdout.write(Buffer.from(chunk));
 ```
 
-For `chat/completions`, use `@ai-sdk/openai-compatible`. For `messages`, use
-`@ai-sdk/anthropic`. For OpenCode Zen Gemini, use the model-specific
-`models/MODEL_ID:generateContent` URL shown in the dashboard.
+Available provider factories are `chatGptProvider()`, `claudeProvider()`,
+`copilotProvider()`, `grokProvider()`, `openCodeGoProvider()`, and
+`openCodeZenProvider()`.
 
-</details>
+`getModels()` is cached for five minutes and `getUsage()` for 15 seconds by
+default, with concurrent calls deduplicated. Account changes invalidate both.
+Pass `modelsCacheTtlMs` or `usageCacheTtlMs` to `createSubscriptionAuth()` when
+an in-process application needs different metadata freshness.
 
-<details>
-<summary><strong>TanStack AI</strong></summary>
+Useful account methods:
 
-TanStack AI can use AISubs through its OpenAI-compatible adapter:
+| Method               | Purpose                                                |
+| -------------------- | ------------------------------------------------------ |
+| `status()`           | Check whether the account is connected                 |
+| `signIn(options?)`   | Start browser, device-code, or API-key sign-in         |
+| `signOut()`          | Remove the account's locally stored credential         |
+| `getModels()`        | Read the current provider model catalog                |
+| `getUsage()`         | Read current provider usage when available             |
+| `details()`          | Read safe identity, credential, usage, and model data  |
+| `fetch(url, init?)`  | Send an authorized request to an allowed provider host |
+| `proxy(path, init?)` | Send a provider-native request without handling tokens |
 
-```bash
-nub install @tanstack/ai @tanstack/ai-openai       # Nub (recommended)
-npm install @tanstack/ai @tanstack/ai-openai       # npm
-pnpm add @tanstack/ai @tanstack/ai-openai          # pnpm
-bun add @tanstack/ai @tanstack/ai-openai           # Bun
-```
+<details>
+<summary><strong>Configure every provider and custom credential storage</strong></summary>
 
-```ts
-import { chat } from "@tanstack/ai";
-import { openaiCompatibleText } from "@tanstack/ai-openai/compatible";
+```js
+import {
+  FileCredentialStore,
+  chatGptProvider,
+  claudeProvider,
+  copilotProvider,
+  createSubscriptionAuth,
+  grokProvider,
+  openCodeGoProvider,
+  openCodeZenProvider,
+} from "aisubs";
 
-const stream = chat({
-  adapter: openaiCompatibleText("MODEL_ID", {
-    baseURL: "http://127.0.0.1:4319/aisubs/grok/personal",
-    apiKey: process.env.AISUBS_API_KEY!,
-  }),
-  messages: [{ role: "user", content: "Hello" }],
+const subscriptions = createSubscriptionAuth({
+  store: new FileCredentialStore("./data/aisubs-credentials.json"),
+  providers: [
+    chatGptProvider(),
+    claudeProvider(),
+    copilotProvider(),
+    grokProvider(),
+    openCodeGoProvider(),
+    openCodeZenProvider(),
+  ],
 });
+```
 
-for await (const chunk of stream) {
-  if (chunk.type === "TEXT_MESSAGE_CONTENT") process.stdout.write(chunk.delta);
-}
+Without a custom store, credentials are saved to
+`~/.aisubs/credentials.json`. Select an account with its provider ID and a
+local account name:
+
+```js
+const chatgpt = subscriptions.account("chatgpt", "personal");
+const claude = subscriptions.account("claude", "team");
+const copilot = subscriptions.account("copilot", "github");
+const grok = subscriptions.account("grok", "personal");
+const go = subscriptions.account("opencode-go", "team");
+const zen = subscriptions.account("opencode-zen", "lab");
 ```
 
-Use the equivalent `npm install`, `pnpm add`, or `bun add` command if you use
-another package manager. Replace the provider, account, and model with values
-from your dashboard.
+Account names are 1–128 characters and cannot contain control characters.
 
 </details>
 
 <details>
-<summary><strong>OpenAI, Anthropic, Python, or cURL</strong></summary>
+<summary><strong>Browser, device-code, and API-key sign-in</strong></summary>
 
-OpenAI Responses:
+The default ChatGPT flow opens a browser. On a headless machine, request its
+device-code flow explicitly:
 
-```bash
-nub install openai
+```js
+const login = await chatgpt.signIn({ mode: "device" });
+console.log(login.prompt);
+await login.wait();
 ```
 
-```js
-import OpenAI from "openai";
+Copilot uses device-code sign-in and can target a supported GitHub Enterprise
+Cloud domain:
 
-const client = new OpenAI({
-  baseURL: "http://127.0.0.1:4319/aisubs/chatgpt/personal",
-  apiKey: process.env.AISUBS_API_KEY,
-});
+```js
+const login = await copilot.signIn({ enterpriseDomain: "company.ghe.com" });
+console.log(login.prompt);
+await login.wait();
+```
 
-const stream = await client.responses.create({
-  model: "MODEL_ID",
-  store: false,
-  stream: true,
-  input: "Hello",
-});
+OpenCode Go and Zen use API keys:
 
-for await (const event of stream) console.log(event);
+```js
+const login = await go.signIn({ apiKey: process.env.OPENCODE_API_KEY });
+await login.wait();
 ```
 
-Anthropic Messages uses `@anthropic-ai/sdk` with this base URL:
+</details>
 
-```text
-http://127.0.0.1:4319/aisubs/claude/team
-```
+<details>
+<summary><strong>Inspect account details and switch between accounts</strong></summary>
 
-Chat Completions with LiteLLM:
+```js
+const details = await chatgpt.details();
 
-```bash
-pip install litellm
+console.log(details.session); // connection state and safe account identity
+console.log(details.credential); // expiry and refresh state, never token values
+console.log(details.usage); // limits and reset information, or null
+console.log(details.models); // available models, or null
 ```
 
-```python
-import os
-from litellm import completion
-
-response = completion(
-    model="openai/MODEL_ID",
-    api_base="http://127.0.0.1:4319/aisubs/grok/personal",
-    api_key=os.environ["AISUBS_API_KEY"],
-    messages=[{"role": "user", "content": "Hello"}],
-    stream=True,
-)
+`details()`, `getUsage()`, and `getModels()` never return access or refresh
+tokens. Prefer `fetch()` or `proxy()` over handling a token directly.
 
-for event in response:
-    print(event)
-```
+Each named account keeps separate credentials, refresh state, usage, and model
+data, so selection can happen at request time:
 
-cURL:
+```js
+const personal = subscriptions.account("chatgpt", "personal");
+const work = subscriptions.account("chatgpt", "work");
 
-```bash
-curl "http://127.0.0.1:4319/aisubs/chatgpt/personal/responses" \
-  -H "Authorization: Bearer $AISUBS_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{"model":"MODEL_ID","store":false,"stream":true,"input":"Hello"}'
+const selected = user.isWorkAccount ? work : personal;
+const response = await selected.proxy("responses", requestOptions);
 ```
 
-For Messages, use `x-api-key: $AISUBS_API_KEY` and
-`anthropic-version: 2023-06-01`.
-
 </details>
 
 <details>
-<summary><strong>Run a server from Node.js</strong></summary>
+<summary><strong>Run the local HTTP server from Node.js</strong></summary>
 
-HTTP bridge without the dashboard:
+This is the programmatic equivalent of `aisubs dashboard`. The API key is
+created once and reused across restarts; delete or regenerate the key file only
+when clients should receive a new key.
 
 ```js
-import { randomBytes } from "node:crypto";
-import { chatGptProvider, createSubscriptionAuth, FileCredentialStore } from "aisubs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  FileApiKeyStore,
+  FileCredentialStore,
+  chatGptProvider,
+  claudeProvider,
+  createSubscriptionAuth,
+} from "aisubs";
 import { createSubscriptionAuthServer } from "aisubs/http";
 
+const directory = join(homedir(), ".aisubs");
+const apiKey = await new FileApiKeyStore(join(directory, "api-key")).readOrCreate();
 const auth = createSubscriptionAuth({
-  store: new FileCredentialStore("./data/aisubs-credentials.json"),
-  providers: [chatGptProvider()],
+  store: new FileCredentialStore(join(directory, "credentials.json")),
+  providers: [chatGptProvider(), claudeProvider()],
 });
 
-const server = await createSubscriptionAuthServer({
-  auth,
-  apiKey: randomBytes(24).toString("hex"),
-  port: 4319,
-});
-
-console.log(server.url);
-// await server.close();
+const server = await createSubscriptionAuthServer({ auth, apiKey, port: 4319 });
+console.log(`AISubs API: ${server.url}`);
 ```
 
-Dashboard inside a Node.js application:
+A runnable version is available in [`examples/server.mjs`](./examples/server.mjs).
 
-```js
-import { createSubscriptionAuthDashboardServer } from "aisubs/dashboard";
+</details>
+
+## Dashboard options
 
-const dashboard = await createSubscriptionAuthDashboardServer({ auth });
-console.log(dashboard.bootstrapUrl);
-// await dashboard.close();
+```text
+aisubs dashboard [options]
+
+--data-dir <path>  State directory (default: ~/.aisubs)
+--port <number>    Local port (default: 4319; 0 chooses an available port)
+--no-open          Do not open the browser
+--help             Show help
 ```
 
-Both servers bind only to localhost. The programmatic HTTP server requires its
-API key; the dashboard also provides a one-time browser link.
+`AISUBS_DATA_DIR` also changes the state directory. The built-in server binds
+only to localhost.
 
-</details>
+## Local management API
 
-<details>
-<summary><strong>Local HTTP API</strong></summary>
+These routes are for the dashboard and advanced integrations:
 
 ```text
 GET    /health
@@ -546,84 +621,60 @@ GET    /v1/auth
 GET    /v1/auth/:provider
 GET    /v1/auth/:provider/accounts
 POST   /v1/auth/:provider/login
+DELETE /v1/auth/:provider?account=work
 GET    /v1/logins/:loginId
 DELETE /v1/logins/:loginId
-GET    /v1/auth/:provider/details?account=work
-DELETE /v1/auth/:provider?account=work
-POST   /v1/fetch/:provider
 GET    /v1/usage/:provider?account=work
 GET    /v1/models/:provider?account=work
-*      /aisubs/:provider/:account/*
+GET    /v1/api-key                 # dashboard session only
+POST   /v1/api-key/regenerate      # dashboard session only
+*      /aisubs/:provider/:account/v1/*
 ```
 
-The dashboard's `/bootstrap` link is one-time. Other routes require the
-control API key or dashboard session cookie. Login responses return an attempt
-ID; poll `/v1/logins/:loginId` until it is complete, failed, or cancelled.
+The provider and account routes accept `Authorization: Bearer AISUBS_API_KEY`
+or `x-api-key: AISUBS_API_KEY`. A Google-protocol client can instead put that
+same local AISubs key in `x-goog-api-key` or `?key=`; this does not represent a
+Google credential or subscription. Local credentials are removed from headers
+and query strings before proxying. Regenerating the key immediately invalidates
+the old key.
 
-</details>
+## Storage and security
 
-<details>
-<summary><strong>Storage and security</strong></summary>
-
-- Default credentials: `~/.aisubs/credentials.json`.
-- Override the directory with `AISUBS_DATA_DIR` or `--data-dir`.
-- `FileCredentialStore` creates private directories/files and uses file locks.
-- `MemoryCredentialStore` is available for tests and temporary processes.
-- Usage is cached for 15 seconds; model catalogs are cached for five minutes.
-- Sign-in, refresh, and sign-out clear the affected metadata cache.
-- Provider credentials are added only after host allowlist validation.
-- Local auth and control-key headers are removed before forwarding.
-- Account APIs return safe summaries, never token values.
-- Never expose provider credentials or `AISUBS_API_KEY` in browser code.
+- Credentials: `~/.aisubs/credentials.json`.
+- Persistent local API key: `~/.aisubs/api-key`.
+- State directories and files use private permissions where the platform supports them.
+- Provider credentials are attached only after provider-host allowlist validation.
+- Local authorization, cookie, origin, and proxy headers are never forwarded.
+- Account and model APIs never return provider access or refresh tokens.
+- Keep AISubs on localhost and never put its API key in browser-delivered code.
 
-</details>
+## Development
 
-<details>
-<summary><strong>Local development</strong></summary>
-
-From the package directory, run:
+From the package directory:
 
 ```bash
-nub run dev
+nub install
+nub run check
 ```
 
-Equivalent commands are `pnpm dev`, `npm run dev`, and `bun run dev`. Nub is
-recommended, but it is not required. The command builds the package once,
-watches backend and dashboard changes, and opens the local dashboard. Pass
-`-- --no-open` to keep the browser closed.
-
-</details>
-
-<details>
-<summary><strong>Maintainer pre-publish check</strong></summary>
+Package-manager equivalents:
 
 ```bash
-nub run check
-nub pack --dry-run
+npm install && npm run check
+pnpm install && pnpm run check
+bun install && bun run check
 ```
 
-With another package manager, use `pnpm check` / `pnpm pack`,
-`npm run check` / `npm pack --dry-run`, or `bun run check` / `bun pm pack`.
-
-Confirm that the package contains `dist`, `examples`, `public`, `README.md`,
-`LICENSE`, and the README logo asset. Test at least one real account for every
-provider your release claims to support.
-
-Runnable examples:
-
-- [`examples/direct.mjs`](./examples/direct.mjs)
-- [`examples/server.mjs`](./examples/server.mjs)
-
-</details>
+For the watch dashboard use `nub run dev`, `npm run dev`, `pnpm run dev`, or
+`bun run dev`. Before publishing, also inspect the package with `nub pack --dry-run`,
+`npm pack --dry-run`, `pnpm pack --dry-run`, or `bun pm pack --dry-run`.
 
-## Contributing and bug reports
+## Provider terms
 
-Please read [`CONTRIBUTING.md`](./CONTRIBUTING.md) before opening an issue or
-pull request. To report a reproducible bug, use the
-[Bug report form](./.github/ISSUE_TEMPLATE/bug_report.yml) and include the
-version, environment, steps to reproduce, expected and actual behavior, and
-sanitized error output where relevant.
+Provider subscriptions, OAuth clients, and model access are governed by each
+provider's terms and may change. Use accounts you are authorized to use, discover
+models at runtime, and pin the AISubs version your integration has tested.
 
 ## License
 
-AISubs is licensed under the [MIT License](./LICENSE).
+[MIT](./LICENSE)