@withone/connect 0.13.2 → 0.14.0

package/README.md

@@ -139,20 +139,46 @@ 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, blockedByGrant, data }
 ```
 
-You never set a header: the client adds the connect key and the user's id 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.
+
+```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.
 

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>;

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.2",
+  "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

@@ -128,22 +128,34 @@ A custom button in React: `useOneConnect({ authorizeUrl })` returns `{ open, sta
 
 ## 6 - 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, blockedByGrant, data }
 ```
 
-Do not set any header. The package adds the connect key and the user's id
-to every call it makes.
+`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 with `blockedByGrant: true` means the call is outside what
 the user granted. Do not retry it.

package/src/server/index.ts

@@ -19,9 +19,12 @@
  *   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.
@@ -41,6 +44,7 @@ import {
 import { createTokenCredential } from "./token";
 import {
   OneConnectError,
+  type ActionKnowledge,
   type CompleteAuthorizationInput,
   type CompleteAuthorizationResult,
   type ConnectFailureCode,
@@ -54,6 +58,7 @@ import {
   type RefreshIfExpiringOptions,
   type RunActionInput,
   type RunActionResult,
+  type SearchActionsOptions,
   type StartAuthorizationInput,
   type StartAuthorizationResult,
 } from "./types";
@@ -64,6 +69,60 @@ export { refreshTokenExpiresAt, tenancyHeaders, tokenScopes } from "./oauth";
 
 const CATALOG_PAGE_SIZE = 100;
 const CATALOG_MAX_PAGES = 20;
+const SEARCH_DEFAULT_LIMIT = 5;
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  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. */
+export function fillPath(
+  path: string,
+  params: Record<string, string | number | boolean> = {},
+): string {
+  return path.replace(/\{\{([^}]+)\}\}/g, (_match, name: string) => {
+    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. */
+export function formEncode(value: unknown): string {
+  const out = new URLSearchParams();
+  const walk = (prefix: string, v: unknown) => {
+    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 as Record<string, unknown>))
+        walk(prefix ? `${prefix}[${k}]` : k, inner);
+    else out.append(prefix, String(v));
+  };
+  walk("", value);
+  return out.toString();
+}
+
+const toKnowledge = (row: Record<string, unknown>): ActionKnowledge => ({
+  _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. */
 export interface OneConnectClient {
@@ -91,7 +150,18 @@ 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: (
@@ -362,42 +432,51 @@ export function createOneConnect(
     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: string,
+    what: string,
+    response: Response,
+  ): Promise<OneConnectError> => {
+    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: Record<string, unknown>[]): PlatformAction[] =>
+    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: string,
     platform: string,
   ): Promise<PlatformAction[]> => {
     const pageUrl = (page: number) =>
       `/knowledge?connectionPlatform=${encodeURIComponent(platform)}&limit=${CATALOG_PAGE_SIZE}&page=${page}`;
-    const slim = (rows: Record<string, unknown>[]): PlatformAction[] =>
-      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()) as {
       rows?: Record<string, unknown>[];
       pages?: number;
@@ -417,22 +496,115 @@ export function createOneConnect(
     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: string,
+    platform: string,
+    query: string,
+    options: SearchActionsOptions = {},
+  ): Promise<PlatformAction[]> => {
+    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()) as
+      | Record<string, unknown>[]
+      | { rows?: Record<string, unknown>[] };
+    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<string, Promise<ActionKnowledge>>();
+  const getActionKnowledge = (userId: string, actionId: string): Promise<ActionKnowledge> => {
+    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()) as { rows?: Record<string, unknown>[] };
+      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: string,
     input: RunActionInput,
   ): Promise<RunActionResult> => {
-    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: [] as string[] }
+        : 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: Record<string, string> = {
+      ...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: unknown = 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: BodyInit | undefined;
+    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) {
@@ -472,6 +644,8 @@ export function createOneConnect(
     disconnect: credential.disconnect,
     listConnections,
     listActions,
+    searchActions,
+    getActionKnowledge,
     runAction,
     fetch: oneFetch,
   };

package/src/server/types.ts

@@ -221,18 +221,58 @@ 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 {