@withone/connect 0.17.0 → 0.17.1

package/README.md

@@ -281,7 +281,7 @@ const reply = await oneConnect.runAction(userId, {
   actionId: action._id,
   body: { limit: 10 },
 });
-// { status, ok, blockedByGrant, data }
+// { status, ok, blockedByGrant, refusal, data }
 ```
 
 Each connection carries its `access`: `{ policy: "full" }`, `{ policy: "methods", methods }` or `{ policy: "actions", actions }`. Plan from it before you call.
@@ -306,7 +306,15 @@ You never set an auth header: the client adds the connect key and the user's id
 
 ## 6 · Errors
 
-A `403` with `blockedByGrant: true` means the call is outside what the user granted. The provider was never called; don't retry it.
+When One itself turns a call down, `runAction` says why in `refusal`:
+
+| `refusal` | Status | What to do |
+|---|---|---|
+| `"grant"` (`blockedByGrant: true`) | `403` | The call is outside what the user granted. The provider was never called; don't retry it. |
+| `"plan_limit"` | `402` | A plan limit, not the grant. Wait and retry later; don't ask the user to reconnect. |
+| `"rate_limit"` | `429` | Too many calls. Wait and retry. |
+| `"one_error"` | other, e.g. `5xx` | Retry with a backoff. |
+| `null` | any | Not One's refusal: the provider's own answer, or a success. |
 
 Everything else is a `OneConnectError` with a `code`:
 
@@ -393,6 +401,7 @@ The job renews both tokens when either is within 3 days of expiring. Without it,
 | Every call fails with `request_failed`: "One did not accept the connect key" | The key is not this app's, or it was revoked. Create a key on the app's page and update `ONE_CONNECT_KEY`. |
 | Every user's calls throw `reconnect_required` | The app is deactivated. Check that it is active in the dashboard. |
 | A call returns `403` with `blockedByGrant: true` | The action is outside what the user granted. Ask for it in your permission set; users see new tools the next time they connect. |
+| A call returns `402` with `refusal: "plan_limit"` | A plan limit was hit, not the grant. Wait and retry later; don't ask the user to reconnect. |
 
 ## Supported versions
 

package/dist/server/index.cjs.js

@@ -185,6 +185,18 @@ function tokenScopes(accessToken) {
  * method and path the SDK runs it with.
  */
 
+/**
+ * Why One itself turned a call down, when it did. A provider's own error
+ * (Gmail's 404, Stripe's 400) is not One's refusal and reads `null`.
+ *
+ * - `grant`: the call is outside what the user granted (403). Do not retry.
+ * - `plan_limit`: a plan limit was hit (402, "Please try again later or
+ *   upgrade your plan"). Not about the grant: wait and retry later.
+ * - `rate_limit`: too many calls (429). Wait and retry later.
+ * - `one_error`: any other error from One (for example a 5xx). Retry with
+ *   a backoff.
+ */
+
 /**
  * - `not_connected`: nothing is stored for this user.
  * - `reconnect_required` (key mode): One will not act for this user.
@@ -510,6 +522,23 @@ function createTokenCredential(tokenStore, postToken) {
  * The Next.js and Node adapters turn the first two into route handlers.
  * See `./key` and `./token` for what each mode stores and sends.
  */
+
+/**
+ * Why One itself refused a call, from its reply. One's own errors carry a
+ * correlationId; a provider's error does not, so it reads `null`. Only a
+ * 403 is the grant: One also answers a plan limit (402), a rate limit
+ * (429) and its own failures (5xx) with a correlationId, and none of those
+ * mean the call is outside what the user granted.
+ */
+function oneRefusal(response, data) {
+  if (response.ok) return null;
+  const fromOne = typeof data === "object" && data !== null && "correlationId" in data;
+  if (!fromOne) return null;
+  if (response.status === 403) return "grant";
+  if (response.status === 402) return "plan_limit";
+  if (response.status === 429) return "rate_limit";
+  return "one_error";
+}
 const CATALOG_PAGE_SIZE = 100;
 const CATALOG_MAX_PAGES = 20;
 const SEARCH_DEFAULT_LIMIT = 5;
@@ -860,6 +889,7 @@ function createOneConnect(config) {
           status: response.status,
           ok: false,
           blockedByGrant: true,
+          refusal: "grant",
           data: text
         };
         throw refused;
@@ -873,13 +903,12 @@ function createOneConnect(config) {
     } catch {
       /* the provider answered with something other than JSON */
     }
-    // One's own refusals carry a correlationId; a provider's error does
-    // not. A One-shaped 403 is the grant working, not the provider.
-    const blockedByGrant = !response.ok && typeof data === "object" && data !== null && "correlationId" in data;
+    const refusal = oneRefusal(response, data);
     return {
       status: response.status,
       ok: response.ok,
-      blockedByGrant,
+      blockedByGrant: refusal === "grant",
+      refusal,
       data
     };
   };

package/dist/server/index.esm.js

@@ -183,6 +183,18 @@ function tokenScopes(accessToken) {
  * method and path the SDK runs it with.
  */
 
+/**
+ * Why One itself turned a call down, when it did. A provider's own error
+ * (Gmail's 404, Stripe's 400) is not One's refusal and reads `null`.
+ *
+ * - `grant`: the call is outside what the user granted (403). Do not retry.
+ * - `plan_limit`: a plan limit was hit (402, "Please try again later or
+ *   upgrade your plan"). Not about the grant: wait and retry later.
+ * - `rate_limit`: too many calls (429). Wait and retry later.
+ * - `one_error`: any other error from One (for example a 5xx). Retry with
+ *   a backoff.
+ */
+
 /**
  * - `not_connected`: nothing is stored for this user.
  * - `reconnect_required` (key mode): One will not act for this user.
@@ -508,6 +520,23 @@ function createTokenCredential(tokenStore, postToken) {
  * The Next.js and Node adapters turn the first two into route handlers.
  * See `./key` and `./token` for what each mode stores and sends.
  */
+
+/**
+ * Why One itself refused a call, from its reply. One's own errors carry a
+ * correlationId; a provider's error does not, so it reads `null`. Only a
+ * 403 is the grant: One also answers a plan limit (402), a rate limit
+ * (429) and its own failures (5xx) with a correlationId, and none of those
+ * mean the call is outside what the user granted.
+ */
+function oneRefusal(response, data) {
+  if (response.ok) return null;
+  const fromOne = typeof data === "object" && data !== null && "correlationId" in data;
+  if (!fromOne) return null;
+  if (response.status === 403) return "grant";
+  if (response.status === 402) return "plan_limit";
+  if (response.status === 429) return "rate_limit";
+  return "one_error";
+}
 const CATALOG_PAGE_SIZE = 100;
 const CATALOG_MAX_PAGES = 20;
 const SEARCH_DEFAULT_LIMIT = 5;
@@ -858,6 +887,7 @@ function createOneConnect(config) {
           status: response.status,
           ok: false,
           blockedByGrant: true,
+          refusal: "grant",
           data: text
         };
         throw refused;
@@ -871,13 +901,12 @@ function createOneConnect(config) {
     } catch {
       /* the provider answered with something other than JSON */
     }
-    // One's own refusals carry a correlationId; a provider's error does
-    // not. A One-shaped 403 is the grant working, not the provider.
-    const blockedByGrant = !response.ok && typeof data === "object" && data !== null && "correlationId" in data;
+    const refusal = oneRefusal(response, data);
     return {
       status: response.status,
       ok: response.ok,
-      blockedByGrant,
+      blockedByGrant: refusal === "grant",
+      refusal,
       data
     };
   };

package/dist/server/types.d.ts

@@ -260,13 +260,30 @@ export interface RunActionInput {
      *  notation); "multipart" for file-style uploads. */
     encoding?: ActionBodyEncoding;
 }
+/**
+ * Why One itself turned a call down, when it did. A provider's own error
+ * (Gmail's 404, Stripe's 400) is not One's refusal and reads `null`.
+ *
+ * - `grant`: the call is outside what the user granted (403). Do not retry.
+ * - `plan_limit`: a plan limit was hit (402, "Please try again later or
+ *   upgrade your plan"). Not about the grant: wait and retry later.
+ * - `rate_limit`: too many calls (429). Wait and retry later.
+ * - `one_error`: any other error from One (for example a 5xx). Retry with
+ *   a backoff.
+ */
+export type OneRefusal = "grant" | "plan_limit" | "rate_limit" | "one_error";
 export interface RunActionResult {
     status: number;
     ok: boolean;
-    /** True when One refused the call because it is outside the grant.
-     *  The provider was never called. Do not retry. Key mode sets it; in
-     *  token mode it stays false today, so treat any 403 there as refused. */
+    /** True only when One refused the call because it is outside the grant
+     *  (a 403). The provider was never called. Do not retry. Key mode sets
+     *  it; in token mode it stays false today, so treat any 403 there as
+     *  refused. One's other refusals (plan limit, rate limit, its own
+     *  errors) are not about the grant: see `refusal`. */
     blockedByGrant: boolean;
+    /** 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;
     data: unknown;
 }
 /**

package/package.json

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

@@ -214,7 +214,7 @@ 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, data }
+// { status, ok, blockedByGrant, refusal, data }
 ```
 
 Each connection's `access` is `{ policy: "full" }`, `{ policy: "methods",
@@ -230,8 +230,18 @@ user's id to every call it makes.
 
 ## 8 - Errors
 
-A `403` reply with `blockedByGrant: true` means the call is outside what
-the user granted. Do not retry it.
+`refusal` says why One itself turned a call down:
+
+- `"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.
+- `"one_error"` (other, e.g. `5xx`): retry with a backoff.
+- `null`: not One's refusal; the provider's own answer, or a success.
+
+Only a `403` means "outside the grant". Never treat a `402`, `429` or `5xx`
+as a missing permission.
 
 Errors are `OneConnectError` with a `code`. Handle them where the app calls One:
 

package/src/server/index.ts

@@ -59,6 +59,7 @@ import {
   type ReachableConnection,
   type RefreshIfExpiringOptions,
   type RunActionInput,
+  type OneRefusal,
   type RunActionResult,
   type SearchActionsOptions,
   type StartAuthorizationInput,
@@ -69,6 +70,24 @@ export * from "./types";
 export { encodeUserReference, parseUserReference } from "./key";
 export { refreshTokenExpiresAt, tenancyHeaders, tokenScopes } from "./oauth";
 
+/**
+ * Why One itself refused a call, from its reply. One's own errors carry a
+ * correlationId; a provider's error does not, so it reads `null`. Only a
+ * 403 is the grant: One also answers a plan limit (402), a rate limit
+ * (429) and its own failures (5xx) with a correlationId, and none of those
+ * mean the call is outside what the user granted.
+ */
+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>);
+  if (!fromOne) return null;
+  if (response.status === 403) return "grant";
+  if (response.status === 402) return "plan_limit";
+  if (response.status === 429) return "rate_limit";
+  return "one_error";
+}
+
 const CATALOG_PAGE_SIZE = 100;
 const CATALOG_MAX_PAGES = 20;
 const SEARCH_DEFAULT_LIMIT = 5;
@@ -624,7 +643,7 @@ 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, data: text };
+          return { status: response.status, ok: false, blockedByGrant: true, refusal: "grant", data: text };
         throw refused;
       }
       // One refusing the credential is not an answer to the action.
@@ -636,14 +655,8 @@ export function createOneConnect(
     } catch {
       /* the provider answered with something other than JSON */
     }
-    // One's own refusals carry a correlationId; a provider's error does
-    // not. A One-shaped 403 is the grant working, not the provider.
-    const blockedByGrant =
-      !response.ok &&
-      typeof data === "object" &&
-      data !== null &&
-      "correlationId" in (data as Record<string, unknown>);
-    return { status: response.status, ok: response.ok, blockedByGrant, data };
+    const refusal = oneRefusal(response, data);
+    return { status: response.status, ok: response.ok, blockedByGrant: refusal === "grant", refusal, data };
   };
 
   const shared = {

package/src/server/types.ts

@@ -279,13 +279,31 @@ export interface RunActionInput {
   encoding?: ActionBodyEncoding;
 }
 
+/**
+ * Why One itself turned a call down, when it did. A provider's own error
+ * (Gmail's 404, Stripe's 400) is not One's refusal and reads `null`.
+ *
+ * - `grant`: the call is outside what the user granted (403). Do not retry.
+ * - `plan_limit`: a plan limit was hit (402, "Please try again later or
+ *   upgrade your plan"). Not about the grant: wait and retry later.
+ * - `rate_limit`: too many calls (429). Wait and retry later.
+ * - `one_error`: any other error from One (for example a 5xx). Retry with
+ *   a backoff.
+ */
+export type OneRefusal = "grant" | "plan_limit" | "rate_limit" | "one_error";
+
 export interface RunActionResult {
   status: number;
   ok: boolean;
-  /** True when One refused the call because it is outside the grant.
-   *  The provider was never called. Do not retry. Key mode sets it; in
-   *  token mode it stays false today, so treat any 403 there as refused. */
+  /** True only when One refused the call because it is outside the grant
+   *  (a 403). The provider was never called. Do not retry. Key mode sets
+   *  it; in token mode it stays false today, so treat any 403 there as
+   *  refused. One's other refusals (plan limit, rate limit, its own
+   *  errors) are not about the grant: see `refusal`. */
   blockedByGrant: boolean;
+  /** 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;
   data: unknown;
 }