@withone/connect 0.13.1 → 0.14.0

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 {