@withone/connect 0.13.1 → 0.14.0

package/dist/server/index.esm.js

@@ -151,6 +151,12 @@ function tokenScopes(accessToken) {
 
 /** One catalog action for a platform. */
 
+/**
+ * Everything One knows about one action: the guide a caller reads before
+ * running it (`knowledge`, Markdown), the shape of its input, and the
+ * method and path the SDK runs it with.
+ */
+
 /**
  * - `not_connected`: nothing is stored for this user.
  * - `reconnect_required` (key mode): One will not act for this user.
@@ -466,15 +472,53 @@ function createTokenCredential(tokenStore, postToken) {
  *   const { redirectUrl, cookie } = oneConnect.startAuthorization({ loginHint });
  *   // in the callback route
  *   const result = await oneConnect.completeAuthorization({ userId, url, getCookie });
- *   // afterwards
+ *   // afterwards, the same way the One CLI works: find the action, read
+ *   // its knowledge, run it
  *   const rows = await oneConnect.listConnections(userId);
- *   const reply = await oneConnect.runAction(userId, { connectionKey, actionId, method, path });
+ *   const [action] = await oneConnect.searchActions(userId, "stripe", "create an invoice");
+ *   const guide = await oneConnect.getActionKnowledge(userId, action._id);
+ *   const reply = await oneConnect.runAction(userId, { connectionKey, actionId: action._id, body });
  *
  * The Next.js and Node adapters turn the first two into route handlers.
  * See `./key` and `./token` for what each mode stores and sends.
  */
 const CATALOG_PAGE_SIZE = 100;
 const CATALOG_MAX_PAGES = 20;
+const SEARCH_DEFAULT_LIMIT = 5;
+const isPlainObject = value => typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Blob) && !(value instanceof FormData);
+
+/** Fills a path's `{{placeholders}}`. A placeholder with no value is an
+ *  error the caller can read, rather than a request One cannot route. */
+function fillPath(path, params = {}) {
+  return path.replace(/\{\{([^}]+)\}\}/g, (_match, name) => {
+    const key = name.trim();
+    const value = params[key];
+    if (value === undefined || value === null || value === "") throw new OneConnectError("request_failed", `The action's path needs a value for {{${key}}}; pass it in pathParams.`);
+    return encodeURIComponent(String(value));
+  });
+}
+
+/** `application/x-www-form-urlencoded` with nested objects and arrays in
+ *  bracket notation, as Stripe and other form providers read it. */
+function formEncode(value) {
+  const out = new URLSearchParams();
+  const walk = (prefix, v) => {
+    if (v === undefined || v === null) return;
+    if (Array.isArray(v)) v.forEach((item, i) => walk(`${prefix}[${typeof item === "object" ? i : ""}]`, item));else if (typeof v === "object") for (const [k, inner] of Object.entries(v)) walk(prefix ? `${prefix}[${k}]` : k, inner);else out.append(prefix, String(v));
+  };
+  walk("", value);
+  return out.toString();
+}
+const toKnowledge = row => ({
+  _id: String(row._id ?? ""),
+  title: String(row.title ?? ""),
+  method: String(row.method ?? "").toUpperCase(),
+  path: String(row.path ?? ""),
+  tags: Array.isArray(row.tags) ? row.tags.map(String) : [],
+  knowledge: String(row.knowledge ?? ""),
+  ioSchema: row.ioSchema,
+  platform: row.connectionPlatform ? String(row.connectionPlatform) : undefined
+});
 
 /** What an app does with One in either mode. */
 
@@ -649,29 +693,34 @@ function createOneConnect(config) {
     const body = await response.json();
     return body.rows ?? [];
   };
+
+  /**
+   * Turns a catalog refusal into the right error. A One API that does not
+   * take the credential on its catalog answers the same bare 403 as a
+   * consent that is gone; asking what the grant reaches tells them apart.
+   */
+  const catalogRefusal = async (userId, what, response) => {
+    const refused = credential.refusal(response.status, await response.text());
+    if (refused?.code === "reconnect_required") {
+      if (await consentStands(userId, refused)) return new OneConnectError("request_failed", `One's ${what} refused the ${keyCredential ? "connect key" : "access token"} (HTTP 403) although the user's consent stands: this One API does not accept it on the ${what}.`, response.status);
+      return refused;
+    }
+    if (refused) return refused;
+    return new OneConnectError("request_failed", `One refused the ${what} request (HTTP ${response.status}).`, response.status);
+  };
+  const slim = rows => rows.map(row => ({
+    _id: String(row._id ?? row.systemId ?? ""),
+    title: String(row.title ?? ""),
+    method: String(row.method ?? "").toUpperCase(),
+    path: String(row.path ?? ""),
+    ...(Array.isArray(row.tags) ? {
+      tags: row.tags.map(String)
+    } : {})
+  }));
   const listActions = async (userId, platform) => {
     const pageUrl = page => `/knowledge?connectionPlatform=${encodeURIComponent(platform)}&limit=${CATALOG_PAGE_SIZE}&page=${page}`;
-    const slim = rows => rows.map(row => ({
-      _id: String(row._id ?? ""),
-      title: String(row.title ?? ""),
-      method: String(row.method ?? ""),
-      path: String(row.path ?? "")
-    }));
     const first = await oneFetch(userId, pageUrl(1));
-    if (!first.ok) {
-      const refused = credential.refusal(first.status, await first.text());
-      if (refused?.code === "reconnect_required") {
-        // The same bare 403 is what a One API answers when its catalog
-        // does not take the connect key. If the consent stands, that is
-        // what happened, and asking the user to reconnect would not help.
-        if (await consentStands(userId, refused)) {
-          throw new OneConnectError("request_failed", "One's action catalog refused the connect key (HTTP 403) although the user's consent stands: this One API does not accept the connect key on the catalog.", first.status);
-        }
-        throw refused;
-      }
-      if (refused) throw refused;
-      throw new OneConnectError("request_failed", `One refused the catalog request (HTTP ${first.status}).`, first.status);
-    }
+    if (!first.ok) throw await catalogRefusal(userId, "action catalog", first);
     const page1 = await first.json();
     const pages = Math.min(Math.max(page1.pages ?? 1, 1), CATALOG_MAX_PAGES);
     const rest = await Promise.all(Array.from({
@@ -679,19 +728,90 @@ function createOneConnect(config) {
     }, (_, index) => oneFetch(userId, pageUrl(index + 2)).then(response => response.ok ? response.json() : null).catch(() => null)));
     return slim([page1, ...rest].flatMap(page => page?.rows ?? []));
   };
+
+  /** The actions that fit a request in words, best first: One's search,
+   *  the one the One CLI's `actions search` uses. */
+  const searchActions = async (userId, platform, query, options = {}) => {
+    const params = new URLSearchParams({
+      query,
+      limit: String(options.limit ?? SEARCH_DEFAULT_LIMIT),
+      [options.mode === "knowledge" ? "knowledgeAgent" : "executeAgent"]: "true"
+    });
+    const response = await oneFetch(userId, `/available-actions/search/${encodeURIComponent(platform)}?${params}`);
+    if (!response.ok) throw await catalogRefusal(userId, "action search", response);
+    const body = await response.json();
+    return slim(Array.isArray(body) ? body : body.rows ?? []);
+  };
+
+  /** One action's knowledge, cached for the life of the client: an
+   *  action's guide does not change between two calls. */
+  const knowledgeCache = new Map();
+  const getActionKnowledge = (userId, actionId) => {
+    const cached = knowledgeCache.get(actionId);
+    if (cached) return cached;
+    const loading = (async () => {
+      const response = await oneFetch(userId, `/knowledge?_id=${encodeURIComponent(actionId)}`);
+      if (!response.ok) throw await catalogRefusal(userId, "action knowledge", response);
+      const body = await response.json();
+      const row = body.rows?.[0];
+      if (!row) throw new OneConnectError("request_failed", `One has no action with the id ${actionId}.`, 404);
+      return toKnowledge(row);
+    })();
+    knowledgeCache.set(actionId, loading);
+    loading.catch(() => knowledgeCache.delete(actionId));
+    return loading;
+  };
+
+  /**
+   * Runs one action through One the way the One CLI's `actions execute`
+   * does: the method and path come from the action itself, the path's
+   * placeholders are filled, an action One serves gets the connection key
+   * in its body, and the body is encoded as the provider reads it.
+   */
   const runAction = async (userId, input) => {
-    const method = input.method.toUpperCase();
-    const query = input.query ? `?${new URLSearchParams(input.query)}` : "";
+    // The caller may hand over method and path from the catalog; otherwise
+    // the action says, and its tags say whether it is one One serves.
+    const action = input.method && input.path ? {
+      method: input.method,
+      path: input.path,
+      tags: []
+    } : await getActionKnowledge(userId, input.actionId);
+    const method = action.method.toUpperCase();
+    const path = fillPath(action.path, input.pathParams);
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(input.query ?? {})) for (const item of Array.isArray(value) ? value : [value]) search.append(key, item);
+    const query = search.size ? `?${search}` : "";
     const headers = {
+      ...input.headers,
       "x-one-connection-key": input.connectionKey,
       "x-one-action-id": input.actionId
     };
-    const hasBody = method !== "GET" && method !== "HEAD" && input.body !== undefined;
-    if (hasBody) headers["Content-Type"] = "application/json";
-    const response = await oneFetch(userId, `/passthrough${input.path}${query}`, {
+    const takesBody = method !== "GET" && method !== "HEAD";
+    let payload = input.body;
+    // An action One serves itself reads the connection key from its body.
+    if (takesBody && action.tags.includes("custom") && (payload === undefined || isPlainObject(payload))) payload = {
+      ...(payload ?? {}),
+      connectionKey: input.connectionKey
+    };
+    let body;
+    if (takesBody && payload !== undefined) {
+      const encoding = input.encoding ?? "json";
+      if (encoding === "form") {
+        headers["Content-Type"] = "application/x-www-form-urlencoded";
+        body = formEncode(payload);
+      } else if (encoding === "multipart") {
+        const form = new FormData();
+        for (const [key, value] of Object.entries(isPlainObject(payload) ? payload : {})) form.append(key, value instanceof Blob ? value : typeof value === "object" ? JSON.stringify(value) : String(value));
+        body = form; // fetch sets the multipart boundary itself
+      } else {
+        headers["Content-Type"] = "application/json";
+        body = JSON.stringify(payload);
+      }
+    }
+    const response = await oneFetch(userId, `/passthrough${path}${query}`, {
       method,
       headers,
-      body: hasBody ? JSON.stringify(input.body) : undefined
+      body
     });
     const text = await response.text();
     if (!response.ok) {
@@ -735,6 +855,8 @@ function createOneConnect(config) {
     disconnect: credential.disconnect,
     listConnections,
     listActions,
+    searchActions,
+    getActionKnowledge,
     runAction,
     fetch: oneFetch
   };
@@ -756,4 +878,4 @@ function createOneConnect(config) {
   };
 }
 
-export { OneConnectError, createOneConnect, encodeUserReference, parseUserReference, refreshTokenExpiresAt, tenancyHeaders, tokenScopes };
+export { OneConnectError, createOneConnect, encodeUserReference, fillPath, formEncode, parseUserReference, refreshTokenExpiresAt, tenancyHeaders, tokenScopes };

package/dist/server/types.d.ts

@@ -207,17 +207,54 @@ export interface PlatformAction {
     title: string;
     method: string;
     path: string;
+    /** One's tags for the action. "custom" marks an action One itself
+     *  serves, which takes the connection key in its body. */
+    tags?: string[];
 }
+export interface SearchActionsOptions {
+    /** How many candidates to return. Five when omitted. */
+    limit?: number;
+    /** What the search ranks for: actions to run now (the default), or
+     *  actions to write code and flows against. */
+    mode?: "execute" | "knowledge";
+}
+/**
+ * Everything One knows about one action: the guide a caller reads before
+ * running it (`knowledge`, Markdown), the shape of its input, and the
+ * method and path the SDK runs it with.
+ */
+export interface ActionKnowledge extends PlatformAction {
+    tags: string[];
+    /** The action's documentation: what it does, every field it takes,
+     *  what it answers. Markdown. */
+    knowledge: string;
+    /** The input and output shape, when One has one. */
+    ioSchema?: unknown;
+    /** The platform the action belongs to. */
+    platform?: string;
+}
+export type ActionBodyEncoding = "json" | "form" | "multipart";
 export interface RunActionInput {
     /** From `listConnections`. */
     connectionKey: string;
-    /** From `listActions`. */
+    /** From `searchActions`, `listActions` or `getActionKnowledge`. */
     actionId: string;
-    method: string;
-    /** The action's path, appended to /v1/passthrough. */
-    path: string;
+    /** The action's method. Looked up from `actionId` when omitted. */
+    method?: string;
+    /** The action's path, appended to /v1/passthrough. Looked up from
+     *  `actionId` when omitted. */
+    path?: string;
+    /** Values for the path's `{{placeholders}}`, such as `{ calendarId: "primary" }`. */
+    pathParams?: Record<string, string | number | boolean>;
     body?: unknown;
-    query?: Record<string, string>;
+    query?: Record<string, string | string[]>;
+    /** Extra request headers an action's knowledge asks for, such as a
+     *  provider's version header. */
+    headers?: Record<string, string>;
+    /** How `body` is sent. JSON when omitted; "form" for providers that
+     *  take `application/x-www-form-urlencoded` (nested fields in bracket
+     *  notation); "multipart" for file-style uploads. */
+    encoding?: ActionBodyEncoding;
 }
 export interface RunActionResult {
     status: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/connect",
-  "version": "0.13.1",
+  "version": "0.14.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,29 +1,29 @@
 ---
 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, storing and refreshing the grant, and calling One with it.
+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, the connect key, 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 tools. The package does the OAuth work;
-you wire four things: a button, two routes, a daily refresh job, and the calls
-made with the grant.
+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--->  hosted page: sign in, pick tools, set access
                            GET /api/one/callback    <--302----  ?code&state
-                             stores the tokens, redirects home
+                             saves one id for the user, redirects home
                  <------   onSuccess fires
 Later:                     oneConnect.runAction(userId, ...) -> One, grant enforced
-Daily:                     oneConnect.refreshIfExpiring(userId, ...) for every connected user
 ```
 
-Use **token mode**, described in sections 1 to 8. Key mode (section 9) is a
-second way to hold the grant; use it only when the human asks for it.
+Use **key mode**, described in sections 1 to 7: the app holds one connect
+key and saves one id per user, and nothing is refreshed. Token mode
+(section 9) is the other way to hold the grant; use it only when the human
+asks for it, or when the app already passes a `tokenStore`.
 
-Secrets and tokens stay on the server.
+The client secret and the connect key stay on the server.
 
 ## 1 - Ask the human for these
 
@@ -33,17 +33,19 @@ They create the app in the One dashboard: Developers -> Connect -> New app.
 |---|---|
 | `ONE_CLIENT_ID` | From the app. |
 | `ONE_CLIENT_SECRET` | Starts with `one_secret_`. Shown once. |
+| `ONE_CONNECT_KEY` | On the app's page: Credentials -> Connect keys -> Create key, with the dashboard on Production. 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. |
 
-Never ask the human to paste the secret into the chat. Tell them which
-environment variable to set and read it from there.
+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_CONNECT_KEY=sk_live_...
 ONE_REDIRECT_URI=https://yourapp.com/api/one/callback
 ONE_PERMISSION_SET=...        # optional
 ```
@@ -63,19 +65,23 @@ export const oneConnect = createOneConnect({
   clientSecret: process.env.ONE_CLIENT_SECRET!,
   redirectUri: process.env.ONE_REDIRECT_URI!,
   permissionSet: process.env.ONE_PERMISSION_SET,
-  tokenStore: {
-    saveTokens: (userId, tokens) => /* save in the app's database, encrypted */,
-    loadTokens: (userId) => /* read; null when never connected */,
-    clearTokens: (userId) => /* delete */,
+  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 */,
   },
 });
 ```
 
 Use the app's own user id as the key and the database it already has.
 
-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).
+`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. The
+package writes it in the callback and reads it on every call; the app
+never passes it anywhere.
 
 ## 4 - The two routes
 
@@ -120,59 +126,46 @@ Vue: `@withone/connect/vue`, same props. Svelte: `use:connectButton` from
 `<one-connect-button authorize-url="/api/one/authorize" platforms="gmail, stripe">`.
 A custom button in React: `useOneConnect({ authorizeUrl })` returns `{ open, status }`.
 
-## 6 - Keeping users connected
-
-Tokens expire. Two things keep them fresh, and only the first is automatic.
-
-| | Who does it | When |
-|---|---|---|
-| Refresh before a call | the package, on its own | whenever the app calls One and the token is about to expire |
-| Refresh for users who have not called in a while | **the app**, with a daily job | once a day, for every connected user |
-
-You must add the daily job. Without it, a user who stays away for 30 days
-has to connect again: the refresh token lives 30 days, and only a live
-refresh token can renew the pair.
-
-```ts
-// a scheduled job, once a day
-for (const userId of /* every user with stored tokens */) {
-  await oneConnect.refreshIfExpiring(userId, { withinMs: 3 * 24 * 3_600_000 });
-}
-```
-
-It renews both tokens when either is within 3 days of expiring, and does
-nothing otherwise. The access token lives as long as the app's Token lifetime
-says (30 days unless changed under Advanced when creating the app); keep the
-window shorter than that, or every run refreshes. Use the scheduler the app
-already has (a cron route, a queue, a worker).
+## 6 - Calling One with the grant
 
-## 7 - Calling One with the grant
+The same four steps the One CLI takes: find the action, read its knowledge,
+run it. Always read the knowledge before running an action for the first
+time; it names the required fields, the encoding and any header.
 
 ```ts
-const connections = await oneConnect.listConnections(userId);   // [{ key, platform, access }]
-const actions = await oneConnect.listActions(userId, "gmail");  // [{ _id, title, method, path }]
+const connections = await oneConnect.listConnections(userId);                 // [{ key, platform, access }]
+const [action] = await oneConnect.searchActions(userId, "stripe", "create an invoice");  // best first, 5 by default
+const guide = await oneConnect.getActionKnowledge(userId, action._id);        // { knowledge (Markdown), ioSchema, method, path, tags }
 
 const reply = await oneConnect.runAction(userId, {
   connectionKey: connection.key,
   actionId: action._id,
-  method: action.method,
-  path: action.path,
-  body: payload,
+  body: payload,                              // what the guide asks for
+  pathParams: { calendarId: "primary" },      // values for {{placeholders}} in the path
+  query: { limit: "10" },
+  encoding: "json",                           // or "form" / "multipart", as the guide says
+  headers: {},                                // only when the guide names one
 });
-// { status, ok, data }
+// { status, ok, blockedByGrant, data }
 ```
 
-Do not set any header. The package adds the user's credential to every call
-it makes, and refreshes it first when it is about to expire.
+`runAction` takes the method and path from the action, fills the path's
+placeholders, puts the connection key in the body of an action One serves
+itself (tag `custom`), and encodes the body as asked. `listActions(userId,
+platform)` lists a whole catalog when search is not enough.
+
+Do not set any auth header. The package adds the connect key and the
+user's id to every call it makes.
 
-A `403` reply means the call is outside what the user granted. Do not retry it.
+A `403` reply with `blockedByGrant: true` means the call is outside what
+the user granted. Do not retry it.
 
 Errors are `OneConnectError` with a `code`. Handle them where the app calls One:
 
 | `code` | Meaning | Do |
 |---|---|---|
 | `not_connected` | Nothing is stored for this user. | Show the Connect button. |
-| `refresh_failed` | The grant ended. The tokens were cleared. | Ask the user to connect again. |
+| `reconnect_required` | 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. |
 | `request_failed` | One answered with an error or could not be reached. Nothing stored changed. | Retry later. |
 
 ```ts
@@ -183,7 +176,7 @@ try {
 } catch (error) {
   if (
     error instanceof OneConnectError &&
-    ["not_connected", "refresh_failed"].includes(error.code)
+    ["not_connected", "reconnect_required"].includes(error.code)
   ) {
     // show the Connect button again
   } else {
@@ -192,31 +185,38 @@ try {
 }
 ```
 
-## 8 - Rules
+`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`.
 
-- Never put the client secret in browser code, logs, error reports, source
-  files or prompts. Environment variables only.
-- Store tokens encrypted, keyed by the app's user.
-- Add the daily refresh job. It is part of the integration, not an extra.
+## 7 - Rules
+
+- Never put the client secret or the connect key in browser code, logs,
+  error reports, source files or prompts. Environment variables only.
+- Connect keys work in Production only; the human creates the key with
+  the dashboard on Production.
+- Store the per-user string as given.
 - 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 - Key mode (only when asked)
+## 8 - Done when
 
-A second way to hold the grant: one connect key for the app and one permanent
-id per user, with nothing to refresh. The routes, the button and the calls are
-the same. Two limits today:
+1. The button leads to One's page; after signing in and authorizing, the user
+   lands back in the app and `onSuccess` fires.
+2. One string is saved for the user.
+3. `listConnections` returns only the granted connections.
+4. `runAction` works for an action inside the grant and returns `403` with
+   `blockedByGrant: true` for one outside it.
+5. After the user revokes the app in their One dashboard, the next call
+   fails with `reconnect_required` and the app asks them to connect again.
 
-- `listActions` does not work in key mode yet. The app has to know the
-  actions it runs.
-- It works in Production only. The human creates the key with the dashboard
-  on Production.
+## 9 - Token mode (only when asked)
 
-The human creates the key on the app's page: Credentials -> Connect key ->
-Create key. It is shown once. They set it as `ONE_CONNECT_KEY`; never ask
-them to paste it into the chat.
+The other way to hold the grant: the app stores an access token and a
+refresh token per user, as a standard OAuth client. The routes, the button
+and the calls are the same. No `ONE_CONNECT_KEY` is needed.
 
 ```ts
 export const oneConnect = createOneConnect({
@@ -224,33 +224,44 @@ export const oneConnect = createOneConnect({
   clientSecret: process.env.ONE_CLIENT_SECRET!,
   redirectUri: process.env.ONE_REDIRECT_URI!,
   permissionSet: process.env.ONE_PERMISSION_SET,
-  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 */,
+  tokenStore: {
+    saveTokens: (userId, tokens) => /* save in the app's database, encrypted */,
+    loadTokens: (userId) => /* read; null when never connected */,
+    clearTokens: (userId) => /* delete */,
   },
 });
 ```
 
-- `reference` is one short string. Store it as given and hand it back
-  unchanged; do not parse or rebuild it. It is an identifier, not a secret.
-- There is no daily refresh job in key mode.
-- When the user revokes access, the next call throws `reconnect_required`
-  (not `refresh_failed`). Ask them to connect again. The stored value is kept.
-- A `403` reply carries `blockedByGrant: true` when the call is outside what
-  the user granted.
-- The mode is whichever credential `createOneConnect` is given: `tokenStore`
-  for token mode, `connectKey` and `userStore` for key mode.
+- Store tokens encrypted, keyed by the app's user.
+- 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).
+- When the user revokes access, the next refresh throws `refresh_failed`
+  (not `reconnect_required`) and the tokens are cleared. Ask them to connect
+  again.
+- `blockedByGrant` stays `false` in token mode; treat any `403` as outside
+  the grant.
 
-## 10 - Done when
+Tokens expire, and two things keep them fresh. Only the first is automatic:
 
-1. The button leads to One's page; after signing in and authorizing, the user
-   lands back in the app and `onSuccess` fires.
-2. The tokens are saved for the user.
-3. `listConnections` returns only the granted connections.
-4. `runAction` works for an action inside the grant and returns `403` for
-   one outside it.
-5. The daily refresh job exists and runs for every connected user.
-6. After the user revokes the app in their One dashboard, the app asks them
-   to connect again.
+| | Who does it | When |
+|---|---|---|
+| Refresh before a call | the package, on its own | whenever the app calls One and the token is about to expire |
+| Refresh for users who have not called in a while | **the app**, with a daily job | once a day, for every connected user |
+
+```ts
+// a scheduled job, once a day
+for (const userId of /* every user with stored tokens */) {
+  await oneConnect.refreshIfExpiring(userId, { withinMs: 3 * 24 * 3_600_000 });
+}
+```
+
+Without the job, a user who stays away for 30 days has to connect again:
+the refresh token lives 30 days, and only a live refresh token can renew
+the pair. The access token lives as long as the app's Token lifetime says
+(30 days unless changed under Advanced when creating the app); keep the
+window shorter than that, or every run refreshes. In token mode, "done"
+also means the daily job exists and runs for every connected user.
+
+The mode is whichever credential `createOneConnect` is given: `connectKey`
+and `userStore` for key mode, `tokenStore` for token mode.