@withone/connect 0.13.1 → 0.14.0

package/README.md

@@ -28,7 +28,7 @@ You add three things: a button, two backend routes, and the calls you make with
 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
-                             saves the grant for the user, redirects home
+                             saves one id for the user, redirects home
 onSuccess()      ◄──────
 later:                     oneConnect.runAction(userId, …)  ──►  One, grant enforced
 ```
@@ -45,9 +45,12 @@ Using a coding agent? `npx skills add withoneai/connect` teaches it the whole se
 
 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.
 
+Then, on the app's page, under **Credentials → Connect keys**, create a key with your dashboard on Production. It is shown once.
+
 ```env
 ONE_CLIENT_ID=…
 ONE_CLIENT_SECRET=one_secret_…                        # server only
+ONE_CONNECT_KEY=sk_live_…                             # server only
 ONE_REDIRECT_URI=https://yourapp.com/api/one/callback  # exactly the registered URL
 ONE_PERMISSION_SET=…                                  # optional: the tools you ask for
 ```
@@ -98,7 +101,7 @@ To match your design, set `--one-connect-font` and `--one-connect-radius`, or st
 
 ## 3 · The server client
 
-Your server keeps an access token and a refresh token for each user who connects. This is **token mode**, and it is the one to use.
+Your server holds one **connect key** for the app and saves one id per user who connects. Nothing expires and nothing is refreshed: One checks the user's consent on every call. This is **key mode**, the default.
 
 ```ts
 // lib/one.ts
@@ -109,17 +112,16 @@ 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) => db.oneTokens.upsert(userId, tokens),
-    loadTokens: (userId) => db.oneTokens.find(userId),
-    clearTokens: (userId) => db.oneTokens.delete(userId),
+  connectKey: process.env.ONE_CONNECT_KEY!,
+  userStore: {
+    saveUser: (userId, reference) => db.users.update(userId, { oneConnect: reference }),
+    loadUser: async (userId) => (await db.users.find(userId))?.oneConnect ?? null,
+    clearUser: (userId) => db.users.update(userId, { oneConnect: null }),
   },
 });
 ```
 
-Store the tokens in your database, encrypted, keyed by your user id.
-
-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.
+`reference` is one short string: the user's permanent One id, plus the space they granted from. Save it in one column and hand it back unchanged. It is an identifier, not a secret, and it stays the same if the user disconnects and connects again.
 
 ## 4 · The two routes
 
@@ -137,63 +139,70 @@ That file serves `/api/one/authorize` and `/api/one/callback`. For Express or pl
 
 ## 5 · Using the grant
 
+Work the way the One CLI does: find the action, read its knowledge, run it.
+
 ```ts
-const connections = await oneConnect.listConnections(userId);   // what the user granted
-const actions = await oneConnect.listActions(userId, "gmail");  // what a platform can do
+// 1. what the user granted, with the connection key per tool
+const connections = await oneConnect.listConnections(userId);
+const stripe = connections.find((c) => c.platform === "stripe");
 
+// 2. the actions that fit what you want to do, best first
+const [action] = await oneConnect.searchActions(userId, "stripe", "list invoice items");
+
+// 3. the action's guide: what it does, every field it takes, what it answers
+const guide = await oneConnect.getActionKnowledge(userId, action._id);
+console.log(guide.knowledge);   // Markdown
+
+// 4. run it: the method and path come from the action; you pass the input
 const reply = await oneConnect.runAction(userId, {
-  connectionKey: connections[0].key,
-  actionId: actions[0]._id,
-  method: actions[0].method,
-  path: actions[0].path,
+  connectionKey: stripe.key,
+  actionId: action._id,
+  body: { limit: 10 },
 });
-// { status, ok, data }
+// { status, ok, blockedByGrant, data }
 ```
 
-You never set a header: the client adds the user's credential to every call it makes.
+`runAction` does what the guide asks for: it fills `{{placeholders}}` in the path from `pathParams`, puts the connection key in the body of an action One serves itself, and sends the body the way the provider reads it.
 
-A `403` means the call is outside what the user granted. Don't retry it.
+```ts
+await oneConnect.runAction(userId, {
+  connectionKey: calendar.key,
+  actionId: action._id,
+  pathParams: { calendarId: "primary" },          // for a path like /calendars/{{calendarId}}/events
+  query: { maxResults: "10" },
+  body: { summary: "Call" },
+  encoding: "form",                               // when the guide says x-www-form-urlencoded; "multipart" for uploads
+  headers: { "Notion-Version": "2022-06-28" },    // when the guide names a header
+});
+```
+
+`listActions(userId, platform)` still lists everything a platform can do, and `runAction` still takes `method` and `path` from it if you'd rather pass them yourself.
+
+You never set an auth header: the client adds the connect key and the user's id to every call it makes.
+
+A `403` with `blockedByGrant: true` means the call is outside what the user granted. Don't retry it.
 
 Errors are `OneConnectError` with a `code`:
 
 | `code` | What it means | What to do |
 |---|---|---|
 | `not_connected` | Nothing is stored for this user. | Show the Connect button. |
-| `refresh_failed` | The grant ended (revoked or expired). 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. Your 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. |
 
-## 6 · Keeping users connected
+## 6 · Key mode notes
 
-Tokens expire, and two things keep them fresh. One is automatic. The other is yours to run.
-
-| | Who does it | When |
-|---|---|---|
-| Refresh before a call | the client, on its own | whenever you call One and the token is about to expire |
-| Refresh for users who have not called in a while | **you**, with a daily job | once a day, for every connected user |
-
-```ts
-// run once a day
-for (const userId of await db.oneTokens.allUserIds()) {
-  await oneConnect.refreshIfExpiring(userId, { withinMs: 3 * 24 * 3_600_000 });
-}
-```
-
-The job renews both tokens when either is within 3 days of expiring. 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.
-
-The access token lives as long as your app's **Token lifetime** says: 30 days unless you changed it under **Advanced** when creating or editing the app. Keep the job's window shorter than that, or every run refreshes.
+- Keep the connect key on the server, in an environment variable. It is bound to your app and does nothing without a user's id.
+- Connect keys work in Production only. Create the key with your dashboard on Production.
+- `isConnected(userId)` says whether 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`.
+- `oneConnect.getConnectUserId(userId)` returns the user's One id (`cu_…`) if you want it for your own records.
+- Lost or leaked a key? Create another on the app's page, move your servers to it, then revoke the old one there.
 
 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.
 
-## 7 · Key mode
-
-A second way to hold a grant: one **connect key** for your app and one permanent id per user, with nothing to refresh. The button, the routes and the calls stay the same.
+## 7 · Token mode
 
-Two limits today, so use token mode unless you have a reason not to:
-
-- `listActions` does not work in key mode yet. Your app has to know the actions it runs.
-- It works in Production only. Create the key with your dashboard on Production.
-
-Create the key on your app's page, under **Credentials → Connect key**. It is shown once. Keep it on the server as `ONE_CONNECT_KEY`.
+The other way to hold a grant: your server stores an access token and a refresh token per user, as a standard OAuth client. The button, the routes and the calls stay the same. Use it when you need bearer tokens, or when the app already has them; an app that passes only a `tokenStore` keeps running in token mode with no change.
 
 ```ts
 export const oneConnect = createOneConnect({
@@ -201,19 +210,36 @@ 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) => db.users.update(userId, { oneConnect: reference }),
-    loadUser: async (userId) => (await db.users.find(userId))?.oneConnect ?? null,
-    clearUser: (userId) => db.users.update(userId, { oneConnect: null }),
+  tokenStore: {
+    saveTokens: (userId, tokens) => db.oneTokens.upsert(userId, tokens),
+    loadTokens: (userId) => db.oneTokens.find(userId),
+    clearTokens: (userId) => db.oneTokens.delete(userId),
   },
 });
 ```
 
-- `reference` is one short string. Save it in one column and hand it back unchanged. It is an identifier, not a secret.
-- When a user revokes access, the next call throws `reconnect_required` instead of `refresh_failed`. Ask them to connect again; your stored value is kept.
-- A `403` reply carries `blockedByGrant: true` when the call is outside what the user granted.
-- The mode is whichever credential you pass: `tokenStore` for token mode, `connectKey` and `userStore` for key mode. `oneConnect.mode` tells you which one is running.
+- Store the tokens in your database, encrypted, keyed by your user id.
+- 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.
+- When a user revokes access, the next refresh throws `refresh_failed` and the tokens are cleared. Ask them to connect again.
+- A `403` means the call is outside what the user granted; `blockedByGrant` stays `false` in token mode.
+
+**Keeping users connected.** Tokens expire, and two things keep them fresh. One is automatic. The other is yours to run.
+
+| | Who does it | When |
+|---|---|---|
+| Refresh before a call | the client, on its own | whenever you call One and the token is about to expire |
+| Refresh for users who have not called in a while | **you**, with a daily job | once a day, for every connected user |
+
+```ts
+// run once a day
+for (const userId of await db.oneTokens.allUserIds()) {
+  await oneConnect.refreshIfExpiring(userId, { withinMs: 3 * 24 * 3_600_000 });
+}
+```
+
+The job renews both tokens when either is within 3 days of expiring. 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. The access token lives as long as your app's **Token lifetime** says (30 days unless you changed it under **Advanced**); keep the job's window shorter than that, or every run refreshes.
+
+The mode is whichever credential you pass: `connectKey` and `userStore` for key mode, `tokenStore` for token mode. `oneConnect.mode` tells you which one is running.
 
 ## License
 

package/dist/server/index.cjs.js

@@ -153,6 +153,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.
@@ -468,15 +474,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. */
 
@@ -651,29 +695,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({
@@ -681,19 +730,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) {
@@ -737,6 +857,8 @@ function createOneConnect(config) {
     disconnect: credential.disconnect,
     listConnections,
     listActions,
+    searchActions,
+    getActionKnowledge,
     runAction,
     fetch: oneFetch
   };
@@ -761,6 +883,8 @@ function createOneConnect(config) {
 exports.OneConnectError = OneConnectError;
 exports.createOneConnect = createOneConnect;
 exports.encodeUserReference = encodeUserReference;
+exports.fillPath = fillPath;
+exports.formEncode = formEncode;
 exports.parseUserReference = parseUserReference;
 exports.refreshTokenExpiresAt = refreshTokenExpiresAt;
 exports.tenancyHeaders = tenancyHeaders;

package/dist/server/index.d.ts

@@ -1,7 +1,13 @@
-import { type CompleteAuthorizationInput, type CompleteAuthorizationResult, type OneConnectKeyConfig, type OneConnectMode, type OneConnectServerConfig, type OneConnectTokenConfig, type OneConnectTokens, type PlatformAction, type ReachableConnection, type RefreshIfExpiringOptions, type RunActionInput, type RunActionResult, type StartAuthorizationInput, type StartAuthorizationResult } from "./types";
+import { type ActionKnowledge, type CompleteAuthorizationInput, type CompleteAuthorizationResult, type OneConnectKeyConfig, type OneConnectMode, type OneConnectServerConfig, type OneConnectTokenConfig, type OneConnectTokens, type PlatformAction, type ReachableConnection, type RefreshIfExpiringOptions, type RunActionInput, type RunActionResult, type SearchActionsOptions, type StartAuthorizationInput, type StartAuthorizationResult } from "./types";
 export * from "./types";
 export { encodeUserReference, parseUserReference } from "./key";
 export { refreshTokenExpiresAt, tenancyHeaders, tokenScopes } from "./oauth";
+/** Fills a path's `{{placeholders}}`. A placeholder with no value is an
+ *  error the caller can read, rather than a request One cannot route. */
+export declare function fillPath(path: string, params?: Record<string, string | number | boolean>): string;
+/** `application/x-www-form-urlencoded` with nested objects and arrays in
+ *  bracket notation, as Stripe and other form providers read it. */
+export declare function formEncode(value: unknown): string;
 /** What an app does with One in either mode. */
 export interface OneConnectClient {
     /** How this client holds each user's grant. */
@@ -24,7 +30,13 @@ export interface OneConnectClient {
     /** Every catalog action of a platform. What exists, not what is
      *  permitted; the grant decides that when the action runs. */
     listActions: (userId: string, platform: string) => Promise<PlatformAction[]>;
-    /** Runs one action through One with the grant. */
+    /** The actions of a platform that fit a request in words, best first. */
+    searchActions: (userId: string, platform: string, query: string, options?: SearchActionsOptions) => Promise<PlatformAction[]>;
+    /** An action's guide, input shape, method and path. Read it before
+     *  running an action for the first time. */
+    getActionKnowledge: (userId: string, actionId: string) => Promise<ActionKnowledge>;
+    /** Runs one action through One with the grant: fills the path, encodes
+     *  the body, adds what the action needs. */
     runAction: (userId: string, input: RunActionInput) => Promise<RunActionResult>;
     /** Any authenticated request to One's /v1 API, headers handled. */
     fetch: (userId: string, path: string, init?: RequestInit) => Promise<Response>;