@withone/connect 0.12.1 → 0.12.2

package/README.md

@@ -20,171 +20,84 @@
   <a href="https://npmjs.com/package/@withone/connect"><img src="https://img.shields.io/npm/v/%40withone%2Fconnect" alt="npm version"></a>
 </p>
 
-One Connect lets your users grant your app **scoped, revocable access to their own One-connected tools**: Gmail, Slack, Notion, Stripe and 500 more. Your user keeps their connections in One. Your app holds only what they granted, and One checks that on every call.
+One Connect lets your users grant your app **scoped, revocable access to their own tools**: Gmail, Slack, Notion, Stripe and 500 more. The connections stay in your user's One account. Your app holds only what they granted, and One checks that on every call.
 
-You build three things: a button, two backend routes, and the calls you make with the grant. This package gives you all three.
+You add three things: a button, two backend routes, and the calls you make with the grant.
 
 ```
-Browser                       Your server                          One
-<ConnectButton>  ───────►  GET /api/one/authorize  ──302──►  One's hosted connect page
-                                                              sign in · pick tools · set access
+Browser                    Your server                          One
+<ConnectButton>  ──────►   GET /api/one/authorize  ──302──►  hosted page: sign in, pick tools, set access
                            GET /api/one/callback   ◄──302──  ?code&state
-                             exchanges the code, stores the tokens
-                             302 → /?one_connect=success
-onSuccess() fires ◄────────
-later:                     oneConnect.runAction(userId, …)  ──►  /v1/passthrough (grant enforced)
+                             stores the tokens, redirects home
+onSuccess()      ◄──────
+later:                     oneConnect.runAction(userId, …)  ──►  One, grant enforced
 ```
 
-> **Connect vs. Auth.** [`@withone/auth`](https://github.com/withoneai/auth) puts connections in *your* One project: you own them. Connect puts connections in *your user's* One account and hands you a grant.
-
 ## Install
 
 ```bash
 npm install @withone/connect
 ```
 
-Or let your coding agent do the whole setup:
-
-```bash
-npx skills add withoneai/connect
-```
+Using a coding agent? `npx skills add withoneai/connect` teaches it the whole setup.
 
 ## 1 · Create your app in One
 
-Dashboard → **Developers → Connect → New app**.
-
-- You get a **client id** (public) and a **client secret** (shown once; server only).
-- Register the **redirect URI** of your callback route, exactly: `https://yourapp.com/api/one/callback`.
-- Choose what the app asks for: specific connectors and levels (an *ask*, which gives you a permission set id), or everything the user has connected.
-- Optionally write the one line users see about why you ask.
-
-Environment variables, server side:
+Dashboard → **Developers → Connect → New app**. Register your callback URL exactly, for example `https://yourapp.com/api/one/callback`. Optionally choose the tools and access levels to ask for; the consent page lists them in the order you add them.
 
 ```env
 ONE_CLIENT_ID=…
-ONE_CLIENT_SECRET=one_secret_…
-ONE_REDIRECT_URI=https://yourapp.com/api/one/callback
-ONE_PERMISSION_SET=…                    # optional: the ask to open on
-ONE_API_URL=https://api.withone.ai      # optional: production when unset
+ONE_CLIENT_SECRET=one_secret_…                        # server only
+ONE_REDIRECT_URI=https://yourapp.com/api/one/callback  # exactly the registered URL
+ONE_PERMISSION_SET=…                                  # optional: the tools you ask for
+ONE_API_URL=https://api.withone.ai                    # optional: production when unset
 ```
 
-| Variable | Required | What it is |
-|---|---|---|
-| `ONE_CLIENT_ID` | yes | Public client id from your app |
-| `ONE_CLIENT_SECRET` | yes | Server only. Never in a browser, a log or an error report. |
-| `ONE_REDIRECT_URI` | yes | Must equal the registered URI character for character |
-| `ONE_PERMISSION_SET` | no | The ask the consent page opens on. Without it, the page lists everything the user has connected. |
-| `ONE_API_URL` | no | `https://development-api.withone.ai` for the development environment |
-
 ## 2 · The button
 
-Any element wired to `open()` works. The pre-built button draws connector logos from their slugs and handles Connect → Connecting → Connected itself. It renders in its own shadow root, so your page's CSS can't break it, and it keeps its look under a strict Content Security Policy (`style-src 'self'`).
-
 ```tsx
-// React / Next.js: safe to import from a Server Component (the bundle is "use client")
 import { ConnectButton } from "@withone/connect/react";
 
 <ConnectButton
   authorizeUrl="/api/one/authorize"
-  platforms={["stripe", "google-calendar", "gmail"]}
-  connected={user.hasOneGrant}          // from your server; see below
-  onSuccess={() => refreshAppState()}
-  onError={(message, code) => showBanner(message)}
+  platforms={["gmail", "google-calendar", "stripe"]}
+  connected={user.hasOneGrant}   // from your server
+  onSuccess={() => refresh()}
+  onError={(message) => showError(message)}
 />
 ```
 
-```vue
-<!-- Vue 3 -->
-<script setup>
-import { ConnectButton } from "@withone/connect/vue";
-</script>
-<template>
-  <ConnectButton authorize-url="/api/one/authorize" :platforms="['stripe', 'notion']" :connected="hasGrant" @success="onConnected" />
-</template>
-```
+| Prop | What it does |
+|---|---|
+| `authorizeUrl` | Your authorize route. Required. |
+| `platforms` | Connector slugs to show as logos. |
+| `connected` | Whether the user already has a grant, from your server. |
+| `variant` | `default`, `accent` (your brand colour via `accentColor`), or `block` (a card with a `description`). |
+| `size` | `sm`, `md` or `lg`. |
+| `fullWidth` | Fills its container. |
+| `theme` | `light`, `dark` or `auto`. `connectTheme` sets One's page. |
+| `label` | Button text. |
+| `disabled` | Not clickable. |
+| `onSuccess` / `onError` / `onCancel` | How the flow ended. |
+
+Other frameworks take the same props:
 
-```svelte
-<!-- Svelte, as an action -->
-<script>
-  import { connectButton } from "@withone/connect/svelte";
-</script>
-<div use:connectButton={{ authorizeUrl: "/api/one/authorize", platforms: ["stripe", "notion"], connected: data.hasGrant, onSuccess }} />
+```vue
+<ConnectButton authorize-url="/api/one/authorize" :platforms="['gmail']" @success="onConnected" />  <!-- @withone/connect/vue -->
 ```
 
 ```html
-<!-- Plain HTML or any other framework: importing the package registers the element -->
-<one-connect-button authorize-url="/api/one/authorize" platforms="stripe, notion" connected></one-connect-button>
-<script type="module">
-  import "@withone/connect";
-  document.querySelector("one-connect-button").addEventListener("success", () => location.reload());
-</script>
-```
-
-Every surface takes the same props. Attributes are the kebab-case names, and `connected`, `disabled` and `full-width` are boolean attributes. The React and Vue components render the host element themselves, `<span class="one-connect">`, and React's `className` and `style` apply to it. The button inside never changes the host's attributes, so server-rendered pages hydrate without a mismatch, and `fullWidth` fills whatever container you put the button in, flex rows included.
-
-| Prop (attribute) | What it does |
-|---|---|
-| `authorizeUrl` (`authorize-url`) | Your authorize route. Relative paths resolve against the page. Required. |
-| `platforms` | Connector slugs: `["stripe", "google-calendar"]`. Logos come from One's CDN and names from the slug, spelled the way each brand spells itself (`hubspot` → HubSpot). Pass `{ slug, name, imageUrl }` to override either. As an attribute: `"stripe, notion"`. The first three draw as logos; the rest fold into a `+N` chip. |
-| `connected` | Whether this user has a live grant, **from your server**. When set, it decides the Connected state, so the button stays right after a reload. When omitted, the button shows Connected only right after a successful return. |
-| `disabled` | Not clickable, for example until terms are accepted. |
-| `variant` | `default` neutral · `accent` your brand colour · `block` a card with a description and a "Secured by One" foot |
-| `size` | `sm` · `md` (default) · `lg` |
-| `fullWidth` (`full-width`) | Stretches to its container. |
-| `theme` | `light` (default), `dark`, or `auto` to follow the visitor's setting. Matches *your* page. |
-| `connectTheme` (`connect-theme`) | `light` or `dark` for One's hosted page. `appTheme` still works and is deprecated. |
-| `accentColor` (`accent-color`) | Fill of the `accent` variant; One's lime when omitted. The label is black or white, whichever reads better on it. |
-| `label` · `connectedLabel` (`connected-label`) | Button text. Defaults: "Connect your apps" · "Connected". |
-| `description` | Sub-line on the `block` variant. |
-| `onSuccess` | The grant was stored. Fires once per page load, on the first button still mounted. Refetch; your server is the truth. |
-| `onError(message, code)` | The flow ended without a grant. `code` is `declined`, `expired` or `failed`, and `message` is the SDK's fixed text for it, safe to show. |
-| `onCancel` | The user came back with the browser's Back button before finishing. The button is already clickable again. |
-
-The custom element dispatches `success`, `error` (`detail: { message, code }`) and `cancel` events.
-
-**Matching your design system.** The button inherits your page's font. Two custom properties and two parts do the rest:
-
-```css
-one-connect-button, .one-connect {
-  --one-connect-font: var(--font-sans);
-  --one-connect-radius: 8px;
-}
-.one-connect::part(button) { box-shadow: none; }   /* the React, Vue and Svelte host */
-one-connect-button::part(label) { font-weight: 600; }
-```
-
-Under a strict CSP, allow One's connector logos in `img-src` (`https://assets.withone.ai`). If they're blocked, each chip falls back to the connector's first letter.
-
-**Your own element.** In React, use the hook:
-
-```tsx
-import { useOneConnect } from "@withone/connect/react";
-
-const { open, status, error } = useOneConnect({ authorizeUrl: "/api/one/authorize" });
-// status: "idle" | "connecting" | "connected" | "error"
-<button onClick={open} disabled={status === "connecting"}>Connect your tools</button>
+<one-connect-button authorize-url="/api/one/authorize" platforms="gmail, stripe"></one-connect-button>
+<script type="module">import "@withone/connect";</script>
 ```
 
-Anywhere else, use `createConnectFlow`:
-
-```ts
-import { createConnectFlow } from "@withone/connect";
-
-const flow = createConnectFlow({
-  authorizeUrl: "/api/one/authorize",
-  onSuccess: () => {},
-  onError: (message, code) => {},
-  onCancel: () => {},
-});
-button.addEventListener("click", flow.open);
-// later: flow.destroy()
-```
+Svelte: `use:connectButton={{ authorizeUrl, platforms }}` from `@withone/connect/svelte`.
 
-**How the return works.** The flow is a full-page redirect in the same tab, so it works in every browser with no popup or iframe. When your callback route redirects home, it appends `?one_connect=success` or `?one_connect=error&one_connect_error=<code>`. The SDK reads that once per page load, shows it on every button, calls back once, and removes the params from the address bar. Only the code travels on the URL. The text comes from the SDK, so a crafted link can't put its own words in front of your users. `readConnectReturn()` returns the same outcome if you want to show it yourself.
+Your own button in React: `const { open, status } = useOneConnect({ authorizeUrl: "/api/one/authorize" })`.
 
-## 3 · The two routes, as one import
+To match your design, set `--one-connect-font` and `--one-connect-radius`, or style `::part(button)`.
 
-Create the client once, on the server:
+## 3 · The two routes
 
 ```ts
 // lib/one.ts
@@ -197,178 +110,50 @@ export const oneConnect = createOneConnect({
   permissionSet: process.env.ONE_PERMISSION_SET,
   oneApiUrl: process.env.ONE_API_URL,
   tokenStore: {
-    // Your database, keyed by your own user id. Store them encrypted.
     saveTokens: (userId, tokens) => db.oneTokens.upsert(userId, tokens),
     loadTokens: (userId) => db.oneTokens.find(userId),
     clearTokens: (userId) => db.oneTokens.delete(userId),
-    // Required when you run more than one server or a worker. See "Tokens" below.
-    withLock: (userId, run) => db.withUserLock(userId, run),
   },
 });
 ```
 
-Then mount the routes for your server.
-
-**Next.js (App Router), Remix, SvelteKit, Hono, Bun** and anything else that speaks the web `Request`:
-
 ```ts
-// app/api/one/[action]/route.ts
+// app/api/one/[action]/route.ts   (Next.js; also Remix, SvelteKit, Hono, Bun)
 import { createOneConnectRoutes } from "@withone/connect/next";
 import { oneConnect } from "@/lib/one";
 
 export const { GET } = createOneConnectRoutes(oneConnect, {
   identifyUser: async (request) => (await getSession(request))?.userId ?? null,
-  loginHintFor: async (request) => (await getSession(request))?.email ?? null,
-  signInUrl: "/login",
 });
 ```
 
-That one file serves `/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) => request.session?.userId ?? null,
-});
-app.get("/api/one/authorize", authorize);
-app.get("/api/one/callback", callback);
-```
-
-What the routes do for you: mint `state` and a PKCE verifier, keep them in a per-flow httpOnly cookie, send the browser to One, verify the returned state, exchange the code with your secret over HTTP Basic, store both tokens through your `tokenStore`, and redirect home with the outcome. A declined consent, an expired attempt and a failed exchange come back as `?one_connect=error&one_connect_error=declined|expired|failed`. `completeAuthorization` also returns a `message` describing what happened, for your logs only.
-
-**Another language?** The routes are ordinary OAuth 2.1 authorization code with PKCE. The reference behaviour is in `src/server/index.ts`; the same steps work in Python, Go or Ruby.
+That file serves `/api/one/authorize` and `/api/one/callback`. For Express or plain Node, use `createOneConnectHandlers` from `@withone/connect/node`.
 
 ## 4 · Using the grant
 
-Everything runs on your server through the same client. Every call refreshes the tokens first when they are about to expire (see [Tokens](#5--tokens-storing-refreshing-keeping-alive)).
-
 ```ts
-// What the grant reaches, each connection with its access
-const connections = await oneConnect.listConnections(userId);
-// [{ key, platform, name, title, image, access: { policy: "full" | "methods" | "actions", … } }]
+const connections = await oneConnect.listConnections(userId);   // what the user granted
+const actions = await oneConnect.listActions(userId, "gmail");  // what a platform can do
 
-// What actions a platform has (what exists, not what is permitted)
-const actions = await oneConnect.listActions(userId, "gmail");
-// [{ _id, title, method, path }]
-
-// Run one
 const reply = await oneConnect.runAction(userId, {
   connectionKey: connections[0].key,
   actionId: actions[0]._id,
   method: actions[0].method,
   path: actions[0].path,
-  body: { … },
 });
-// { status, ok, blockedByGrant, data }
+// { status, ok, data }
 ```
 
-`blockedByGrant` is true when One refused the call because it is outside what the user granted. The provider was never called. Do not retry; the user chose that. Anything else on One's `/v1` API: `oneConnect.fetch(userId, "/connections", init)` adds the bearer and the tenancy headers for you.
-
-Other calls on the client: `isConnected`, `getAccessToken`, `getTokens`, `refreshTokens`, `refreshIfExpiring`, `disconnect`.
-
-## 5 · Tokens: storing, refreshing, keeping alive
-
-Your app owns the tokens. The SDK never stores anything itself: it calls your `tokenStore`, and it refreshes through it.
-
-**What One issues**
-
-| | Lifetime | On refresh |
-|---|---|---|
-| Access token | The lifetime set on your app: 1 hour by default, or 7, 30, 90 or 365 days | Replaced |
-| Refresh token | 30 days | Replaced, with a fresh 30 days |
-
-Every refresh returns a **new pair** and retires the old refresh token. If the old refresh token is ever used again, One treats it as stolen and **revokes the whole grant**. The user then has to connect again.
-
-**Store them in your database, encrypted, keyed by your user id**
-
-```sql
-create table one_tokens (
-  user_id       text primary key,
-  access_token  text not null,          -- encrypted
-  refresh_token text not null,          -- encrypted
-  expires_at    timestamptz not null    -- tokens.expiresAt
-);
-```
-
-**Give the store a lock when more than one process can refresh**
-
-Serverless functions, several instances, a background worker: any two of them can decide to refresh the same user at the same moment.
-
-```
-without a lock                              with withLock
-web ──refresh(R1)──► One: here is R2         web ──lock──refresh(R1)──► R2 ──save──unlock
-worker ─refresh(R1)─► One: R1 reused!        worker ──wait─────────────────────────────┐
-                      revoke everything ✗                   reload: R2 is fresh, use it ✓
-```
-
-The SDK takes the lock around every refresh and around the save in the callback. It re-reads the store inside the lock, so the process that waited uses the pair the first one saved instead of spending the old refresh token again. The SDK never takes the lock twice for the same call. Postgres, with a transaction-scoped advisory lock:
-
-```ts
-withLock: async (userId, run) => {
-  const client = await pool.connect();
-  try {
-    await client.query("begin");
-    await client.query("select pg_advisory_xact_lock(hashtextextended($1, 0))", [`one-connect:${userId}`]);
-    return await run();
-  } finally {
-    await client.query("commit").catch(() => {});
-    client.release();
-  }
-},
-```
+A `403` means the call is outside what the user granted. Don't retry it.
 
-A single long-running process can leave `withLock` out; the SDK already runs one refresh per user at a time inside a process. If your lock has a timeout, make it at least 60 seconds, because it spans one call to One.
+## 5 · Tokens
 
-**Refreshing ahead of time**
+- Store them in your database, encrypted, keyed by your user id. The SDK refreshes them for you.
+- Running more than one server or a background worker? Add `withLock(userId, run)` to your token store, for example a Postgres advisory lock. Two servers refreshing at once would otherwise disconnect the user.
+- Keep idle users connected: once a day, call `oneConnect.refreshIfExpiring(userId, { withinMs: 7 * 24 * 3_600_000 })`.
+- A `refresh_failed` error means the grant ended (revoked or expired). Ask the user to connect again.
 
-`getAccessToken`, `runAction`, `listConnections` and `fetch` refresh on their own when the access token has less than a minute left. For work that runs in the background, refresh ahead with `refreshIfExpiring`. It refreshes only when the access token **or** the refresh token expires within the window, and otherwise returns the stored pair without calling One.
-
-```ts
-// Every 10 minutes: users whose access token expires in the next 15 minutes
-// (your table knows expires_at).
-await oneConnect.refreshIfExpiring(userId, { withinMs: 15 * 60_000 });
-
-// Once a day, for every connected user: renews refresh tokens before their
-// 30 days run out, so a user who has not been active stays connected.
-await oneConnect.refreshIfExpiring(userId, { withinMs: 7 * 24 * 3_600_000 });
-```
-
-**When a refresh fails**
-
-| `OneConnectError.code` | What happened | Tokens | What to do |
-|---|---|---|---|
-| `refresh_failed` | One declared the grant dead: the user revoked it, the refresh token expired, or it was reused | Cleared | Show "Reconnect", which runs Connect again |
-| `request_failed` | One could not be reached, answered with a server error, or refused your client credentials | **Kept** | Retry later. Check `status` for a 401, which means your client secret is wrong. |
-| `not_connected` | No tokens are stored for this user | — | Show "Connect" |
-
-The SDK clears tokens only when One says the grant is dead (`invalid_grant`), or when the refresh token's own expiry has passed. It calls `clearTokens(userId, failed)` with the pair that failed. Just before that, it re-reads the store: if a newer pair has landed (the user reconnected while an old refresh was failing), it keeps and returns the newer pair. To make that check atomic, delete only when the stored refresh token is still `failed.refreshToken`. `disconnect(userId)` calls `clearTokens(userId)` without `failed`, and always deletes.
-
-**Asking for more tools later**
-
-Edit the app's permission set in the dashboard (Developers → Connect). The next time a user presses the button, One shows them the new tools as "{your app} needs one more connection", with what they already granted pre-selected. Authorizing replaces the user's grant and old tokens at once, and the callback saves the new pair.
-
-## What your users see
-
-In their One dashboard the app appears under **Access control**, with what they granted and when it was last used. They can lower a level, remove an account, or revoke the app at any time. Your next call reflects it: a `401` means reconnect, a `403` means outside the grant.
-
-In *your* dashboard the app lists every user who said yes, what each one granted, and lets you revoke a user.
-
-## Security notes
-
-- The client secret is used on your server only, for the code exchange and refresh, over HTTP Basic.
-- The authorization code is single use and expires ten minutes after consent.
-- Refresh tokens rotate on every use. Reusing an old one revokes the whole family, which is why the client refreshes one user at a time: inside a process on its own, and across processes through `tokenStore.withLock`.
-- The browser half of this package never sees a token. It navigates and reads one query parameter.
-
-## Development
-
-```bash
-npm run check     # typecheck, tests, build
-```
+To ask for more tools later, edit your app's tools in the dashboard. Users see only the new ones the next time they connect.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/connect",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "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

@@ -6,51 +6,40 @@ description: Add One Connect to an application so its users can grant the app sc
 # 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
+                             stores the tokens, redirects home
+                 <------   onSuccess fires
+Later:                     oneConnect.runAction(userId, ...) -> One, grant enforced
 ```
 
-Secrets and tokens never reach the browser.
+Secrets and tokens 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`. |
-
-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.
+| `ONE_CLIENT_ID` | From the app. |
+| `ONE_CLIENT_SECRET` | Starts with `one_secret_`. Shown once. |
+| 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. |
 
 ## 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_REDIRECT_URI=https://yourapp.com/api/one/callback
+ONE_PERMISSION_SET=...        # optional
+ONE_API_URL=...               # optional
 ```
 
 ## 3 - Install and create the client
@@ -70,30 +59,22 @@ 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.
+Use the app's own user id as the key and the database it already has.
 
-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.
+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).
 
 ## 4 - 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 +82,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
-});
-```
-
-That file serves `/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 */,
+  identifyUser: async (request) => /* the signed-in user's id, or null */,
+  loginHintFor: async (request) => /* their email, optional */,
+  signInUrl: "/login",
 });
-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.
+Express or plain Node: `createOneConnectHandlers(oneConnect, { identifyUser })`
+from `@withone/connect/node`, mounted at `/api/one/authorize` and
+`/api/one/callback`.
 
 ## 5 - 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.
-
-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`.
-
-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.
+Optional props: `variant` ("default" | "accent" | "block"), `accentColor`,
+`size` ("sm" | "md" | "lg"), `fullWidth`, `theme` ("light" | "dark" | "auto"),
+`label`, `description`, `disabled`.
 
-## 6 - Calling One with the grant
+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 }`.
 
-Everything runs on the server through the client. Tokens refresh themselves.
+## 6 - 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,
@@ -190,41 +128,26 @@ const reply = await oneConnect.runAction(userId, {
   path: action.path,
   body: payload,
 });
-// { status, ok, blockedByGrant, data }
+// { status, ok, 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.
+A `403` means the call is outside what the user granted. Do not retry it.
+A `refresh_failed` error means the grant ended; ask the user to connect again.
 
 ## 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.
+- Never put the client secret in browser code, logs or error reports.
+- 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 by hand; use the package.
+
+## 8 - 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. `listConnections` returns only the granted connections.
+3. `runAction` works for an action inside the grant and returns `403` for
+   one outside it.
+4. After the user revokes the app in their One dashboard, the app asks them
+   to connect again.