@withone/connect 0.8.2 → 0.9.0

package/README.md

@@ -1,4 +1,4 @@
-<img src="https://assets.withone.ai/banners/connect.png" alt="One Connect — Let your users grant your app scoped, revocable access to their own tools." style="border-radius: 5px;">
+<img src="https://assets.withone.ai/banners/connect.png" alt="One Connect. Let your users grant your app scoped, revocable access to their own tools." style="border-radius: 5px;">
 
 <h3 align="center">One Connect</h3>
 
@@ -7,7 +7,7 @@
   &nbsp;·&nbsp;
   <a href="https://withone.ai/docs/connect"><strong>Docs</strong></a>
   &nbsp;·&nbsp;
-  <a href="https://app.withone.ai"><strong>Dashboard</strong></a>
+  <a href="https://app.withone.ai/developers/connect"><strong>Dashboard</strong></a>
   &nbsp;·&nbsp;
   <a href="https://withone.ai/changelog"><strong>Changelog</strong></a>
   &nbsp;·&nbsp;
@@ -20,157 +20,77 @@
   <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 application **scoped, revocable access to their own One-connected tools** — Gmail, Slack, Notion, Stripe and 500+ more — through the standard OAuth 2.1 authorization-code flow with PKCE.
+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.
 
-Your user owns their connections inside One. You never see their Gmail password — you hold a One access token scoped to **exactly what they granted**, and they can narrow or revoke it at any time. One enforces the grant 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.
 
-Fully compatible with popular frameworks such as React, Next.js, Vue, Svelte, and more.
+```
+Browser                       Your server                          One
+<ConnectButton>  ───────►  GET /api/one/authorize  ──302──►  One's hosted connect 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)
+```
 
-> **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 own One account** and hands you a scoped grant.
+> **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
 
-With npm:
-
 ```bash
-npm i @withone/connect
+npm install @withone/connect
 ```
 
-With yarn:
+Or let your coding agent do the whole setup:
 
 ```bash
-yarn add @withone/connect
+npx skills add withoneai/connect
 ```
 
-## How it works
-
-Everything sensitive — `state`, the PKCE verifier, your client secret, the tokens — lives on **your server**. The SDK is a thin navigator: it sends the tab to One's hosted connect page and never touches a token.
-
-You build exactly **two backend routes and one button**.
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant YourApp as Your Application
-    participant YourBackend as Your Backend
-    participant One as One Connect
-
-    User->>YourApp: Clicks "Connect your tools"
-    YourApp->>YourBackend: Navigate tab → GET /api/one/authorize
-    YourBackend->>YourBackend: Mint state + PKCE, set httpOnly cookie
-    YourBackend->>One: 302 → /oauth/authorize
-    User->>One: Sign in, connect tools, narrow & grant access
-    One->>YourBackend: 302 → /api/one/callback?code&state
-    YourBackend->>YourBackend: Verify state
-    YourBackend->>One: POST /oauth/token (code + verifier + secret)
-    One->>YourBackend: Access token + refresh token
-    YourBackend->>YourApp: 302 → /?one_connect=success
-    YourApp->>User: SDK detects the return, onSuccess() fires
-```
+## 1 · Create your app in One
 
-The SDK watches for `?one_connect=` on the page URL when the tab returns — so **there is no completion page to build**.
+Dashboard → **Developers → Connect → New app**.
 
-## 1 · Create your OAuth 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.
 
-Dashboard → **Settings → OAuth Apps → New OAuth app**.
-
-- You get a **Client ID** (public) and a **Client Secret** (shown once — server-only, never in a browser).
-- Register your **redirect URI** (e.g. `https://yourapp.com/api/one/callback`).
-- Pick the **access-token lifetime**: 7 days, 30 days, 90 days or 1 year.
-- Optionally create a **permission set** — the connectors your app needs and the access level for each (full / read & write / read only / specific actions). Your user sees it pre-filled at consent and can only *narrow* it. Without one, your app asks for access to the user's connections generally, which they can also narrow.
-
-### Environment Variables
+Environment variables, server side:
 
 ```env
-ONE_CLIENT_ID=...
-ONE_CLIENT_SECRET=one_secret_...
+ONE_CLIENT_ID=…
+ONE_CLIENT_SECRET=one_secret_…
 ONE_REDIRECT_URI=https://yourapp.com/api/one/callback
-ONE_PERMISSION_SET=79659c66-...
+ONE_PERMISSION_SET=…                    # optional: the ask to open on
+ONE_API_URL=https://api.withone.ai      # optional: production when unset
 ```
 
-| Variable | Required | Description |
+| Variable | Required | What it is |
 |---|---|---|
-| `ONE_CLIENT_ID` | Yes | Public client ID from your OAuth app |
-| `ONE_CLIENT_SECRET` | Yes | Server-only secret. Never ship to a browser. |
-| `ONE_REDIRECT_URI` | Yes | Must exactly match the URI registered in the dashboard |
-| `ONE_PERMISSION_SET` | No | Pre-fills the consent screen with the access your app needs |
-
-## 2 · Using the Connect component
+| `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 |
 
-Replace the `authorize URL` with your backend authorize endpoint.
+## 2 · The button
 
-> Relative paths like `/api/one/authorize` work — the SDK resolves them against your page's origin. A full URL is only required if the authorize route lives on a different origin than the page.
+Any element wired to `open()` works. The pre-built button draws connector logos from their slugs, and manages Connect → Connecting → Connected on its own.
 
 ```tsx
-"use client";
-
-import { useOneConnect } from "@withone/connect";
-
-export function ConnectWithOne() {
-  const { open } = useOneConnect({
-    authorize: {
-      url: "https://your-domain.com/api/one/authorize",
-    },
-    appTheme: "light",
-    onSuccess: () => {
-      // Your backend already stored the tokens by the time this fires.
-      console.log("Access granted");
-    },
-    onError: (error) => {
-      console.error("Connect failed:", error);
-    },
-    onClose: () => {
-      console.log("Connect flow closed");
-    },
-  });
-
-  return <button onClick={open}>Connect your tools</button>;
-}
-```
-
-### Configuration Options
-
-| Option | Type | Description |
-|---|---|---|
-| `authorize.url` | `string` | Full URL of your backend authorize endpoint. Must be absolute. |
-| `appTheme` | `"dark" \| "light"` | Theme for the Connect card. The SDK carries it on the URL fragment — nothing for your backend to forward. |
-| `onSuccess` | `() => void` | The grant completed and your server stored the tokens |
-| `onError` | `(error: string) => void` | The flow failed, with a human-readable message |
-| `onClose` | `() => void` | The user closed the card without a result |
-
-### Returned handle
-
-| Method | Description |
-|---|---|
-| `open()` | Navigates the tab to One's hosted connect flow |
-| `close()` | No-op kept for API stability — safe to call on unmount |
-
-
-### Optional: the pre-built button
-
-Any element wired to `open()` works — the button is **optional**. It
-ships as a custom element, `<one-connect-button>`, so the SAME tag
-works in React, Next, Vue, Svelte, or plain HTML — no refs, no mount
-calls. Importing the package registers it. It wires the whole flow
-itself and manages Connect → Connecting → Connected.
-
-```tsx
-// React / Next — a real component:
+// React / Next.js
 import { ConnectButton } from "@withone/connect/react";
 
-export function ConnectWithOne() {
-  return (
-    <ConnectButton
-      authorizeUrl="/api/one/authorize"
-      label="Connect your apps"
-      platforms={[
-        { name: "Stripe", imageUrl: "/icons/stripe.svg" },
-        { name: "PostHog", imageUrl: "/icons/posthog.svg" },
-      ]}
-      onSuccess={() => {/* tokens stored server-side — refresh app state */}}
-    />
-  );
-}
+<ConnectButton
+  authorizeUrl="/api/one/authorize"
+  platforms={["stripe", "google-calendar", "gmail"]}
+  moreCount={274}
+  onSuccess={() => refreshAppState()}
+  onError={(message) => showBanner(message)}
+/>
 ```
 
 ```vue
@@ -179,293 +99,161 @@ export function ConnectWithOne() {
 import { ConnectButton } from "@withone/connect/vue";
 </script>
 <template>
-  <ConnectButton
-    authorize-url="/api/one/authorize"
-    :platforms="[{ name: 'Stripe', imageUrl: '/icons/stripe.svg' }]"
-    @success="onConnected"
-  />
+  <ConnectButton authorize-url="/api/one/authorize" :platforms="['stripe', 'notion']" @success="onConnected" />
 </template>
 ```
 
 ```svelte
-<!-- Svelte (an action — the idiomatic Svelte shape) -->
+<!-- Svelte, as an action -->
 <script>
   import { connectButton } from "@withone/connect/svelte";
 </script>
-<div use:connectButton={{
-  authorizeUrl: "/api/one/authorize",
-  platforms: [{ name: "Stripe", imageUrl: "/icons/stripe.svg" }],
-  onSuccess: () => { /* refresh app state */ },
-}} />
+<div use:connectButton={{ authorizeUrl: "/api/one/authorize", platforms: ["stripe", "notion"], onSuccess }} />
 ```
 
-Plain HTML (or any other framework) uses the SAME widget as a custom
-element — `import "@withone/connect"` registers `<one-connect-button>`:
-
 ```html
-<!-- Plain HTML / any framework -->
-<one-connect-button
-  authorize-url="/api/one/authorize"
-  label="Connect your apps"
-></one-connect-button>
-<script>
-  document.querySelector("one-connect-button")
-    .addEventListener("success", () => location.reload());
+<!-- Plain HTML or any other framework: importing the package registers the element -->
+<one-connect-button authorize-url="/api/one/authorize" platforms="stripe, notion" more-count="274"></one-connect-button>
+<script type="module">
+  import "@withone/connect";
+  document.querySelector("one-connect-button").addEventListener("success", () => location.reload());
 </script>
 ```
 
-| Attribute | What it does |
+| Prop (attribute) | What it does |
 |---|---|
-| `authorize-url` | Your backend authorize route (required) |
-| `label` | Button text (default "Connect your apps") |
-| `variant` | `default` pill · `accent` brand pill · `block` consent card |
-| `theme` | `light` / `dark` — matches YOUR page |
-| `app-theme` | Theme for One's card |
-| `platforms` | JSON array of `{name, imageUrl}` — provider chips, fan on hover |
-| `more-count` | The `+N` chip (e.g. `274`) |
+| `authorizeUrl` (`authorize-url`) | Your authorize route. Relative paths resolve against the page. Required. |
+| `platforms` | Connector slugs: `["stripe", "google-calendar"]`. Logos and names come from One. To override either, pass `{ slug, name, imageUrl }`. As an attribute: `"stripe, notion"`. |
+| `moreCount` (`more-count`) | The `+N` chip after the first three logos |
+| `label` | Button text. Default "Connect your apps". |
+| `connectedLabel` (`connected-label`) | Text after a successful return. Default "Connected". |
+| `variant` | `default` pill · `accent` brand-colored pill · `block` card with a description |
 | `description` | Sub-line on the `block` variant |
-| `accent-color` | Fill for the `accent` variant (lime fallback) |
-| `connected-label` | Label after success |
+| `theme` | `light` or `dark`, matching *your* page |
+| `appTheme` (`app-theme`) | `light` or `dark` for One's page |
+| `accentColor` (`accent-color`) | Fill of the `accent` variant. One's lime when omitted. |
+| `onSuccess` / `onError` | Fire once when the tab returns. `onError` receives a message safe to show. The element also dispatches `success` and `error` events. |
 
-Events: `success`, `error` (detail = message), `close` — or set the
-`onSuccess` / `onError` / `onClose` function props (React 19, Vue and
-Svelte set these naturally).
-
-TypeScript + React: add this once so JSX accepts the tag:
+Your own element:
 
 ```ts
-// one-connect-button.d.ts
-declare module "react" {
-  namespace JSX {
-    interface IntrinsicElements {
-      "one-connect-button": React.DetailedHTMLProps<
-        React.HTMLAttributes<HTMLElement>,
-        HTMLElement
-      > & {
-        "authorize-url"?: string; "app-theme"?: string; label?: string;
-        variant?: string; theme?: string; platforms?: string;
-        "more-count"?: string; description?: string;
-        "accent-color"?: string; "connected-label"?: string;
-        onSuccess?: () => void; onError?: (e: string) => void;
-        onClose?: () => void;
-      };
-    }
-  }
-}
-export {};
-```
+import { useOneConnect } from "@withone/connect";
 
-Programmatic alternative: `mountConnectButton(container, options)`
-takes the same options as an object (plus `connect: {…useOneConnect
-props}`) and returns `{ setState, destroy }`.
-
-## 3 · Backend — the authorize route
-
-Generates `state` (CSRF proof) and PKCE (proof that whoever redeems the code is this server), stashes both in an httpOnly cookie, and 302s the browser to One.
-
-```typescript
-// app/api/one/authorize/route.ts (Next.js App Router)
-import { createHash, randomBytes } from "crypto";
-import { NextRequest, NextResponse } from "next/server";
-
-const ONE_AUTHORIZE_URL = "https://api.withone.ai/oauth/authorize";
-
-export async function GET(req: NextRequest) {
-  const state = randomBytes(16).toString("hex");
-  const verifier = randomBytes(32).toString("base64url");
-  const challenge = createHash("sha256").update(verifier).digest("base64url");
-
-  const url = new URL(ONE_AUTHORIZE_URL);
-  url.searchParams.set("client_id", process.env.ONE_CLIENT_ID!);
-  url.searchParams.set("redirect_uri", process.env.ONE_REDIRECT_URI!);
-  url.searchParams.set("response_type", "code");
-  url.searchParams.set("scope", "user:connections:read user:connections:write org:connections:read org:connections:write project:connections:read project:connections:write"); // all 3 tenancy tiers — org/project grants 403 without theirs
-  url.searchParams.set("state", state);
-  url.searchParams.set("code_challenge", challenge);
-  url.searchParams.set("code_challenge_method", "S256");
-
-  if (process.env.ONE_PERMISSION_SET) {
-    url.searchParams.set("permission_set", process.env.ONE_PERMISSION_SET);
-  }
-
-  // Optional: your user's email. One pre-fills (never locks) their sign-in.
-  const userEmail = await getCurrentUserEmail(req); // ← your code
-  if (userEmail) url.searchParams.set("login_hint", userEmail);
-
-  const res = NextResponse.redirect(url.toString(), 302);
-  // One cookie PER flow — the name carries the state. Users open the
-  // flow more than once (retries, second tabs); a single shared cookie
-  // would be overwritten by each start, so only the LAST-opened flow
-  // could ever complete. Expiry reaps the strays.
-  res.cookies.set(`one_tx_${state}`, verifier, {
-    httpOnly: true,
-    secure: true,
-    // The callback is a TOP-LEVEL navigation on your own site, so Lax
-    // survives the cross-site redirect chain (One -> here).
-    sameSite: "lax",
-    maxAge: 600, // matches One's 10-minute authorization-code lifetime
-    path: "/api/one",
-  });
-  return res;
-}
+const { open } = useOneConnect({
+  authorizeUrl: "/api/one/authorize",
+  onSuccess: () => {},
+  onError: (message) => {},
+});
+button.addEventListener("click", open);
 ```
 
-## 4 · Backend — the callback route
-
-One redirects back with a **single-use code**, worthless without your secret and the PKCE verifier. Exchange it server-side, store the tokens, then redirect anywhere on your site with `?one_connect=success` appended — the SDK reads that parameter off the page URL on return.
-
-```typescript
-// app/api/one/callback/route.ts
-import { NextRequest, NextResponse } from "next/server";
-
-const ONE_TOKEN_URL = "https://api.withone.ai/oauth/token";
-
-export async function GET(req: NextRequest) {
-  const code = req.nextUrl.searchParams.get("code");
-  const state = req.nextUrl.searchParams.get("state");
-  // The state that came back selects its own cookie — not finding one
-  // IS the CSRF failure (forged or stale state has no cookie).
-  const verifier = state ? req.cookies.get(`one_tx_${state}`)?.value : undefined;
-
-  if (!code || !state || !verifier) {
-    return NextResponse.redirect(
-      new URL(
-        "/?one_connect=error&one_connect_message=" +
-          encodeURIComponent("The sign-in attempt expired or was tampered with."),
-        req.url,
-      ),
-      302,
-    );
-  }
-
-  const basic = Buffer.from(
-    `${process.env.ONE_CLIENT_ID}:${process.env.ONE_CLIENT_SECRET}`,
-  ).toString("base64");
-
-  const tokenRes = await fetch(ONE_TOKEN_URL, {
-    method: "POST",
-    headers: {
-      Authorization: `Basic ${basic}`,
-      "Content-Type": "application/x-www-form-urlencoded",
-    },
-    body: new URLSearchParams({
-      grant_type: "authorization_code",
-      code,
-      redirect_uri: process.env.ONE_REDIRECT_URI!,
-      code_verifier: verifier,
-    }),
-  });
-
-  const res = NextResponse.redirect(
-    new URL(
-      tokenRes.ok
-        ? "/?one_connect=success"
-        : "/?one_connect=error&one_connect_message=" +
-          encodeURIComponent("Token exchange failed."),
-      req.url,
-    ),
-    302,
-  );
-  res.cookies.delete(`one_tx_${state}`);
-
-  if (tokenRes.ok) {
-    // { access_token, refresh_token, token_type: "bearer", expires_in, scope }
-    const tokens = await tokenRes.json();
-    await saveOneTokens(req, {                    // ← your code
-      accessToken: tokens.access_token,
-      refreshToken: tokens.refresh_token,
-      expiresAt: Date.now() + tokens.expires_in * 1000,
-    });
-  }
-  return res;
-}
-```
+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_message=…`); the SDK reads that on load, fires your callback once, and removes the params from the address bar.
+
+## 3 · The two routes, as one import
 
-**Token response (200):**
+Create the client once, on the server:
 
-```json
-{
-  "access_token": "one_at_...",
-  "refresh_token": "one_rt_...",
-  "token_type": "bearer",
-  "expires_in": 2592000,
-  "scope": "user:connections:read user:connections:write"
-}
+```ts
+// lib/one.ts
+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,
+  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),
+  },
+});
 ```
 
-## 5 · Backend — refreshing the token
-
-Access tokens last as long as you chose when creating the app (7 days to 1 year). Refresh tokens last **30 days** and are **rotated on every use** — always store BOTH new tokens. Reusing an old refresh token revokes the entire token family (theft protection).
-
-```typescript
-const ONE_TOKEN_URL = "https://api.withone.ai/oauth/token";
-
-export async function getOneAccessToken(userId: string): Promise<string> {
-  const t = await loadOneTokens(userId);           // ← your code
-  if (Date.now() < t.expiresAt - 60_000) return t.accessToken;
-
-  // The refresh exchange is authenticated exactly like the code exchange —
-  // same Basic header. The public-client form (client_id in the body, no
-  // secret) is rejected with 401.
-  const basic = Buffer.from(
-    `${process.env.ONE_CLIENT_ID}:${process.env.ONE_CLIENT_SECRET}`,
-  ).toString("base64");
-
-  const res = await fetch(ONE_TOKEN_URL, {
-    method: "POST",
-    headers: {
-      Authorization: `Basic ${basic}`,
-      "Content-Type": "application/x-www-form-urlencoded",
-    },
-    body: new URLSearchParams({
-      grant_type: "refresh_token",
-      refresh_token: t.refreshToken,
-    }),
-  });
-  if (!res.ok) throw new Error("One refresh failed — re-run the connect flow");
-
-  const tokens = await res.json();
-  await saveOneTokens(userId, {                    // BOTH tokens — rotation!
-    accessToken: tokens.access_token,
-    refreshToken: tokens.refresh_token,
-    expiresAt: Date.now() + tokens.expires_in * 1000,
-  });
-  return tokens.access_token;
-}
+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
+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",
+});
 ```
 
-## 6 · Backend — using the grant
+That one file serves `/api/one/authorize` and `/api/one/callback`.
 
-The bearer token works on One's standard `/v1` API — the same routes every other credential uses.
+**Express, Fastify, Koa, plain Node:**
 
-```typescript
-const token = await getOneAccessToken(userId);
+```ts
+import { createOneConnectHandlers } from "@withone/connect/node";
+import { oneConnect } from "./one";
 
-// Discover what the user granted. Ungranted connections are invisible,
-// not merely forbidden.
-const res = await fetch("https://api.withone.ai/v1/connections", {
-  headers: { Authorization: `Bearer ${token}` },
+const { authorize, callback } = createOneConnectHandlers(oneConnect, {
+  identifyUser: (request) => request.session?.userId ?? null,
 });
+app.get("/api/one/authorize", authorize);
+app.get("/api/one/callback", callback);
 ```
 
-Execute actions through `/v1/passthrough/*` with the same bearer. Every call is checked inside One against what the user granted — a call outside the grant returns `403`, and your code cannot override it. That is the point.
+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 all come back as `?one_connect=error` with a message you can show.
+
+**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.
+
+## 4 · Using the grant
+
+Everything runs on your server through the same client. Tokens are refreshed for you before they expire; a refresh One refuses clears the stored tokens and throws `OneConnectError` with code `refresh_failed`, which means "ask the user to connect again".
+
+```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", … } }]
+
+// 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 }
+```
 
-## Completion
+`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.
 
-There is no completion page to build: your callback's final redirect carries `?one_connect=success` on any same-origin URL. The SDK detects it, fires your callbacks, and scrubs the params from the address bar. The SDK paints no result UI of its own — One's hosted page already showed the success beat before redirecting back. If you want your own celebratory screen, just have the callback redirect there; append the `?one_connect=` params wherever the SDK is mounted.
+Other calls on the client: `isConnected`, `getAccessToken`, `getTokens`, `refreshTokens`, `disconnect`.
 
 ## What your users see
 
-In their own One dashboard, your app appears under **Authorized apps** with what they granted and when it was last used. They can revoke it at any time — handle `401`/`403` by prompting them to reconnect.
+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, your OAuth app lists every user who granted access, and you can revoke individual users too.
+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 lives on your server only. Authenticate the token exchange with the `Authorization: Basic` header, as shown above.
-- The authorization code is single-use and expires in 10 minutes.
-- The SDK never handles tokens. It navigates the tab to One's hosted connect page and watches for the `?one_connect=` result on the way back — there is nothing sensitive in the browser to leak.
+- 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 serialises refreshes per user.
+- 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
+```
 
 ## License
 
-This project is licensed under the GPL-3.0 license. See the [LICENSE](LICENSE) file for details.
+GPL-3.0. See [LICENSE](LICENSE).