@withone/connect 0.23.1 → 0.24.0

package/README.md

@@ -348,9 +348,11 @@ const reply = await oneConnect.runAction(userId, {
   actionId: action._id,
   body: { limit: 10 },
 });
-// { status, ok, blockedByGrant, refusal, data }
+// { status, ok, blockedByGrant, refusal, rateLimit, data }
 ```
 
+`rateLimit` is One's limit for that user after the call: `{ limit, remaining, resetsIn, retryAfter }`, calls per minute and seconds. The app owner's plan sets the size and each of your users has a bucket of their own. Slow down as `remaining` nears 0, and on a `429` wait `retryAfter` seconds. Any value One didn't send is `null`, `limit` and `remaining` are `null` when nothing limits the user, and `rateLimit` is `null` when One sent none of them. A `402` (`refusal: "plan_limit"`) means the user's calls for the month are used up: stop calling for them until next month rather than retrying.
+
 Each connection carries its `access`: `{ policy: "full" }`, `{ policy: "methods", methods }` or `{ policy: "actions", actions }`. Plan from it before you call.
 
 `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.

package/dist/server/index.cjs.js

@@ -200,6 +200,12 @@ function tokenScopes(accessToken) {
  *   a backoff.
  */
 
+/**
+ * One's rate limit for the user a call was made for, as One reported it on
+ * that call. The app owner's plan sets the size; each of the app's users
+ * has a bucket of their own. Any value One didn't send is `null`.
+ */
+
 /**
  * - `not_connected`: nothing is stored for this user.
  * - `reconnect_required` (key mode): One will not act for this user.
@@ -542,6 +548,33 @@ function oneRefusal(response, data) {
   if (response.status === 429) return "rate_limit";
   return "one_error";
 }
+
+/**
+ * One's rate limit from a reply's headers, or `null` when it sent none of
+ * them. A missing or unreadable header reads `null` on its own and never
+ * throws. One writes "no limit" as the largest 64-bit integer, which
+ * reads as `null` too.
+ */
+function rateLimitFrom(headers) {
+  const read = name => {
+    const value = headers.get(name)?.trim();
+    if (!value) return null;
+    const number = Number(value);
+    return Number.isFinite(number) && number >= 0 ? number : null;
+  };
+  const limit = read("x-ratelimit-limit");
+  const remaining = read("x-ratelimit-remaining");
+  const resetsIn = read("x-ratelimit-reset");
+  const retryAfter = read("retry-after");
+  if (limit === null && remaining === null && resetsIn === null && retryAfter === null) return null;
+  const unlimited = limit !== null && limit > Number.MAX_SAFE_INTEGER;
+  return {
+    limit: unlimited ? null : limit,
+    remaining: unlimited ? null : remaining,
+    resetsIn,
+    retryAfter
+  };
+}
 const CATALOG_PAGE_SIZE = 100;
 /** One's largest page; reading every connection takes the fewest calls. */
 const CONNECTIONS_PAGE_SIZE = 150;
@@ -901,6 +934,7 @@ function createOneConnect(config) {
       body
     });
     const text = await response.text();
+    const rateLimit = rateLimitFrom(response.headers);
     if (!response.ok) {
       const refused = credential.refusal(response.status, text);
       if (refused?.code === "reconnect_required") {
@@ -913,6 +947,7 @@ function createOneConnect(config) {
           ok: false,
           blockedByGrant: true,
           refusal: "grant",
+          rateLimit,
           data: text
         };
         throw refused;
@@ -932,6 +967,7 @@ function createOneConnect(config) {
       ok: response.ok,
       blockedByGrant: refusal === "grant",
       refusal,
+      rateLimit,
       data
     };
   };

package/dist/server/index.esm.js

@@ -198,6 +198,12 @@ function tokenScopes(accessToken) {
  *   a backoff.
  */
 
+/**
+ * One's rate limit for the user a call was made for, as One reported it on
+ * that call. The app owner's plan sets the size; each of the app's users
+ * has a bucket of their own. Any value One didn't send is `null`.
+ */
+
 /**
  * - `not_connected`: nothing is stored for this user.
  * - `reconnect_required` (key mode): One will not act for this user.
@@ -540,6 +546,33 @@ function oneRefusal(response, data) {
   if (response.status === 429) return "rate_limit";
   return "one_error";
 }
+
+/**
+ * One's rate limit from a reply's headers, or `null` when it sent none of
+ * them. A missing or unreadable header reads `null` on its own and never
+ * throws. One writes "no limit" as the largest 64-bit integer, which
+ * reads as `null` too.
+ */
+function rateLimitFrom(headers) {
+  const read = name => {
+    const value = headers.get(name)?.trim();
+    if (!value) return null;
+    const number = Number(value);
+    return Number.isFinite(number) && number >= 0 ? number : null;
+  };
+  const limit = read("x-ratelimit-limit");
+  const remaining = read("x-ratelimit-remaining");
+  const resetsIn = read("x-ratelimit-reset");
+  const retryAfter = read("retry-after");
+  if (limit === null && remaining === null && resetsIn === null && retryAfter === null) return null;
+  const unlimited = limit !== null && limit > Number.MAX_SAFE_INTEGER;
+  return {
+    limit: unlimited ? null : limit,
+    remaining: unlimited ? null : remaining,
+    resetsIn,
+    retryAfter
+  };
+}
 const CATALOG_PAGE_SIZE = 100;
 /** One's largest page; reading every connection takes the fewest calls. */
 const CONNECTIONS_PAGE_SIZE = 150;
@@ -899,6 +932,7 @@ function createOneConnect(config) {
       body
     });
     const text = await response.text();
+    const rateLimit = rateLimitFrom(response.headers);
     if (!response.ok) {
       const refused = credential.refusal(response.status, text);
       if (refused?.code === "reconnect_required") {
@@ -911,6 +945,7 @@ function createOneConnect(config) {
           ok: false,
           blockedByGrant: true,
           refusal: "grant",
+          rateLimit,
           data: text
         };
         throw refused;
@@ -930,6 +965,7 @@ function createOneConnect(config) {
       ok: response.ok,
       blockedByGrant: refusal === "grant",
       refusal,
+      rateLimit,
       data
     };
   };

package/dist/server/types.d.ts

@@ -281,6 +281,21 @@ export interface RunActionInput {
  *   a backoff.
  */
 export type OneRefusal = "grant" | "plan_limit" | "rate_limit" | "one_error";
+/**
+ * One's rate limit for the user a call was made for, as One reported it on
+ * that call. The app owner's plan sets the size; each of the app's users
+ * has a bucket of their own. Any value One didn't send is `null`.
+ */
+export interface RateLimit {
+    /** Calls this user may make a minute. `null` when nothing limits them. */
+    limit: number | null;
+    /** Calls left in the current minute. `null` when nothing limits them. */
+    remaining: number | null;
+    /** Seconds until the minute resets. */
+    resetsIn: number | null;
+    /** Seconds to wait before trying again. Set on a 429 only. */
+    retryAfter: number | null;
+}
 export interface RunActionResult {
     status: number;
     ok: boolean;
@@ -293,6 +308,11 @@ export interface RunActionResult {
     /** Why One turned the call down, or `null` when it didn't (the call
      *  succeeded, or the provider answered with its own error). */
     refusal: OneRefusal | null;
+    /** One's rate limit for this user after the call, or `null` when One
+     *  sent none of its rate-limit headers. A `refusal` of `"plan_limit"`
+     *  (402) means this user's calls for the month are used up: back off
+     *  for the month, don't retry. */
+    rateLimit: RateLimit | null;
     data: unknown;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/connect",
-  "version": "0.23.1",
+  "version": "0.24.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

@@ -279,9 +279,13 @@ const reply = await oneConnect.runAction(userId, {
   encoding: "json",                           // or "form" / "multipart", as the guide says
   headers: {},                                // only when the guide names one
 });
-// { status, ok, blockedByGrant, refusal, data }
+// { status, ok, blockedByGrant, refusal, rateLimit, data }
 ```
 
+`rateLimit` is `{ limit, remaining, resetsIn, retryAfter }` for that user
+(calls per minute, seconds), or `null` when One sent none. Slow down as
+`remaining` nears 0; on a `429` wait `retryAfter` seconds.
+
 Each connection's `access` is `{ policy: "full" }`, `{ policy: "methods",
 methods }` or `{ policy: "actions", actions }`; plan from it before calling.
 `runAction` takes the method and path from the action, fills the path's
@@ -308,9 +312,11 @@ user's id to every call it makes.
 
 - `"grant"` (`403`, `blockedByGrant: true`): outside what the user granted.
   Do not retry it.
-- `"plan_limit"` (`402`): a plan limit, not the grant. Wait and retry later.
-  Do not ask the user to reconnect.
-- `"rate_limit"` (`429`): too many calls. Wait and retry.
+- `"plan_limit"` (`402`): the user's calls for the month are used up, not
+  the grant. Stop calling for this user until next month. Do not ask the
+  user to reconnect.
+- `"rate_limit"` (`429`): too many calls. Wait `rateLimit.retryAfter`
+  seconds and retry.
 - `"one_error"` (other, e.g. `5xx`): retry with a backoff.
 - `null`: not One's refusal; the provider's own answer, or a success.
 

package/src/server/index.ts

@@ -29,7 +29,11 @@
  * The Next.js and Node adapters turn the first two into route handlers.
  * See `./key` and `./token` for what each mode stores and sends.
  */
-import { DEFAULT_ONE_API_URL, RETURN_ERROR_PARAM, RETURN_STATUS_PARAM } from "../constants";
+import {
+  DEFAULT_ONE_API_URL,
+  RETURN_ERROR_PARAM,
+  RETURN_STATUS_PARAM,
+} from "../constants";
 import type { Credential, PostToken, TokenResponse } from "./credential";
 import { createKeyCredential } from "./key";
 import {
@@ -61,6 +65,7 @@ import {
   type RefreshIfExpiringOptions,
   type RunActionInput,
   type OneRefusal,
+  type RateLimit,
   type RunActionResult,
   type SearchActionsOptions,
   type StartAuthorizationInput,
@@ -81,7 +86,9 @@ export { refreshTokenExpiresAt, tenancyHeaders, tokenScopes } from "./oauth";
 function oneRefusal(response: Response, data: unknown): OneRefusal | null {
   if (response.ok) return null;
   const fromOne =
-    typeof data === "object" && data !== null && "correlationId" in (data as Record<string, unknown>);
+    typeof data === "object" &&
+    data !== null &&
+    "correlationId" in (data as Record<string, unknown>);
   if (!fromOne) return null;
   if (response.status === 403) return "grant";
   if (response.status === 402) return "plan_limit";
@@ -89,6 +96,39 @@ function oneRefusal(response: Response, data: unknown): OneRefusal | null {
   return "one_error";
 }
 
+/**
+ * One's rate limit from a reply's headers, or `null` when it sent none of
+ * them. A missing or unreadable header reads `null` on its own and never
+ * throws. One writes "no limit" as the largest 64-bit integer, which
+ * reads as `null` too.
+ */
+function rateLimitFrom(headers: Headers): RateLimit | null {
+  const read = (name: string): number | null => {
+    const value = headers.get(name)?.trim();
+    if (!value) return null;
+    const number = Number(value);
+    return Number.isFinite(number) && number >= 0 ? number : null;
+  };
+  const limit = read("x-ratelimit-limit");
+  const remaining = read("x-ratelimit-remaining");
+  const resetsIn = read("x-ratelimit-reset");
+  const retryAfter = read("retry-after");
+  if (
+    limit === null &&
+    remaining === null &&
+    resetsIn === null &&
+    retryAfter === null
+  )
+    return null;
+  const unlimited = limit !== null && limit > Number.MAX_SAFE_INTEGER;
+  return {
+    limit: unlimited ? null : limit,
+    remaining: unlimited ? null : remaining,
+    resetsIn,
+    retryAfter,
+  };
+}
+
 const CATALOG_PAGE_SIZE = 100;
 /** One's largest page; reading every connection takes the fewest calls. */
 const CONNECTIONS_PAGE_SIZE = 150;
@@ -128,7 +168,9 @@ export function formEncode(value: unknown): string {
   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));
+      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);
@@ -188,10 +230,16 @@ export interface OneConnectClient {
   ) => 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>;
+  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>;
+  runAction: (
+    userId: string,
+    input: RunActionInput,
+  ) => Promise<RunActionResult>;
   /** Any authenticated request to One's /v1 API, headers handled. */
   fetch: (
     userId: string,
@@ -235,9 +283,11 @@ export interface OneConnect extends OneConnectClient {
  * so an app written before key mode existed keeps working untouched.
  */
 function resolveMode(config: OneConnectServerConfig): OneConnectMode {
-  const given = config as Partial<OneConnectKeyConfig> & Partial<OneConnectTokenConfig>;
+  const given = config as Partial<OneConnectKeyConfig> &
+    Partial<OneConnectTokenConfig>;
   const mode: OneConnectMode | undefined =
-    given.mode ?? (given.connectKey ? "key" : given.tokenStore ? "token" : undefined);
+    given.mode ??
+    (given.connectKey ? "key" : given.tokenStore ? "token" : undefined);
   if (mode === undefined) {
     throw new TypeError(
       "createOneConnect needs a credential: pass `connectKey` and `userStore` (key mode, recommended), or `tokenStore` (token mode).",
@@ -258,7 +308,9 @@ function resolveMode(config: OneConnectServerConfig): OneConnectMode {
 }
 
 /** Key mode: a connect key for the app and one permanent id per user. */
-export function createOneConnect(config: OneConnectKeyConfig): OneConnectKeyClient;
+export function createOneConnect(
+  config: OneConnectKeyConfig,
+): OneConnectKeyClient;
 /** Token mode: an access and a refresh token per user, kept fresh. */
 export function createOneConnect(config: OneConnectTokenConfig): OneConnect;
 export function createOneConnect(
@@ -268,7 +320,10 @@ export function createOneConnect(
   config: OneConnectServerConfig,
 ): OneConnectKeyClient | OneConnect {
   const mode = resolveMode(config);
-  const oneApiUrl = (config.oneApiUrl ?? DEFAULT_ONE_API_URL).replace(/\/+$/, "");
+  const oneApiUrl = (config.oneApiUrl ?? DEFAULT_ONE_API_URL).replace(
+    /\/+$/,
+    "",
+  );
   const authorizeUrl = `${oneApiUrl}/oauth/authorize`;
   const tokenUrl = `${oneApiUrl}/oauth/token`;
   const apiUrl = `${oneApiUrl}/v1`;
@@ -330,7 +385,10 @@ export function createOneConnect(
       : null;
   const tokenCredential =
     mode === "token"
-      ? createTokenCredential((config as OneConnectTokenConfig).tokenStore, postToken)
+      ? createTokenCredential(
+          (config as OneConnectTokenConfig).tokenStore,
+          postToken,
+        )
       : null;
   const credential = (keyCredential ?? tokenCredential) as Credential;
 
@@ -352,7 +410,12 @@ export function createOneConnect(
     if (input.loginHint) url.searchParams.set("login_hint", input.loginHint);
     return {
       redirectUrl: url.toString(),
-      cookie: txCookie(state, verifier, config.redirectUri, appPath(input.returnTo)),
+      cookie: txCookie(
+        state,
+        verifier,
+        config.redirectUri,
+        appPath(input.returnTo),
+      ),
     };
   };
 
@@ -387,7 +450,10 @@ export function createOneConnect(
     // The returned state names its own cookie. No cookie means a stale,
     // foreign or forged state; the code is never exchanged in that case.
     if (!code || !state || !verifier)
-      return fail("expired", "The attempt expired, or its state cookie was missing.");
+      return fail(
+        "expired",
+        "The attempt expired, or its state cookie was missing.",
+      );
 
     try {
       const response = await exchange(
@@ -401,7 +467,8 @@ export function createOneConnect(
       // Tokens in token mode, the user's permanent id in key mode.
       await credential.connected(input.userId, response);
     } catch (error) {
-      const status = error instanceof OneConnectError ? error.status : undefined;
+      const status =
+        error instanceof OneConnectError ? error.status : undefined;
       return fail(
         "failed",
         status
@@ -425,7 +492,9 @@ export function createOneConnect(
     init: RequestInit = {},
   ): Promise<Response> => {
     const headers = new Headers(init.headers);
-    for (const [name, value] of Object.entries(await credential.headers(userId)))
+    for (const [name, value] of Object.entries(
+      await credential.headers(userId),
+    ))
       headers.set(name, value);
     return fetch(`${apiUrl}${path.startsWith("/") ? path : `/${path}`}`, {
       ...init,
@@ -438,7 +507,10 @@ export function createOneConnect(
    * that needs nothing but the credential. Throws when the question
    * itself cannot be answered, rather than guessing.
    */
-  const consentStands = async (userId: string, refused: OneConnectError): Promise<boolean> => {
+  const consentStands = async (
+    userId: string,
+    refused: OneConnectError,
+  ): Promise<boolean> => {
     const probe = await oneFetch(userId, "/connections/reachable?limit=1");
     if (probe.ok) return true;
     const verdict = credential.refusal(probe.status, await probe.text());
@@ -465,7 +537,10 @@ export function createOneConnect(
       `/connections/reachable?limit=${limit}&page=${page}`,
     );
     if (!response.ok) {
-      const refused = credential.refusal(response.status, await response.text());
+      const refused = credential.refusal(
+        response.status,
+        await response.text(),
+      );
       if (refused) throw refused;
       throw new OneConnectError(
         "request_failed",
@@ -494,7 +569,10 @@ export function createOneConnect(
       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 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),
@@ -558,7 +636,9 @@ export function createOneConnect(
         oneFetch(userId, pageUrl(index + 2))
           .then((response) =>
             response.ok
-              ? (response.json() as Promise<{ rows?: Record<string, unknown>[] }>)
+              ? (response.json() as Promise<{
+                  rows?: Record<string, unknown>[];
+                }>)
               : null,
           )
           .catch(() => null),
@@ -578,32 +658,46 @@ export function createOneConnect(
     const params = new URLSearchParams({
       query,
       limit: String(options.limit ?? SEARCH_DEFAULT_LIMIT),
-      [options.mode === "knowledge" ? "knowledgeAgent" : "executeAgent"]: "true",
+      [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);
+    if (!response.ok)
+      throw await catalogRefusal(userId, "action search", response);
     const body = (await response.json()) as
-      | Record<string, unknown>[]
-      | { rows?: Record<string, unknown>[] };
+      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 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 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);
+        throw new OneConnectError(
+          "request_failed",
+          `One has no action with the id ${actionId}.`,
+          404,
+        );
       return toKnowledge(row);
     })();
     knowledgeCache.set(actionId, loading);
@@ -631,7 +725,8 @@ export function createOneConnect(
     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);
+      for (const item of Array.isArray(value) ? value : [value])
+        search.append(key, item);
     const query = search.size ? `?${search}` : "";
 
     const headers: Record<string, string> = {
@@ -656,7 +751,9 @@ export function createOneConnect(
         body = formEncode(payload);
       } else if (encoding === "multipart") {
         const form = new FormData();
-        for (const [key, value] of Object.entries(isPlainObject(payload) ? payload : {}))
+        for (const [key, value] of Object.entries(
+          isPlainObject(payload) ? payload : {},
+        ))
           form.append(
             key,
             value instanceof Blob
@@ -678,6 +775,7 @@ export function createOneConnect(
       body,
     });
     const text = await response.text();
+    const rateLimit = rateLimitFrom(response.headers);
     if (!response.ok) {
       const refused = credential.refusal(response.status, text);
       if (refused?.code === "reconnect_required") {
@@ -686,7 +784,14 @@ export function createOneConnect(
         // tells them apart: if that still answers, the consent stands
         // and it was this call One refused.
         if (await consentStands(userId, refused))
-          return { status: response.status, ok: false, blockedByGrant: true, refusal: "grant", data: text };
+          return {
+            status: response.status,
+            ok: false,
+            blockedByGrant: true,
+            refusal: "grant",
+            rateLimit,
+            data: text,
+          };
         throw refused;
       }
       // One refusing the credential is not an answer to the action.
@@ -699,7 +804,14 @@ export function createOneConnect(
       /* the provider answered with something other than JSON */
     }
     const refusal = oneRefusal(response, data);
-    return { status: response.status, ok: response.ok, blockedByGrant: refusal === "grant", refusal, data };
+    return {
+      status: response.status,
+      ok: response.ok,
+      blockedByGrant: refusal === "grant",
+      refusal,
+      rateLimit,
+      data,
+    };
   };
 
   const shared = {

package/src/server/types.ts

@@ -144,7 +144,8 @@ export interface OneConnectTokenConfig extends OneConnectBaseConfig {
  * mode, a `tokenStore` alone is token mode. Set `mode` to say so
  * explicitly.
  */
-export type OneConnectServerConfig = OneConnectKeyConfig | OneConnectTokenConfig;
+export type OneConnectServerConfig =
+  OneConnectKeyConfig | OneConnectTokenConfig;
 
 /** The transaction cookie the authorize leg sets and the callback reads. */
 export interface OneConnectCookie {
@@ -302,6 +303,22 @@ export interface RunActionInput {
  */
 export type OneRefusal = "grant" | "plan_limit" | "rate_limit" | "one_error";
 
+/**
+ * One's rate limit for the user a call was made for, as One reported it on
+ * that call. The app owner's plan sets the size; each of the app's users
+ * has a bucket of their own. Any value One didn't send is `null`.
+ */
+export interface RateLimit {
+  /** Calls this user may make a minute. `null` when nothing limits them. */
+  limit: number | null;
+  /** Calls left in the current minute. `null` when nothing limits them. */
+  remaining: number | null;
+  /** Seconds until the minute resets. */
+  resetsIn: number | null;
+  /** Seconds to wait before trying again. Set on a 429 only. */
+  retryAfter: number | null;
+}
+
 export interface RunActionResult {
   status: number;
   ok: boolean;
@@ -314,6 +331,11 @@ export interface RunActionResult {
   /** Why One turned the call down, or `null` when it didn't (the call
    *  succeeded, or the provider answered with its own error). */
   refusal: OneRefusal | null;
+  /** One's rate limit for this user after the call, or `null` when One
+   *  sent none of its rate-limit headers. A `refusal` of `"plan_limit"`
+   *  (402) means this user's calls for the month are used up: back off
+   *  for the month, don't retry. */
+  rateLimit: RateLimit | null;
   data: unknown;
 }
 
@@ -329,10 +351,7 @@ export interface RunActionResult {
  *   reached. Nothing stored was changed, so retry later.
  */
 export type OneConnectErrorCode =
-  | "not_connected"
-  | "reconnect_required"
-  | "refresh_failed"
-  | "request_failed";
+  "not_connected" | "reconnect_required" | "refresh_failed" | "request_failed";
 
 export class OneConnectError extends Error {
   readonly code: OneConnectErrorCode;