@withone/connect 0.13.2 → 0.15.0

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/dist/svelte.d.ts

@@ -5,7 +5,7 @@
  * Svelte compiler or dependency is involved:
  *
  *   <div use:connectButton={{ authorizeUrl: "/api/one/authorize",
- *     platforms: ["stripe", "notion"], connected: data.hasOneGrant,
+ *     logos: ["stripe", "notion"], connected: data.hasOneGrant,
  *     onSuccess: () => { ... } }} />
  */
 import { type ConnectButtonProps } from "@withone/connect";

package/dist/types.d.ts

@@ -27,8 +27,6 @@ export interface OneConnectFlowOptions {
     /** Theme for One's hosted page. Carried on the URL fragment, which
      *  survives the redirect chain, so the backend forwards nothing. */
     connectTheme?: OneConnectTheme;
-    /** @deprecated Renamed to `connectTheme`; removed in the next minor. */
-    appTheme?: OneConnectTheme;
     /** The grant completed and the backend stored the tokens. Fires once
      *  per page load, on the first flow still mounted when the tab
      *  returns. Treat it as a hint to refetch: your server is the truth. */
@@ -55,21 +53,26 @@ export interface OneConnectReturn {
     message?: string;
 }
 /**
- * A connector chip on the button. Pass One's connector slug ("stripe",
+ * A logo chip on the button. Pass One's connector slug ("stripe",
  * "google-calendar") and the SDK shows its logo and name; pass an
- * object to override either.
+ * object to override either. Decoration only: what One asks the user
+ * for comes from the app's permission set, not from this list.
  */
-export type ConnectButtonPlatformInput = string | {
+export type ConnectButtonLogoInput = string | {
     slug?: string;
     name?: string;
     imageUrl?: string;
 };
 /** A normalized chip: what the button actually draws. */
-export interface ConnectButtonPlatform {
+export interface ConnectButtonLogo {
     slug: string;
     name: string;
     imageUrl: string;
 }
+/** @deprecated Renamed to `ConnectButtonLogoInput`; removed in the next minor. */
+export type ConnectButtonPlatformInput = ConnectButtonLogoInput;
+/** @deprecated Renamed to `ConnectButtonLogo`; removed in the next minor. */
+export type ConnectButtonPlatform = ConnectButtonLogo;
 export type ConnectButtonVariant = "default" | "accent" | "block";
 export type ConnectButtonSize = "sm" | "md" | "lg";
 export type ConnectButtonState = "idle" | "connecting" | "connected";
@@ -78,17 +81,22 @@ export type ConnectButtonState = "idle" | "connecting" | "connected";
 export interface ConnectButtonProps {
     /** The app's own backend authorize route; relative is fine. */
     authorizeUrl: string;
-    /** Connector slugs, or objects that override the name or the logo.
-     *  The first three draw as logos; the rest fold into a "+N" chip. */
-    platforms?: ConnectButtonPlatformInput[];
+    /** Logos to draw on the button: connector slugs, or objects that
+     *  override the name or the image. The first three draw; the rest fold
+     *  into a "+N" chip. Decoration only; the permission set decides what
+     *  One asks for. */
+    logos?: ConnectButtonLogoInput[];
+    /** @deprecated Renamed to `logos`; removed in the next minor. */
+    platforms?: ConnectButtonLogoInput[];
     /** Whether this user has a live grant, from your server. When set, it
      *  decides the Connected state. When omitted, the button shows
      *  Connected only right after a successful return. */
     connected?: boolean;
     /** Not clickable, for example until terms are accepted. */
     disabled?: boolean;
-    /** default = neutral, accent = your brand colour, block = a card with
-     *  a description and a "Secured by One" foot. */
+    /** default = neutral, accent = your brand colour (set
+     *  `--one-connect-accent` and `--one-connect-accent-fg` on the host),
+     *  block = a card with a description and a "Secured by One" foot. */
     variant?: ConnectButtonVariant;
     size?: ConnectButtonSize;
     /** Stretches to the width of its container. */
@@ -97,11 +105,6 @@ export interface ConnectButtonProps {
     theme?: ConnectButtonTheme;
     /** Theme of One's hosted page. */
     connectTheme?: OneConnectTheme;
-    /** @deprecated Renamed to `connectTheme`; removed in the next minor. */
-    appTheme?: OneConnectTheme;
-    /** Fill of the accent variant; One's lime when omitted. The label is
-     *  black or white, whichever reads better on it. */
-    accentColor?: string;
     /** "Connect your apps" unless set. */
     label?: string;
     /** "Connected" unless set. */