@withone/connect 0.22.1 → 0.23.0

package/README.md

@@ -516,7 +516,7 @@ The job renews both tokens when either is within 3 days of expiring. Without it,
 
 | Method | Mode | |
 |---|---|---|
-| `listConnections(userId)` | both | The connections the grant reaches, each with its `access`. |
+| `listConnections(userId, { limit?, page? })` | both | The connections the grant reaches, each with its `access`. Every one of them by default; pass `page` (1-based) and `limit` (up to 150) for one page. |
 | `searchActions(userId, platform, query, { limit?, mode? })` | both | Best matches first, 5 by default. `mode` is `"execute"` or `"knowledge"`. |
 | `getActionKnowledge(userId, actionId)` | both | The action's guide, input shape, method and path. |
 | `listActions(userId, platform)` | both | Every action of a platform. |

package/dist/server/index.cjs.js

@@ -543,6 +543,9 @@ function oneRefusal(response, data) {
   return "one_error";
 }
 const CATALOG_PAGE_SIZE = 100;
+/** One's largest page; reading every connection takes the fewest calls. */
+const CONNECTIONS_PAGE_SIZE = 150;
+const CONNECTIONS_MAX_PAGES = 20;
 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);
@@ -750,15 +753,32 @@ function createOneConnect(config) {
     if (verdict?.code === refused.code) return false;
     throw verdict ?? new OneConnectError("request_failed", `One could not confirm the user's consent (HTTP ${probe.status}). Nothing stored was changed; try again.`, probe.status);
   };
-  const listConnections = async userId => {
-    const response = await oneFetch(userId, "/connections/reachable");
+  const connectionsPage = async (userId, limit, page) => {
+    const response = await oneFetch(userId, `/connections/reachable?limit=${limit}&page=${page}`);
     if (!response.ok) {
       const refused = credential.refusal(response.status, await response.text());
       if (refused) throw refused;
       throw new OneConnectError("request_failed", `One refused the connections request (HTTP ${response.status}).`, response.status);
     }
-    const body = await response.json();
-    return body.rows ?? [];
+    return await response.json();
+  };
+
+  /**
+   * One page when the caller names one; otherwise every page, so a user
+   * with more connections than one page holds is never cut short. A page
+   * that fails fails the whole list rather than returning part of it.
+   */
+  const listConnections = async (userId, options = {}) => {
+    if (options.page !== undefined || options.limit !== undefined) {
+      const page = await connectionsPage(userId, Math.max(1, Math.floor(options.limit ?? 20)), Math.max(1, Math.floor(options.page ?? 1)));
+      return page.rows ?? [];
+    }
+    const first = await connectionsPage(userId, CONNECTIONS_PAGE_SIZE, 1);
+    const pages = Math.min(Math.max(first.pages ?? 1, 1), CONNECTIONS_MAX_PAGES);
+    const rest = await Promise.all(Array.from({
+      length: pages - 1
+    }, (_, index) => connectionsPage(userId, CONNECTIONS_PAGE_SIZE, index + 2)));
+    return [first, ...rest].flatMap(page => page.rows ?? []);
   };
 
   /**

package/dist/server/index.d.ts

@@ -1,4 +1,4 @@
-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";
+import { type ActionKnowledge, type CompleteAuthorizationInput, type CompleteAuthorizationResult, type OneConnectKeyConfig, type OneConnectMode, type OneConnectServerConfig, type OneConnectTokenConfig, type OneConnectTokens, type PlatformAction, type ListConnectionsOptions, 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";
@@ -25,8 +25,9 @@ export interface OneConnectClient {
     /** Drops the app's copy of what it stored. The user revokes the grant
      *  itself from their One dashboard. */
     disconnect: (userId: string) => Promise<void>;
-    /** The connections the grant reaches, each with its access. */
-    listConnections: (userId: string) => Promise<ReachableConnection[]>;
+    /** The connections the grant reaches, each with its access: every one
+     *  of them, or a single page when `page` or `limit` is given. */
+    listConnections: (userId: string, options?: ListConnectionsOptions) => Promise<ReachableConnection[]>;
     /** 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[]>;

package/dist/server/index.esm.js

@@ -541,6 +541,9 @@ function oneRefusal(response, data) {
   return "one_error";
 }
 const CATALOG_PAGE_SIZE = 100;
+/** One's largest page; reading every connection takes the fewest calls. */
+const CONNECTIONS_PAGE_SIZE = 150;
+const CONNECTIONS_MAX_PAGES = 20;
 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);
@@ -748,15 +751,32 @@ function createOneConnect(config) {
     if (verdict?.code === refused.code) return false;
     throw verdict ?? new OneConnectError("request_failed", `One could not confirm the user's consent (HTTP ${probe.status}). Nothing stored was changed; try again.`, probe.status);
   };
-  const listConnections = async userId => {
-    const response = await oneFetch(userId, "/connections/reachable");
+  const connectionsPage = async (userId, limit, page) => {
+    const response = await oneFetch(userId, `/connections/reachable?limit=${limit}&page=${page}`);
     if (!response.ok) {
       const refused = credential.refusal(response.status, await response.text());
       if (refused) throw refused;
       throw new OneConnectError("request_failed", `One refused the connections request (HTTP ${response.status}).`, response.status);
     }
-    const body = await response.json();
-    return body.rows ?? [];
+    return await response.json();
+  };
+
+  /**
+   * One page when the caller names one; otherwise every page, so a user
+   * with more connections than one page holds is never cut short. A page
+   * that fails fails the whole list rather than returning part of it.
+   */
+  const listConnections = async (userId, options = {}) => {
+    if (options.page !== undefined || options.limit !== undefined) {
+      const page = await connectionsPage(userId, Math.max(1, Math.floor(options.limit ?? 20)), Math.max(1, Math.floor(options.page ?? 1)));
+      return page.rows ?? [];
+    }
+    const first = await connectionsPage(userId, CONNECTIONS_PAGE_SIZE, 1);
+    const pages = Math.min(Math.max(first.pages ?? 1, 1), CONNECTIONS_MAX_PAGES);
+    const rest = await Promise.all(Array.from({
+      length: pages - 1
+    }, (_, index) => connectionsPage(userId, CONNECTIONS_PAGE_SIZE, index + 2)));
+    return [first, ...rest].flatMap(page => page.rows ?? []);
   };
 
   /**

package/dist/server/types.d.ts

@@ -216,6 +216,14 @@ export interface PlatformAction {
      *  serves, which takes the connection key in its body. */
     tags?: string[];
 }
+export interface ListConnectionsOptions {
+    /** Return just this page, 1-based. Omit it (and `limit`) to get every
+     *  connection the grant reaches. */
+    page?: number;
+    /** Connections per page when asking for one page. One caps it at 150;
+     *  20 when omitted. */
+    limit?: number;
+}
 export interface SearchActionsOptions {
     /** How many candidates to return. Five when omitted. */
     limit?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/connect",
-  "version": "0.22.1",
+  "version": "0.23.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/src/server/index.ts

@@ -56,6 +56,7 @@ import {
   type OneConnectTokenConfig,
   type OneConnectTokens,
   type PlatformAction,
+  type ListConnectionsOptions,
   type ReachableConnection,
   type RefreshIfExpiringOptions,
   type RunActionInput,
@@ -89,6 +90,9 @@ function oneRefusal(response: Response, data: unknown): OneRefusal | null {
 }
 
 const CATALOG_PAGE_SIZE = 100;
+/** One's largest page; reading every connection takes the fewest calls. */
+const CONNECTIONS_PAGE_SIZE = 150;
+const CONNECTIONS_MAX_PAGES = 20;
 const CATALOG_MAX_PAGES = 20;
 const SEARCH_DEFAULT_LIMIT = 5;
 
@@ -166,8 +170,12 @@ export interface OneConnectClient {
   /** Drops the app's copy of what it stored. The user revokes the grant
    *  itself from their One dashboard. */
   disconnect: (userId: string) => Promise<void>;
-  /** The connections the grant reaches, each with its access. */
-  listConnections: (userId: string) => Promise<ReachableConnection[]>;
+  /** The connections the grant reaches, each with its access: every one
+   *  of them, or a single page when `page` or `limit` is given. */
+  listConnections: (
+    userId: string,
+    options?: ListConnectionsOptions,
+  ) => Promise<ReachableConnection[]>;
   /** 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[]>;
@@ -445,8 +453,17 @@ export function createOneConnect(
     );
   };
 
-  const listConnections = async (userId: string): Promise<ReachableConnection[]> => {
-    const response = await oneFetch(userId, "/connections/reachable");
+  type ConnectionsPage = { rows?: ReachableConnection[]; pages?: number };
+
+  const connectionsPage = async (
+    userId: string,
+    limit: number,
+    page: number,
+  ): Promise<ConnectionsPage> => {
+    const response = await oneFetch(
+      userId,
+      `/connections/reachable?limit=${limit}&page=${page}`,
+    );
     if (!response.ok) {
       const refused = credential.refusal(response.status, await response.text());
       if (refused) throw refused;
@@ -456,8 +473,34 @@ export function createOneConnect(
         response.status,
       );
     }
-    const body = (await response.json()) as { rows?: ReachableConnection[] };
-    return body.rows ?? [];
+    return (await response.json()) as ConnectionsPage;
+  };
+
+  /**
+   * One page when the caller names one; otherwise every page, so a user
+   * with more connections than one page holds is never cut short. A page
+   * that fails fails the whole list rather than returning part of it.
+   */
+  const listConnections = async (
+    userId: string,
+    options: ListConnectionsOptions = {},
+  ): Promise<ReachableConnection[]> => {
+    if (options.page !== undefined || options.limit !== undefined) {
+      const page = await connectionsPage(
+        userId,
+        Math.max(1, Math.floor(options.limit ?? 20)),
+        Math.max(1, Math.floor(options.page ?? 1)),
+      );
+      return page.rows ?? [];
+    }
+    const first = await connectionsPage(userId, CONNECTIONS_PAGE_SIZE, 1);
+    const pages = Math.min(Math.max(first.pages ?? 1, 1), CONNECTIONS_MAX_PAGES);
+    const rest = await Promise.all(
+      Array.from({ length: pages - 1 }, (_, index) =>
+        connectionsPage(userId, CONNECTIONS_PAGE_SIZE, index + 2),
+      ),
+    );
+    return [first, ...rest].flatMap((page) => page.rows ?? []);
   };
 
   /**

package/src/server/types.ts

@@ -231,6 +231,15 @@ export interface PlatformAction {
   tags?: string[];
 }
 
+export interface ListConnectionsOptions {
+  /** Return just this page, 1-based. Omit it (and `limit`) to get every
+   *  connection the grant reaches. */
+  page?: number;
+  /** Connections per page when asking for one page. One caps it at 150;
+   *  20 when omitted. */
+  limit?: number;
+}
+
 export interface SearchActionsOptions {
   /** How many candidates to return. Five when omitted. */
   limit?: number;