orangecheck · Xaxis · May 9, 2026
diff --git a/src/pages/sdk/me-client/README.mdx b/src/pages/sdk/me-client/README.mdx
@@ -17,6 +17,8 @@ export const metadata = {
 
 - [BillableEvent](interfaces/BillableEvent.mdx)
 - [ComputedFees](interfaces/ComputedFees.mdx)
+- [FamilyScopesOptions](interfaces/FamilyScopesOptions.mdx)
+- [FamilyScopesResult](interfaces/FamilyScopesResult.mdx)
 - [Federation](interfaces/Federation.mdx)
 - [FireEventOptions](interfaces/FireEventOptions.mdx)
 - [GrantedOptions](interfaces/GrantedOptions.mdx)
@@ -36,6 +38,7 @@ export const metadata = {
 - [VerifyEventResult](interfaces/VerifyEventResult.mdx)
 - [VerifyOptions](interfaces/VerifyOptions.mdx)
 - [VerifyResult](interfaces/VerifyResult.mdx)
+- [WithRateLimitRetryOptions](interfaces/WithRateLimitRetryOptions.mdx)
 
 ## Type Aliases
 
@@ -45,6 +48,7 @@ export const metadata = {
 - [ClassCSubtype](type-aliases/ClassCSubtype.mdx)
 - [EventClass](type-aliases/EventClass.mdx)
 - [EventSubtype](type-aliases/EventSubtype.mdx)
+- [FamilyVerb](type-aliases/FamilyVerb.mdx)
 - [FederationStatus](type-aliases/FederationStatus.mdx)
 - [Scope](type-aliases/Scope.mdx)
 - [SigningMethod](type-aliases/SigningMethod.mdx)
@@ -54,6 +58,7 @@ export const metadata = {
 
 - [config](variables/config.mdx)
 - [event](variables/event.mdx)
+- [family](variables/family.mdx)
 - [federations](variables/federations.mdx)
 - [MIN\_INTEGRATOR\_PRICE\_SATS](variables/MIN_INTEGRATOR_PRICE_SATS.mdx)
 - [oc](variables/oc.mdx)
@@ -74,3 +79,4 @@ export const metadata = {
 - [setBearerToken](functions/setBearerToken.mdx)
 - [setOrigin](functions/setOrigin.mdx)
 - [validateIntegratorConfig](functions/validateIntegratorConfig.mdx)
+- [withRateLimitRetry](functions/withRateLimitRetry.mdx)
diff --git a/src/pages/sdk/me-client/classes/MeClientError.mdx b/src/pages/sdk/me-client/classes/MeClientError.mdx
@@ -11,7 +11,7 @@ export const metadata = {
 
 # Class: MeClientError
 
-Defined in: [me-client/src/transport.ts:73](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/transport.ts#L73)
+Defined in: [me-client/src/transport.ts:103](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/transport.ts#L103)
 
 ## Extends
 
@@ -22,17 +22,26 @@ Defined in: [me-client/src/transport.ts:73](https://github.com/orangecheck/oc-pa
 ### Constructor
 
 ```ts
-new MeClientError(message: string, status: number): MeClientError;
+new MeClientError(
+   message: string, 
+   status: number, 
+   opts?: {
+  errorCode?: string;
+  retryAfterSeconds?: number;
+}): MeClientError;
 ```
 
-Defined in: [me-client/src/transport.ts:75](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/transport.ts#L75)
+Defined in: [me-client/src/transport.ts:114](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/transport.ts#L114)
 
 #### Parameters
 
 | Parameter | Type |
 | ------ | ------ |
 | `message` | `string` |
 | `status` | `number` |
+| `opts?` | \&#123; `errorCode?`: `string`; `retryAfterSeconds?`: `number`; \&#125; |
+| `opts.errorCode?` | `string` |
+| `opts.retryAfterSeconds?` | `number` |
 
 #### Returns
 
@@ -48,110 +57,28 @@ Error.constructor
 
 | Property | Modifier | Type | Description | Inherited from | Defined in |
 | ------ | ------ | ------ | ------ | ------ | ------ |
+| &lt;a id="property-errorcode">&lt;/a> `errorCode` | `readonly` | `string` \| `undefined` | Server-side error code (the `error` field on the JSON body, e.g. `project_rate_limit_exceeded`). Stable across versions; safe to match on. The human-readable `message` may change. | - | [me-client/src/transport.ts:108](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/transport.ts#L108) |
 | &lt;a id="property-message">&lt;/a> `message` | `public` | `string` | - | `Error.message` | node\_modules/typescript/lib/lib.es5.d.ts:1077 |
 | &lt;a id="property-name">&lt;/a> `name` | `public` | `string` | - | `Error.name` | node\_modules/typescript/lib/lib.es5.d.ts:1076 |
+| &lt;a id="property-retryafterseconds">&lt;/a> `retryAfterSeconds` | `readonly` | `number` \| `undefined` | Seconds to wait before retrying. Set when the server responded 429 with a Retry-After header (or a `retry_after_seconds` body field). Undefined for any other status. Use with `withRateLimitRetry()` or your own backoff loop. | - | [me-client/src/transport.ts:113](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/transport.ts#L113) |
 | &lt;a id="property-stack">&lt;/a> `stack?` | `public` | `string` | - | `Error.stack` | node\_modules/typescript/lib/lib.es5.d.ts:1078 |
-| &lt;a id="property-status">&lt;/a> `status` | `readonly` | `number` | - | - | [me-client/src/transport.ts:74](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/transport.ts#L74) |
-| &lt;a id="property-stacktracelimit">&lt;/a> `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `Error.stackTraceLimit` | me-client/node\_modules/@types/node/globals.d.ts:68 |
+| &lt;a id="property-status">&lt;/a> `status` | `readonly` | `number` | - | - | [me-client/src/transport.ts:104](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/transport.ts#L104) |
 
-## Methods
+## Accessors
 
-### captureStackTrace()
+### isRateLimited
 
-```ts
-static captureStackTrace(targetObject: object, constructorOpt?: Function): void;
-```
-
-Defined in: me-client/node\_modules/@types/node/globals.d.ts:52
-
-Creates a `.stack` property on `targetObject`, which when accessed returns
-a string representing the location in the code at which
-`Error.captureStackTrace()` was called.
-
-```js
-const myObject = {};
-Error.captureStackTrace(myObject);
-myObject.stack;  // Similar to `new Error().stack`
-```
-
-The first line of the trace will be prefixed with
-`${myObject.name}: ${myObject.message}`.
-
-The optional `constructorOpt` argument accepts a function. If given, all frames
-above `constructorOpt`, including `constructorOpt`, will be omitted from the
-generated stack trace.
-
-The `constructorOpt` argument is useful for hiding implementation
-details of error generation from the user. For instance:
-
-```js
-function a() {
-  b();
-}
-
-function b() {
-  c();
-}
-
-function c() {
-  // Create an error without stack trace to avoid calculating the stack trace twice.
-  const { stackTraceLimit } = Error;
-  Error.stackTraceLimit = 0;
-  const error = new Error();
-  Error.stackTraceLimit = stackTraceLimit;
-
-  // Capture the stack trace above function b
-  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
-  throw error;
-}
-
-a();
-```
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `targetObject` | `object` |
-| `constructorOpt?` | `Function` |
-
-#### Returns
-
-`void`
-
-#### Inherited from
-
-```ts
-Error.captureStackTrace
-```
-
-***
-
-### prepareStackTrace()
+#### Get Signature
 
 ```ts
-static prepareStackTrace(err: Error, stackTraces: CallSite[]): any;
+get isRateLimited(): boolean;
 ```
 
-Defined in: me-client/node\_modules/@types/node/globals.d.ts:56
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `err` | `Error` |
-| `stackTraces` | `CallSite`[] |
-
-#### Returns
-
-`any`
-
-#### See
+Defined in: [me-client/src/transport.ts:127](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/transport.ts#L127)
 
-https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+True for the 429 surface · convenience boolean so callers don't
+ have to compare status === 429 every time.
 
-#### Inherited from
+##### Returns
 
-```ts
-Error.prepareStackTrace
-```
+`boolean`
diff --git a/src/pages/sdk/me-client/functions/OcSignInButton.mdx b/src/pages/sdk/me-client/functions/OcSignInButton.mdx
@@ -12,7 +12,7 @@ export const metadata = {
 # Function: OcSignInButton()
 
 ```ts
-function OcSignInButton(__namedParameters: OcSignInButtonProps): Element;
+function OcSignInButton(__namedParameters: OcSignInButtonProps): any;
 ```
 
 Defined in: [me-client/src/SignInButton.tsx:29](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/SignInButton.tsx#L29)
@@ -34,4 +34,4 @@ useOcSession() across the rest of the app.
 
 ## Returns
 
-`Element`
+`any`
diff --git a/src/pages/sdk/me-client/functions/withRateLimitRetry.mdx b/src/pages/sdk/me-client/functions/withRateLimitRetry.mdx
@@ -0,0 +1,58 @@
+export const metadata = {
+    title: "Function: withRateLimitRetry()",
+    description: "Auto-generated API reference for Function: withRateLimitRetry(). Source: TypeScript types in oc-packages.",
+};
+
+[**@orangecheck/me-client**](../README.mdx)
+
+***
+
+[@orangecheck/me-client](../README.mdx) / withRateLimitRetry
+
+# Function: withRateLimitRetry()
+
+```ts
+function withRateLimitRetry<T>(fn: () => Promise<T>, opts?: WithRateLimitRetryOptions): Promise<T>;
+```
+
+Defined in: [me-client/src/transport.ts:170](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/transport.ts#L170)
+
+Wrap a transport call with automatic 429 retry, honoring Retry-After.
+
+  import &#123; oc, withRateLimitRetry &#125; from '@orangecheck/me-client';
+
+  const res = await withRateLimitRetry(() =>
+    oc.event.fireBatch(&#123; project_key, events &#125;)
+  );
+
+Retries ONLY on 429 (rate-limit) responses. All other errors throw
+immediately so the caller can handle them. Sleeps for `Retry-After`
+seconds when present (capped at `maxRetryAfterSeconds`); otherwise
+uses exponential backoff from `baseBackoffMs`.
+
+Per OCHK-V3-PLAN §12.6 — backpressure protocol. The server emits
+429 + Retry-After when a project crosses its 1000 events/sec sustained
+cap; this helper honors it without integrators having to write the
+sleep loop.
+
+Idempotency note: integrators using `event.fireBatch` should pass an
+`idempotency_key` per event so a retry doesn't double-record. The
+server collapses retried events to a `duplicate` status with the
+prior payload.
+
+## Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `fn` | () => `Promise`\&lt;`T`\> |
+| `opts` | [`WithRateLimitRetryOptions`](../interfaces/WithRateLimitRetryOptions.mdx) |
+
+## Returns
+
+`Promise`\&lt;`T`\>
diff --git a/src/pages/sdk/me-client/interfaces/FamilyScopesOptions.mdx b/src/pages/sdk/me-client/interfaces/FamilyScopesOptions.mdx
@@ -0,0 +1,21 @@
+export const metadata = {
+    title: "Interface: FamilyScopesOptions",
+    description: "Auto-generated API reference for Interface: FamilyScopesOptions. Source: TypeScript types in oc-packages.",
+};
+
+[**@orangecheck/me-client**](../README.mdx)
+
+***
+
+[@orangecheck/me-client](../README.mdx) / FamilyScopesOptions
+
+# Interface: FamilyScopesOptions
+
+Defined in: [me-client/src/family.ts:42](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/family.ts#L42)
+
+## Properties
+
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| &lt;a id="property-origin">&lt;/a> `origin?` | `string` | Override the OC family origin · only useful for staging. Defaults to https://me.ochk.io · the family-side scope reads always go to me.ochk regardless of which sibling is calling. | [me-client/src/family.ts:46](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/family.ts#L46) |
+| &lt;a id="property-signal">&lt;/a> `signal?` | `AbortSignal` | - | [me-client/src/family.ts:47](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/family.ts#L47) |
diff --git a/src/pages/sdk/me-client/interfaces/FamilyScopesResult.mdx b/src/pages/sdk/me-client/interfaces/FamilyScopesResult.mdx
@@ -0,0 +1,26 @@
+export const metadata = {
+    title: "Interface: FamilyScopesResult",
+    description: "Auto-generated API reference for Interface: FamilyScopesResult. Source: TypeScript types in oc-packages.",
+};
+
+[**@orangecheck/me-client**](../README.mdx)
+
+***
+
+[@orangecheck/me-client](../README.mdx) / FamilyScopesResult
+
+# Interface: FamilyScopesResult
+
+Defined in: [me-client/src/family.ts:50](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/family.ts#L50)
+
+## Properties
+
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| &lt;a id="property-family_product">&lt;/a> `family_product` | \&#123; `name`: `string`; `origin`: `string`; `verb`: [`FamilyVerb`](../type-aliases/FamilyVerb.mdx); \&#125; | Sibling product the grants are scoped to (echoed for logging / debug). | [me-client/src/family.ts:57](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/family.ts#L57) |
+| `family_product.name` | `string` | - | [me-client/src/family.ts:59](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/family.ts#L59) |
+| `family_product.origin` | `string` | - | [me-client/src/family.ts:60](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/family.ts#L60) |
+| `family_product.verb` | [`FamilyVerb`](../type-aliases/FamilyVerb.mdx) | - | [me-client/src/family.ts:58](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/family.ts#L58) |
+| &lt;a id="property-scopes">&lt;/a> `scopes` | `Partial`\&lt;`Record`\&lt;[`Scope`](../type-aliases/Scope.mdx), `string`\>\> | Resolved values for the granted scopes. Only fields whose scope is in `scopes_granted` are present. | [me-client/src/family.ts:67](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/family.ts#L67) |
+| &lt;a id="property-scopes_granted">&lt;/a> `scopes_granted` | [`Scope`](../type-aliases/Scope.mdx)[] | Scopes the user has actively granted to this sibling. Subset of the requested set, filtered for not-revoked + not-expired. | [me-client/src/family.ts:64](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/family.ts#L64) |
+| &lt;a id="property-sub">&lt;/a> `sub` | `string` | Per-sibling stable subject for the currently-signed-in user. Anonymous · derived from master_addr + the family:&lt;verb> project_key. Sibling backends key on this. | [me-client/src/family.ts:54](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/family.ts#L54) |
diff --git a/src/pages/sdk/me-client/interfaces/FireEventOptions.mdx b/src/pages/sdk/me-client/interfaces/FireEventOptions.mdx
@@ -18,6 +18,7 @@ Defined in: [me-client/src/event.ts:38](https://github.com/orangecheck/oc-packag
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
 | &lt;a id="property-action_label">&lt;/a> `action_label?` | `string` | Human-readable action label that appears on the envelope. Optional but encouraged — it's what the user sees in their /me/earn ledger. | [me-client/src/event.ts:46](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/event.ts#L46) |
+| &lt;a id="property-is_agent">&lt;/a> `is_agent?` | `boolean` | Per OCHK-V3-PLAN §7 phase-1 · when true, the event was fired by an oc-agent delegation rather than a human acting under their own session. The integrator's IntegratorEventConfig.agent block applies the override (or refuses · 422 agent_refused). Set this when an autonomous agent (oc-agent kind 30084 action envelope) is the source of the event. Don't set it for events the human user clicked themselves. | [me-client/src/event.ts:66](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/event.ts#L66) |
 | &lt;a id="property-metadata">&lt;/a> `metadata?` | `Record`\&lt;`string`, `unknown`\> | Free-form metadata stored on the envelope. Public — anyone who GETs /api/envelope/&lt;id> sees it. Don't put secrets here. | [me-client/src/event.ts:57](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/event.ts#L57) |
 | &lt;a id="property-payment_amount_sats">&lt;/a> `payment_amount_sats?` | `number` | For percent_of_amount-priced subtypes, the underlying amount the fee is computed against. Required for those subtypes. | [me-client/src/event.ts:49](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/event.ts#L49) |
 | &lt;a id="property-project_key">&lt;/a> `project_key` | `string` | Your project_key (e.g. `pk_live_yourcompany`). Required. | [me-client/src/event.ts:40](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/event.ts#L40) |

diff --git a/src/pages/sdk/me-client/interfaces/GrantedOptions.mdx b/src/pages/sdk/me-client/interfaces/GrantedOptions.mdx
@@ -11,11 +11,11 @@ export const metadata = {
 
 # Interface: GrantedOptions
 
-Defined in: [me-client/src/scope.ts:48](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/scope.ts#L48)
+Defined in: [me-client/src/scope.ts:63](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/scope.ts#L63)
 
 ## Properties
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| &lt;a id="property-project_key">&lt;/a> `project_key` | `string` | Your project_key. Required. | [me-client/src/scope.ts:50](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/scope.ts#L50) |
-| &lt;a id="property-signal">&lt;/a> `signal?` | `AbortSignal` | - | [me-client/src/scope.ts:51](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/scope.ts#L51) |
+| &lt;a id="property-project_key">&lt;/a> `project_key` | `string` | Your project_key. Required. | [me-client/src/scope.ts:65](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/scope.ts#L65) |
+| &lt;a id="property-signal">&lt;/a> `signal?` | `AbortSignal` | - | [me-client/src/scope.ts:66](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/scope.ts#L66) |
diff --git a/src/pages/sdk/me-client/interfaces/GrantedResult.mdx b/src/pages/sdk/me-client/interfaces/GrantedResult.mdx
@@ -11,12 +11,12 @@ export const metadata = {
 
 # Interface: GrantedResult
 
-Defined in: [me-client/src/scope.ts:54](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/scope.ts#L54)
+Defined in: [me-client/src/scope.ts:69](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/scope.ts#L69)
 
 ## Properties
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| &lt;a id="property-scopes">&lt;/a> `scopes` | `Partial`\&lt;`Record`\&lt;[`Scope`](../type-aliases/Scope.mdx), `string`\>\> | Resolved values for the granted scopes. Only fields whose scope is in `scopes_granted` are present. | [me-client/src/scope.ts:64](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/scope.ts#L64) |
-| &lt;a id="property-scopes_granted">&lt;/a> `scopes_granted` | [`Scope`](../type-aliases/Scope.mdx)[] | Scopes the user has actively granted to this project. Subset of the requested scopes, filtered for not-revoked + not-expired. | [me-client/src/scope.ts:61](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/scope.ts#L61) |
-| &lt;a id="property-sub">&lt;/a> `sub` | `string` | Per-integrator stable subject for the currently-signed-in user. This is what your backend should key user records on (NOT the master addr · which OC doesn't reveal). | [me-client/src/scope.ts:58](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/scope.ts#L58) |
+| &lt;a id="property-scopes">&lt;/a> `scopes` | `Partial`\&lt;`Record`\&lt;[`Scope`](../type-aliases/Scope.mdx), `string`\>\> | Resolved values for the granted scopes. Only fields whose scope is in `scopes_granted` are present. | [me-client/src/scope.ts:79](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/scope.ts#L79) |
+| &lt;a id="property-scopes_granted">&lt;/a> `scopes_granted` | [`Scope`](../type-aliases/Scope.mdx)[] | Scopes the user has actively granted to this project. Subset of the requested scopes, filtered for not-revoked + not-expired. | [me-client/src/scope.ts:76](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/scope.ts#L76) |
+| &lt;a id="property-sub">&lt;/a> `sub` | `string` | Per-integrator stable subject for the currently-signed-in user. This is what your backend should key user records on (NOT the master addr · which OC doesn't reveal). | [me-client/src/scope.ts:73](https://github.com/orangecheck/oc-packages/blob/main/me-client/src/scope.ts#L73) |