@withone/connect 0.12.1 → 0.13.0

package/dist/server/key.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Key mode: the app holds one connect key, and one permanent id per
+ * user. Both go on every call; One reads the user's consent live each
+ * time. Nothing expires, so there is nothing to refresh, rotate or lock.
+ *
+ *   X-One-Secret:           the app's connect key
+ *   X-One-Connect-User-Id:  cu_… for the user being acted for
+ *
+ * The id comes from the one code exchange the callback makes. It is the
+ * same for a user for the life of the app, through revocation and
+ * re-consent, so it is saved once and never deleted by the SDK.
+ */
+import type { Credential } from "./credential";
+import { type OneConnectUserReference, type OneConnectUserStore } from "./types";
+/**
+ * The one value an app stores per user, as a string for one column:
+ * `cu_…`, then the space the user granted from when it is not their
+ * personal one (`cu_…;org=<id>;project=<id>`).
+ *
+ * The space travels with the id because One resolves a call's tenant
+ * from headers: a grant made from an organization lives there, and a
+ * call that names none runs in the user's personal space and reaches
+ * nothing. In token mode the access token names the space on every
+ * call; here there is no token after the exchange, so it is kept.
+ */
+export declare function encodeUserReference(reference: OneConnectUserReference): string;
+/** Reads a stored value back. Null when it is not one this SDK wrote. */
+export declare function parseUserReference(value: string): OneConnectUserReference | null;
+export interface KeyCredential extends Credential {
+    getConnectUserId: (userId: string) => Promise<string | null>;
+}
+export declare function createKeyCredential(connectKey: string, userStore: OneConnectUserStore): KeyCredential;

package/dist/server/token.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Token mode: the app holds an access token and a refresh token per
+ * user, and the SDK refreshes them with One.
+ *
+ * Lifetimes. The access token lives as long as the app's Token lifetime
+ * setting says (dashboard, Advanced, when creating or editing the app: 7
+ * days, 30 days, 90 days or 1 year; 30 days unless changed). An app that
+ * never had the setting gets an hour. The refresh token always lives 30
+ * days, whatever the access token's lifetime, and only a live refresh
+ * token can buy a new pair.
+ *
+ * Who refreshes. Before each call the client refreshes a pair that is
+ * within a minute of expiring. Refreshing earlier than that is the app's
+ * job: it runs `refreshIfExpiring` on a schedule, so the refresh token
+ * never runs out. When it has run out, the access token is used until it
+ * expires too, and only then is the user asked to connect again.
+ *
+ * Rotation. Every refresh rotates both tokens, and One treats a second
+ * use of a rotated refresh token as theft and revokes the whole grant.
+ * So the client refreshes one user at a time (in this process always,
+ * across processes through `tokenStore.withLock`), re-reads the store
+ * before spending a refresh token, clears tokens only when the grant is
+ * dead, and never lets a failing old pair delete a newer one.
+ */
+import type { Credential, PostToken } from "./credential";
+import { type OneConnectTokenStore, type OneConnectTokens, type RefreshIfExpiringOptions } from "./types";
+export interface TokenCredential extends Credential {
+    getAccessToken: (userId: string) => Promise<string>;
+    getTokens: (userId: string) => Promise<OneConnectTokens | null>;
+    refreshTokens: (userId: string) => Promise<OneConnectTokens>;
+    refreshIfExpiring: (userId: string, options?: RefreshIfExpiringOptions) => Promise<OneConnectTokens>;
+}
+export declare function createTokenCredential(tokenStore: OneConnectTokenStore, postToken: PostToken): TokenCredential;

package/dist/server/types.d.ts

@@ -2,6 +2,39 @@
  * Types for `@withone/connect/server`: the half of the SDK that runs on
  * the app's server and holds the client secret.
  */
+/**
+ * How the app holds a user's grant.
+ *
+ * - `"key"`: the app's connect key plus a permanent id per user. Nothing
+ *   expires, so there is nothing to refresh. The default.
+ * - `"token"`: an access token and a refresh token per user, which the
+ *   SDK keeps fresh.
+ */
+export type OneConnectMode = "key" | "token";
+/** Key mode: who a stored user is to One, and where their grant lives. */
+export interface OneConnectUserReference {
+    /** One's permanent id for this user, for this app: `cu_…`. */
+    connectUserId: string;
+    /** The organization the user granted from; absent for their personal
+     *  space. */
+    organizationId?: string;
+    /** The project the user granted from, when it was one. */
+    projectId?: string;
+}
+/**
+ * Key mode: where the app keeps the one value the SDK gives it per user.
+ * A single string, written when the user connects and the same until
+ * they connect again, so one column on the app's user row is enough.
+ * `userId` is the app's own id for its user.
+ *
+ * It is an identifier, not a credential: it does nothing without the
+ * app's connect key. No lock is needed, because nothing rotates.
+ */
+export interface OneConnectUserStore {
+    saveUser: (userId: string, reference: string) => Promise<void>;
+    loadUser: (userId: string) => Promise<string | null>;
+    clearUser: (userId: string) => Promise<void>;
+}
 /** What the app stores per user after the exchange. */
 export interface OneConnectTokens {
     accessToken: string;
@@ -47,10 +80,13 @@ export interface OneConnectTokenStore {
 }
 export interface RefreshIfExpiringOptions {
     /** Refresh when the access token or the refresh token expires within
-     *  this many milliseconds. One minute when omitted. */
+     *  this many milliseconds. One minute when omitted. A refresh token
+     *  that has already run out cannot be refreshed: the pair is returned
+     *  as it is while its access token still works. */
     withinMs?: number;
 }
-export interface OneConnectServerConfig {
+/** What every app configures, whichever mode it uses. */
+export interface OneConnectBaseConfig {
     /** The app's client id from the dashboard. */
     clientId: string;
     /** The app's client secret. Server only. */
@@ -69,8 +105,35 @@ export interface OneConnectServerConfig {
     /** OAuth scopes. All three tenancy tiers when omitted, so the user may
      *  grant from any space. */
     scopes?: string[];
+}
+/**
+ * Key mode, the default: pass the app's connect key and a place to keep
+ * one value per user.
+ */
+export interface OneConnectKeyConfig extends OneConnectBaseConfig {
+    mode?: "key";
+    /** The app's connect key, minted on the app's page in the dashboard.
+     *  Server only. One key per environment. */
+    connectKey: string;
+    userStore: OneConnectUserStore;
+    tokenStore?: never;
+}
+/**
+ * Token mode: pass a token store and the SDK keeps each user's tokens
+ * fresh.
+ */
+export interface OneConnectTokenConfig extends OneConnectBaseConfig {
+    mode?: "token";
     tokenStore: OneConnectTokenStore;
+    connectKey?: never;
+    userStore?: never;
 }
+/**
+ * The mode is whichever credential is configured: a `connectKey` is key
+ * mode, a `tokenStore` alone is token mode. Set `mode` to say so
+ * explicitly.
+ */
+export type OneConnectServerConfig = OneConnectKeyConfig | OneConnectTokenConfig;
 /** The transaction cookie the authorize leg sets and the callback reads. */
 export interface OneConnectCookie {
     name: string;
@@ -160,18 +223,23 @@ export interface RunActionResult {
     status: number;
     ok: boolean;
     /** True when One refused the call because it is outside the grant.
-     *  The provider was never called. Do not retry. */
+     *  The provider was never called. Do not retry. Key mode sets it; in
+     *  token mode it stays false today, so treat any 403 there as refused. */
     blockedByGrant: boolean;
     data: unknown;
 }
 /**
- * - `not_connected`: no tokens are stored for this user.
- * - `refresh_failed`: One declared the grant dead (revoked, expired or
- *   reused). The tokens were cleared; ask the user to connect again.
+ * - `not_connected`: nothing is stored for this user.
+ * - `reconnect_required` (key mode): One will not act for this user.
+ *   Their consent was revoked, or the app is deactivated. What the app
+ *   stored is kept; ask the user to connect again.
+ * - `refresh_failed` (token mode): One declared the grant dead (revoked,
+ *   expired or reused). The tokens were cleared; ask the user to connect
+ *   again.
  * - `request_failed`: One answered with an error or could not be
- *   reached. During a refresh the tokens are kept, so retry later.
+ *   reached. Nothing stored was changed, so retry later.
  */
-export type OneConnectErrorCode = "not_connected" | "refresh_failed" | "request_failed";
+export type OneConnectErrorCode = "not_connected" | "reconnect_required" | "refresh_failed" | "request_failed";
 export declare class OneConnectError extends Error {
     readonly code: OneConnectErrorCode;
     readonly status?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/connect",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "One Connect for your app: the button your users press, the two backend routes as one import, and a server client that calls One with the grant. Users keep their connections in One; your app holds only what they granted.",
   "files": [
     "dist",

package/skills/one-connect/SKILL.md

@@ -1,68 +1,118 @@
 ---
 name: one-connect
-description: Add One Connect to an application so its users can grant the app scoped, revocable access to their own One-connected tools (Gmail, Slack, Notion, Stripe and 500 more). Use when wiring @withone/connect into an app - the button, the two backend routes, and calling One with the grant.
+description: Add One Connect to an application so its users can grant the app scoped, revocable access to their own One-connected tools (Gmail, Slack, Notion, Stripe and 500 more). Use when wiring @withone/connect into an app - the button, the two backend routes, choosing key mode or token mode, and calling One with the grant.
 ---
 
 # One Connect
 
 You are adding One Connect to this application. Its users will grant the app
-scoped, revocable access to their own One-connected tools. The package does
-the OAuth work; you wire three things: a button, the two routes, and the
-calls you make with the grant.
+scoped, revocable access to their own tools. The package does the OAuth work;
+you wire three things: a button, two routes, and the calls made with the grant.
 
 ```
-Browser                    Your backend                              One
-<ConnectButton>  ------>   GET /api/one/authorize   ---302--->  One's hosted page (connect.withone.ai)
-                                                                sign-in code, pick tools, set access
-                           GET /api/one/callback    <--302----  ?code=...&state=...
-                             exchanges the code, stores the tokens
-                             302 -> /?one_connect=success
-                 <------   SDK reads the param and fires onSuccess
-Later:                     oneConnect.runAction(userId, ...) -> /v1/passthrough, grant enforced by One
+Browser                    Your backend                          One
+<ConnectButton>  ------>   GET /api/one/authorize   ---302--->  hosted page: sign in, pick tools, set access
+                           GET /api/one/callback    <--302----  ?code&state
+                             saves one id for the user, redirects home
+                 <------   onSuccess fires
+Later:                     oneConnect.runAction(userId, ...) -> One, grant enforced
 ```
 
-Secrets and tokens never reach the browser.
+The client secret and the connect key stay on the server.
 
-## 1 - Collect from the human first
+## 1 - Ask the human for these
 
-The human creates the app in the One dashboard: Developers -> Connect ->
-New app. Confidential client. The secret is shown once.
+They create the app in the One dashboard: Developers -> Connect -> New app.
 
 | Value | Notes |
 |---|---|
-| `ONE_CLIENT_ID` | 40 hex characters |
-| `ONE_CLIENT_SECRET` | starts with `one_secret_` |
-| Registered redirect URI | Must be the exact URL of the callback route (scheme, host, path, no trailing slash). One compares the string as-is and answers `invalid redirect_uri` on any difference. Use `https` for anything public; `http://localhost:3000/api/one/callback` is fine locally. |
-| `ONE_PERMISSION_SET` (optional) | The id of the app's ask: the connectors and levels the consent page opens on. Users can narrow it, never widen it. Without one, the page lists everything the user has connected. |
-| Environment | Production is the default. For the development dashboard set `ONE_API_URL=https://development-api.withone.ai`. |
+| `ONE_CLIENT_ID` | From the app. |
+| `ONE_CLIENT_SECRET` | Starts with `one_secret_`. Shown once. |
+| `ONE_CONNECT_KEY` | Key mode only. On the app's page: Credentials -> Connect key -> Create key. Shown once. It is made for the environment the dashboard is on (Production or Sandbox). |
+| Redirect URI | Registered on the app. Must match the callback route exactly, e.g. `http://localhost:3000/api/one/callback`. |
+| `ONE_PERMISSION_SET` | Optional. The tools and access levels to ask for. |
+| `ONE_API_URL` | Optional. Production when unset; `https://development-api.withone.ai` for the development dashboard. |
 
-Two facts to tell the human:
-
-- The app can show its users one line saying why it asks. It is set on the
-  app in the dashboard, not sent by this package.
-- Users can change or revoke the grant from their One dashboard at any time.
-  Treat a `401` from One as "ask the user to reconnect", never as a bug.
+Never ask the human to paste the secret or the connect key into the chat.
+Tell them which environment variable to set and read it from there.
 
 ## 2 - Environment (server only)
 
 ```bash
 ONE_CLIENT_ID=...
 ONE_CLIENT_SECRET=one_secret_...
-ONE_REDIRECT_URI=https://yourapp.com/api/one/callback   # exactly the registered value
-ONE_PERMISSION_SET=...                                     # optional
-ONE_API_URL=https://api.withone.ai                         # optional; development-api.withone.ai for development
+ONE_CONNECT_KEY=sk_live_...   # key mode
+ONE_REDIRECT_URI=https://yourapp.com/api/one/callback
+ONE_PERMISSION_SET=...        # optional
+ONE_API_URL=...               # optional
 ```
 
-## 3 - Install and create the client
+## 3 - Choose a mode
+
+The server holds a user's grant in one of two ways. The button, the two
+routes and every call are identical in both. The mode is whichever
+credential you pass to `createOneConnect`.
+
+| | Key mode (default) | Token mode |
+|---|---|---|
+| The server holds | one connect key for the app | nothing app-wide |
+| Stored per user | one string, saved once | an access token and a refresh token |
+| Expires | nothing; One checks the consent on every call | the tokens, on the lifetime set on the app |
+| Refreshing | none | the SDK does it; several servers need a shared lock |
+
+How to decide:
+
+- New integration: **key mode**.
+- The app already passes a `tokenStore`: it is in token mode. Leave it as it
+  is unless the human asks to move.
+- The human asks for OAuth bearer tokens: token mode.
+
+```ts
+// key mode
+createOneConnect({ ...app, connectKey: process.env.ONE_CONNECT_KEY!, userStore });
+
+// token mode
+createOneConnect({ ...app, tokenStore });
+```
+
+`mode: "key"` or `mode: "token"` may be added to be explicit.
+`oneConnect.mode` reports which one is running.
+
+## 4 - Install and create the client
 
 ```bash
 npm install @withone/connect
 ```
 
+Key mode:
+
 ```ts
 // lib/one.ts  (server only)
 import { createOneConnect } from "@withone/connect/server";
 
+export const oneConnect = createOneConnect({
+  clientId: process.env.ONE_CLIENT_ID!,
+  clientSecret: process.env.ONE_CLIENT_SECRET!,
+  redirectUri: process.env.ONE_REDIRECT_URI!,
+  permissionSet: process.env.ONE_PERMISSION_SET,
+  oneApiUrl: process.env.ONE_API_URL,
+  connectKey: process.env.ONE_CONNECT_KEY!,
+  userStore: {
+    saveUser: (userId, reference) => /* save the string on the app's user row */,
+    loadUser: (userId) => /* read it; null when never connected */,
+    clearUser: (userId) => /* set it to null */,
+  },
+});
+```
+
+`reference` is one short string: the user's permanent One id and the space
+they granted from. One text column on the user row is enough. Store it as
+given and hand it back unchanged; do not parse or rebuild it. It is an
+identifier, not a secret, so it needs no encryption and no lock.
+
+Token mode:
+
+```ts
 export const oneConnect = createOneConnect({
   clientId: process.env.ONE_CLIENT_ID!,
   clientSecret: process.env.ONE_CLIENT_SECRET!,
@@ -70,30 +120,30 @@ export const oneConnect = createOneConnect({
   permissionSet: process.env.ONE_PERMISSION_SET,
   oneApiUrl: process.env.ONE_API_URL,
   tokenStore: {
-    saveTokens: (userId, tokens) => /* write to this app's database, encrypted, keyed by its user */,
-    loadTokens: (userId) => /* read; null when the user never connected */,
-    clearTokens: (userId, failed) => /* delete; when `failed` is set, only if the stored refreshToken is still failed.refreshToken */,
-    // Required when the app runs more than one process (serverless, several instances, a worker):
-    withLock: (userId, run) => /* run() while holding a per-user lock all processes share, e.g. pg_advisory_xact_lock */,
+    saveTokens: (userId, tokens) => /* save in the app's database, encrypted */,
+    loadTokens: (userId) => /* read; null when never connected */,
+    clearTokens: (userId) => /* delete */,
   },
 });
 ```
 
-`tokens` is `{ accessToken, refreshToken, expiresAt }`. Use the app's own user
-id as the key. Implement the store on whatever the app already uses; do not
-add a database for it.
+In token mode, if the app runs more than one server process or a background
+worker, also add `withLock: (userId, run) => ...`, which runs `run()` while
+holding a per-user lock all processes share (for example a Postgres advisory
+lock). The access token lives as long as the app's Token lifetime says (30
+days unless changed under Advanced when creating the app); the refresh token
+lives 30 days. Required: once a day, for each connected user, call
+`oneConnect.refreshIfExpiring(userId, { withinMs: 3 * 24 * 3_600_000 })`. It
+renews both tokens when either is within 3 days of expiring; without it,
+users have to connect again when the tokens run out. Keep the window shorter
+than the Token lifetime, or every run refreshes.
 
-One rotates the refresh token on every refresh and revokes the whole grant if
-an old one is used again. So when two processes could refresh the same user,
-`withLock` is not optional: without it, a web request and a worker refreshing
-together disconnect the user. The README's "Tokens" section has a Postgres
-version. For background work, call `refreshIfExpiring(userId, { withinMs })`:
-every few minutes with a window of minutes to keep access tokens warm, and
-once a day with a window of days so idle users' 30-day refresh tokens renew.
+In both modes use the app's own user id as the key and the database it
+already has.
 
-## 4 - The two routes
+## 5 - The two routes
 
-Next.js App Router (also Remix, SvelteKit, Hono, Bun: anything with the web `Request`):
+Next.js App Router (also Remix, SvelteKit, Hono, Bun):
 
 ```ts
 // app/api/one/[action]/route.ts
@@ -101,87 +151,44 @@ import { createOneConnectRoutes } from "@withone/connect/next";
 import { oneConnect } from "@/lib/one";
 
 export const { GET } = createOneConnectRoutes(oneConnect, {
-  identifyUser: async (request) => /* this app's signed-in user id, or null */,
-  loginHintFor: async (request) => /* their email, to pre-fill One's sign-in; or null */,
-  signInUrl: "/login",   // where to send a visitor who is not signed in
+  identifyUser: async (request) => /* the signed-in user's id, or null */,
+  loginHintFor: async (request) => /* their email, optional */,
+  signInUrl: "/login",
 });
 ```
 
-That file serves `/api/one/authorize` and `/api/one/callback`.
+Express or plain Node: `createOneConnectHandlers(oneConnect, { identifyUser })`
+from `@withone/connect/node`, mounted at `/api/one/authorize` and
+`/api/one/callback`.
 
-Express, Fastify, Koa, plain Node:
-
-```ts
-import { createOneConnectHandlers } from "@withone/connect/node";
-import { oneConnect } from "./one";
-
-const { authorize, callback } = createOneConnectHandlers(oneConnect, {
-  identifyUser: (request) => /* user id or null */,
-});
-app.get("/api/one/authorize", authorize);
-app.get("/api/one/callback", callback);
-```
-
-The routes mint `state` and PKCE, keep them in a per-flow httpOnly cookie
-(`one_tx_<state>`, SameSite=Lax, 30 minutes), verify the state on return,
-exchange the code with the secret over HTTP Basic, store both tokens, and
-redirect to `/` with `?one_connect=success` or
-`?one_connect=error&one_connect_error=declined|expired|failed` (a code, never
-free text: the SDK shows fixed text for it). Pass `returnTo` to
-`createOneConnect` to land somewhere else.
-
-## 5 - The button
+## 6 - The button
 
 ```tsx
-import { ConnectButton } from "@withone/connect/react";   // "use client" bundle: fine in a Server Component
+import { ConnectButton } from "@withone/connect/react";
 
 <ConnectButton
   authorizeUrl="/api/one/authorize"
-  platforms={["stripe", "google-calendar"]}   // connector slugs; logos from One's CDN, names from the slug
-  connected={hasGrant}                         // from the server (e.g. await oneConnect.isConnected(userId))
-  onSuccess={() => { /* refetch app state; the tokens are already stored */ }}
-  onError={(message, code) => { /* show message; code: declined | expired | failed */ }}
+  platforms={["gmail", "stripe"]}   // connector slugs
+  connected={hasGrant}              // from the server: await oneConnect.isConnected(userId)
+  onSuccess={() => { /* refetch app state */ }}
+  onError={(message) => { /* show message */ }}
 />
 ```
 
-Other props: `disabled`, `variant` ("default" | "accent" | "block"), `size`
-("sm" | "md" | "lg"), `fullWidth`, `theme` ("light" | "dark" | "auto"),
-`connectTheme` (One's page), `accentColor`, `label`, `connectedLabel`,
-`description` (block), `onCancel` (user pressed Back on One's page).
-
-Always pass `connected` from the server. Without it the button forgets after
-a reload and asks the user to connect again.
+Optional props: `variant` ("default" | "accent" | "block"), `accentColor`,
+`size` ("sm" | "md" | "lg"), `fullWidth`, `theme` ("light" | "dark" | "auto"),
+`label`, `description`, `disabled`.
 
-Vue: `import { ConnectButton } from "@withone/connect/vue"` with the same props
-in kebab case (`authorize-url`, `:connected`), and `@success`, `@error`,
-`@cancel`. Svelte: `import { connectButton } from "@withone/connect/svelte"`
-as `use:connectButton={{ authorizeUrl, platforms, connected, onSuccess }}`.
-Anything else: `import "@withone/connect"` registers
-`<one-connect-button authorize-url="/api/one/authorize" platforms="stripe, notion" connected>`,
-which dispatches `success`, `error` (detail `{ message, code }`) and `cancel`.
-A custom button in React: `const { open, status, error } = useOneConnect({ authorizeUrl })`
-from `@withone/connect/react`. Elsewhere: `createConnectFlow({ authorizeUrl, onSuccess, onError }).open`.
+Vue: `@withone/connect/vue`, same props. Svelte: `use:connectButton` from
+`@withone/connect/svelte`. Anything else: `import "@withone/connect"` and use
+`<one-connect-button authorize-url="/api/one/authorize" platforms="gmail, stripe">`.
+A custom button in React: `useOneConnect({ authorizeUrl })` returns `{ open, status }`.
 
-The button renders in a shadow root with a constructed stylesheet, so it
-works under a strict CSP. Allow `https://assets.withone.ai` in `img-src` for
-the logos. Style it with `--one-connect-font`, `--one-connect-radius` and
-`::part(button)`; do not wrap it in extra styling divs.
-
-The flow is a same-tab redirect. The outcome is read once per page load:
-every button shows it, and the callbacks fire once, on the first button
-still mounted.
-
-## 6 - Calling One with the grant
-
-Everything runs on the server through the client. Tokens refresh themselves.
+## 7 - Calling One with the grant
 
 ```ts
-const connections = await oneConnect.listConnections(userId);
-// [{ key, platform, name, title, image, access }]
-// access.policy: "full" | "methods" (+ methods: ["GET", ...]) | "actions" (+ actions: [{ actionId, title, method }])
-
-const actions = await oneConnect.listActions(userId, "gmail");
-// [{ _id, title, method, path }]  - what exists, not what is permitted
+const connections = await oneConnect.listConnections(userId);   // [{ key, platform, access }]
+const actions = await oneConnect.listActions(userId, "gmail");  // [{ _id, title, method, path }]
 
 const reply = await oneConnect.runAction(userId, {
   connectionKey: connection.key,
@@ -193,38 +200,60 @@ const reply = await oneConnect.runAction(userId, {
 // { status, ok, blockedByGrant, data }
 ```
 
-`blockedByGrant` true means One refused the call because it is outside the
-grant; the provider was never called. Do not retry. Any other `/v1` call:
-`oneConnect.fetch(userId, "/connections", init)`.
-
-`OneConnectError` codes: `not_connected` (no tokens stored), `refresh_failed`
-(One declared the grant dead: revoked, expired or reused; the tokens were
-cleared; ask the user to connect again), `request_failed` (One answered with
-an error or could not be reached; `status` carries it; during a refresh the
-tokens are KEPT, so retry later rather than asking the user to reconnect).
-
-To ask users for more tools later, edit the app's permission set in the
-dashboard. The next Connect shows only the new tools as "needs one more
-connection" and the callback stores the new pair; no code change.
-
-## 7 - Rules
-
-- Never put the secret in a client bundle, a log line or an error report.
-- Store tokens encrypted, keyed by the app's user. Delete them when the user
-  is deleted. The client deletes them itself only when One declares the
-  grant dead, and never deletes a newer pair saved in the meantime.
-- Give the store `withLock` whenever more than one process can refresh.
-- The registered redirect URI and `ONE_REDIRECT_URI` must be the same string.
-- Do not build a completion page. The callback redirect is the completion.
-- Do not write the OAuth steps by hand when the package exposes them.
-
-## 8 - Done when all of these pass
-
-1. Button -> One's hosted page -> sign-in code from a real inbox -> choose
-   tools and levels -> "You're all set" -> back in the app with `onSuccess`
-   fired. Repeat once in a private window.
-2. `listConnections` returns only the granted connections, each with `access`.
-3. `runAction` on an action inside the grant reaches the provider; one outside
-   it returns `blockedByGrant: true`.
-4. Revoking the app from the user's One dashboard makes the next call throw
-   `refresh_failed` or return `401`, and the app shows its reconnect prompt.
+A `403` reply means the call is outside what the user granted. Do not retry
+it. In key mode `blockedByGrant` is `true` for those.
+
+Errors are `OneConnectError` with a `code`. Handle them where the app calls One:
+
+| `code` | Mode | Meaning | Do |
+|---|---|---|---|
+| `not_connected` | both | Nothing is stored for this user. | Show the Connect button. |
+| `reconnect_required` | key | One will not act for this user: they revoked access, or the app is deactivated. The stored value is kept. | Ask the user to connect again. |
+| `refresh_failed` | token | The grant ended. The tokens were cleared. | Ask the user to connect again. |
+| `request_failed` | both | One answered with an error or could not be reached. Nothing stored changed. | Retry later. |
+
+```ts
+import { OneConnectError } from "@withone/connect/server";
+
+try {
+  await oneConnect.runAction(userId, action);
+} catch (error) {
+  if (
+    error instanceof OneConnectError &&
+    ["not_connected", "reconnect_required", "refresh_failed"].includes(error.code)
+  ) {
+    // show the Connect button again
+  } else {
+    throw error;
+  }
+}
+```
+
+In key mode `isConnected(userId)` says the user has connected before. One
+confirms the consent on each call, so a user who revoked is found by the
+next call throwing `reconnect_required`.
+
+## 8 - Rules
+
+- Never put the client secret or the connect key in browser code, logs,
+  error reports, source files or prompts. Environment variables only.
+- A connect key works in one environment. Use the Production key against
+  production and the Sandbox key against sandbox.
+- Key mode: store the per-user string as given. Token mode: store tokens
+  encrypted, keyed by the app's user.
+- The registered redirect URI and `ONE_REDIRECT_URI` must be identical.
+- Do not build a completion page; the callback redirect is the completion.
+- Do not write OAuth steps or One request headers by hand; use the package.
+- Do not switch an existing app from one mode to the other unless asked.
+
+## 9 - Done when
+
+1. The button leads to One's page; after signing in and authorizing, the user
+   lands back in the app and `onSuccess` fires.
+2. Key mode: one string is saved for the user. Token mode: the tokens are saved.
+3. `listConnections` returns only the granted connections.
+4. `runAction` works for an action inside the grant and returns `403` for
+   one outside it.
+5. After the user revokes the app in their One dashboard, the next call
+   fails with `reconnect_required` (key mode) or `refresh_failed` (token
+   mode) and the app asks them to connect again.

package/src/next.ts

@@ -14,7 +14,7 @@
  * That serves /api/one/authorize and /api/one/callback. Register
  * `https://yourapp.com/api/one/callback` as the app's redirect URI.
  */
-import type { OneConnect } from "./server";
+import type { OneConnectClient } from "./server";
 
 export interface OneConnectRoutesOptions {
   /** The app's own id for the signed-in user, or null when nobody is
@@ -80,7 +80,7 @@ export function routeFor(url: string): string {
 }
 
 export function createOneConnectRoutes(
-  oneConnect: OneConnect,
+  oneConnect: Pick<OneConnectClient, "startAuthorization" | "completeAuthorization">,
   options: OneConnectRoutesOptions,
 ): OneConnectRoutes {
   const cookiePath = (): string =>

package/src/node.ts

@@ -17,7 +17,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 
 import { createOneConnectRoutes, type OneConnectRoutesOptions } from "@withone/connect/next";
-import type { OneConnect } from "./server";
+import type { OneConnectClient } from "./server";
 
 export interface OneConnectNodeOptions {
   /** The app's own id for the signed-in user, or null when nobody is
@@ -76,7 +76,7 @@ async function send(response: ServerResponse, web: Response): Promise<void> {
 }
 
 export function createOneConnectHandlers(
-  oneConnect: OneConnect,
+  oneConnect: Pick<OneConnectClient, "startAuthorization" | "completeAuthorization">,
   options: OneConnectNodeOptions,
 ): OneConnectHandlers {
   // The web adapter receives a Request; the Node callbacks want the