@atlasauth/backend 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @atlasauth/backend changelog
 
+## 0.12.0
+- **Referral attribution v2.** `referrals.retryFailed({ kind?, error_code? }, idempotencyKey?)` (`POST /v1/instance/referrals/calls/retry_failed`, `ReferralRetryFailedResult` with `requeued`), `referrals.simulate({ code? })` (`POST /v1/instance/referrals/simulate`, `ReferralSimulateResult`: `call_id`, `customer_ref`, `result`, `response`), `referrals.backfill({ since, codes?, code_metadata_path? }, idempotencyKey?)` and `referrals.getBackfill(id)` (`POST /v1/instance/referrals/backfill`, `GET /v1/instance/referrals/backfill/:id`, `ReferralBackfillJob`: `users_scanned`, `users_skipped`, `calls_queued`, `truncated`, `next_since`, `calls`), and `referrals.getForUser(userId)` (`GET /v1/users/:id/referral`, `UserReferralResult`).
+- **Settings.** `ReferralSettings` and `UpdateReferralSettingsBody` gain `tracking_token`, `code_lookup_url`, `signup_code_field`, `forward_lifecycle`, `mirror_to_public_metadata` and `include_referral_claims`. `provider` can be `referally`. `ReferralProviderCapabilities` gains `alias`, `user` and `ping`; `needs` can list `tracking_token`. `ReferralConnectionStatus` gains `last_ping` (`ReferralPing`) and `alert` (`signature_rejected` or `connection_paused`). `ReferralConnectionTest` gains `ping`, `method` and `warnings`.
+- **Call log.** `ReferralCallKind` adds `alias`, `user` and `ping`. `ReferralCall` gains `latency_ms`, `error_code`, `response`, `highlights`, `request_id` and `batch_id`. `ListReferralCallsParams` gains `error_code` and `starting_after`; `limit` goes up to 1000.
+- **Users.** `users.setExternalId(id, externalId | null)` (`PATCH /v1/users/:id`); with referrals on, Atlas forwards the change to the platform as an alias. `UpdateUserBody` gains `external_id`. `UserReferral` gains `partner_external_ref`, `referral_status` and `notes`; `status` is now the attribution status (`pending`, `attributed`, `none`, `failed`, `held`, `flagged`), and the platform's own status moved to `referral_status`. New `UserReferralResolvedEvent` types the `data` of `user.referral_resolved`.
+- **before_user_create hook.** New `userHooks` namespace: `getBeforeUserCreate()`, `updateBeforeUserCreate(body)` and `testBeforeUserCreate()` (`/v1/instance/hooks/before_user_create`; `BeforeUserCreateHook`, `UpdateBeforeUserCreateHookBody`, `BeforeUserCreateHookTest`).
+- **Referral protocol receiver.** `verifyReferralRequest` accepts the new operations `alias` (`/aliases`, `ReferralAliasPayload`), `user` (`/users`, `ReferralUserPayload`) and `ping` (`/ping`, `ReferralPingPayload`; answer `ReferralPingResponse`), and returns `protocolVersion` (the `Atlas-Referrals-Version` header). `ReferralSignupResponse` gains optional `notes`. New constants `REFERRAL_PROTOCOL_VERSION` (`2026-10-21`) and `REFERRAL_PROTOCOL_VERSION_HEADER`.
+- **Test calls.** `createTestIssuer()` gains `referralCall(options)` (an Atlas referral protocol call, signed as an instance signs it) and `referallyCall(options)` (a Referally connection call: `x-referally-signature` over the raw body, or the raw query string for `export`, with `referally-version`). Also standalone: `signAtlasReferralCall`, `signReferallyCall`, `referallySignature`, `referralEmailHash`, `REFERALLY_API_VERSION`; types `SignedReferralCall`, `AtlasReferralCallOptions`, `ReferallyCallOptions`, `ReferallyCallOp`.
+- **Compatible.** New methods, types, optional fields and constants. One meaning changed on the server: `user.referral.status` is the attribution status; read the platform's status from `referral_status`.
+
+## 0.11.0
+- **Referral attribution settings.** New `referrals` namespace: `get()` and `update(body, idempotencyKey?)` (`GET`/`PATCH /v1/instance/referrals`; `ReferralSettings`, `UpdateReferralSettingsBody` with nested `security`: `ReferralSecuritySettings` `challenge_referred_signups`, `on_high_risk`, `hold_until_email_verified`, `max_referred_signups_per_ip_hour`), `test()` (`ReferralConnectionTest`), `listCalls({ limit?, status?, kind?, user_id? })` (`ReferralCall`, `ListReferralCallsParams`) and `retryCall(id, idempotencyKey?)`. Also `ReferralProviderInfo`, `ReferralProviderCapabilities`, `ReferralConnectionStatus`, `ReferralRisk`, `ReferralCallKind`, `ReferralCallStatus`.
+- **Users.** `User` gains optional `referral` (`UserReferral`: `partner_id`, `referrer_external_id`, `referrer_user_id`, `matched_via`, `status`, `risk_level`, `flagged`), `referral_code` and `referral_link`. `CreateUserBody` accepts `referral` (`CreateUserReferralInput`: `code`, `click_id`, `anon_id`) and `referral_code`; `UpdateUserBody` accepts `referral_code` (`null` clears). New `users.flagReferral(id, { reason? }, idempotencyKey?)` (`POST /v1/users/:id/referral/flag`, `UserReferralFlag`).
+- **Webhooks.** `UserReferralAttributedEvent` types the `data` of the new `user.referral_attributed` event (the referral platform answered after `user.created`).
+- **Error codes.** `AtlasErrorCodes` adds `REFERRALS_NOT_CONFIGURED` (422) and `REFERRAL_CODE_TAKEN` (409). Preflight can report `referrals_enabled_unverified` and `referrals_without_bot_protection`.
+- **Referral protocol receiver.** `verifyReferralRequest({ body, headers, secret, path?, expectedOp?, now?, toleranceMs? })` verifies a call from Atlas to a referral platform (the webhook signature scheme; every call is a `POST` whose signed body carries `op` and `customerRef`) and returns `call` by operation (`ReferralProtocolCall`: `signup`, `erase`, `export` with `test`, `partner`, `signal`), plus `deliveryId`, `timestamp` and `idempotencyKey`. It refuses (`ReferralVerifyFailure`) a body that is not an object (`malformed_body`), a missing or unknown `op` (`missing_op`, `unknown_op`), a path that is not a protocol endpoint (`unknown_endpoint`) and an `op` that does not match the path or `expectedOp` (`op_mismatch`). Payload types: `ReferralSignupPayload`, `ReferralSignupResponse`, `ReferralErasePayload`, `ReferralExportPayload`, `ReferralPartnerPayload`, `ReferralSignalPayload`, `ReferralSignalType`, `ReferralContext`, `ReferralRiskVerdict`, `ReferralOp`; `referralOpForPath`; constants `REFERRAL_OP_ENDPOINTS`, `REFERRAL_CONNECTION_TEST_REF`, `REFERRAL_PROTOCOL_USER_AGENT`.
+- **Compatible.** New methods, types, optional fields and constants only.
+
 ## 0.10.0
 - **Trusted reverse proxy secret.** `instanceSecurity.getProxySecret()` (`ProxySecret`: `set`, `created_at`, `previous_expires_at`, `secret_header`, `client_ip_header`), `instanceSecurity.createProxySecret({ overlap_seconds? })` (`ProxySecretCreated`: adds `secret`, shown once, and `rotated`; `CreateProxySecretBody`) and `instanceSecurity.deleteProxySecret()`. A proxy that serves the Frontend API from your own origin sends the secret in `X-Atlas-Proxy-Secret` and the browser's IP in `X-Atlas-Client-IP`; Atlas then uses that IP for rate limits, lockout, risk signals, geo, audit logs and session metadata.
 - **Managed email feedback on Resend.** `ManagedEmail.feedback_webhook` is now also returned for Resend (on create and verify): Atlas registers a bounce / complaint webhook on your own Resend account, so `usage.bounces` / `usage.complaints` count for Resend domains too.

package/README.md

@@ -401,3 +401,58 @@ To check the route end to end, `oauthClients.testBackchannelLogout(id)` sends a
 `verifyWebhook` checks the signature on events Atlas sends to your webhook endpoints. You manage endpoints with `atlas.webhooks.endpoints`: create, update, reveal or rotate a secret, send a test event, and redeliver a past delivery.
 
 The `atlas-signature` header can carry more than one signature, separated by spaces (`v1,<sig> v1,<sig>`). While an endpoint secret rotates, Atlas may sign each delivery with the old and the new secret. `verifyWebhook` accepts the delivery when any one signature matches your secret.
+
+## Referral attribution
+
+With referral attribution on, Atlas reports every interactive sign-up to your referral platform before `user.created` is sent. The answer lands on the user: `referral` (who referred them, or null), `referral_code` and `referral_link` (the user's own code and link, when they are a referrer).
+
+```ts
+await atlas.referrals.update({
+  enabled: true,
+  provider: 'webhook', // the Atlas referral protocol; or a built-in vendor adapter
+  endpoint_url: 'https://referrals.example.com/atlas',
+  signing_secret: process.env.REFERRAL_SIGNING_SECRET,
+  auto_enroll_users: true,
+  link_template: 'https://app.example.com/join?ref={code}',
+  security: { on_high_risk: 'hold' },
+});
+const test = await atlas.referrals.test(); // { ok, http_status, latency_ms, error? }
+const failed = await atlas.referrals.listCalls({ status: 'failed', limit: 20 });
+await atlas.referrals.retryCall(failed.data[0]!.id);
+
+const user = await atlas.users.get('user_123');
+user.referral?.referrer_user_id;
+await atlas.users.update('user_123', { referral_code: 'ada-1' }); // 409 REFERRAL_CODE_TAKEN if held
+await atlas.users.flagReferral('user_123', { reason: 'self-referral' });
+```
+
+Enabling without what the provider needs is `422 REFERRALS_NOT_CONFIGURED`. When the platform answers late, Atlas sends the `user.referral_attributed` webhook (`UserReferralAttributedEvent`). Preflight may report `referrals_enabled_unverified` and `referrals_without_bot_protection`.
+
+### Receive the referral protocol (referral platforms)
+
+A referral platform that implements the Atlas referral protocol verifies Atlas's calls with `verifyReferralRequest`. Every call is a `POST` signed like a webhook, and its JSON body says which operation it is (`op`): `signup`, `erase`, `export`, `partner` or `signal`. Pass the path the call arrived on: a signed body whose `op` does not match the endpoint is refused (`op_mismatch`).
+
+```ts
+import { verifyReferralRequest } from '@atlasauth/backend';
+
+app.post('/atlas/:endpoint', express.raw({ type: '*/*' }), async (req, res) => {
+  const { verified, call } = verifyReferralRequest({
+    body: req.body,
+    headers: req.headers,
+    secret: process.env.REFERRAL_SIGNING_SECRET!,
+    path: req.path, // or expectedOp: 'signup' on a handler for one endpoint
+  });
+  if (!verified || !call) return res.sendStatus(401);
+  switch (call.op) {
+    case 'signup': // ReferralSignupPayload → answer ReferralSignupResponse
+      return res.json({ referral: await match(call.payload), partner: await enroll(call.payload) });
+    case 'export': // the connection test sends test: true
+      return call.test ? res.sendStatus(404) : res.json(await exportFor(call.payload.customerRef));
+    default: // erase, partner, signal
+      await handle(call);
+      return res.sendStatus(204);
+  }
+});
+```
+
+A retry of one call keeps its `atlas-id` (`deliveryId`). Sign-ups are idempotent on `customerRef`: answer a retry the same way.

package/dist/client/error.d.ts

@@ -57,6 +57,10 @@ export declare const AtlasErrorCodes: {
     readonly DEVELOPMENT_EMAIL_LIMIT_REACHED: "DEVELOPMENT_EMAIL_LIMIT_REACHED";
     /** 422 — the development sender sends only Atlas's own sign-in emails, never custom templates. */
     readonly DEVELOPMENT_EMAIL_TEMPLATE_NOT_ALLOWED: "DEVELOPMENT_EMAIL_TEMPLATE_NOT_ALLOWED";
+    /** 422 — referrals cannot be enabled until the provider's needs are set (`meta` names what is missing). */
+    readonly REFERRALS_NOT_CONFIGURED: "REFERRALS_NOT_CONFIGURED";
+    /** 409 — another user on the instance already holds that referral code. */
+    readonly REFERRAL_CODE_TAKEN: "REFERRAL_CODE_TAKEN";
     /** The billing plan still has subscribers and cannot be removed. */
     readonly PLAN_IN_USE: "PLAN_IN_USE";
     /** The key is valid but for another API surface (e.g. a platform key on the Backend API). */

package/dist/client/error.js

@@ -53,6 +53,10 @@ exports.AtlasErrorCodes = {
     DEVELOPMENT_EMAIL_LIMIT_REACHED: 'DEVELOPMENT_EMAIL_LIMIT_REACHED',
     /** 422 — the development sender sends only Atlas's own sign-in emails, never custom templates. */
     DEVELOPMENT_EMAIL_TEMPLATE_NOT_ALLOWED: 'DEVELOPMENT_EMAIL_TEMPLATE_NOT_ALLOWED',
+    /** 422 — referrals cannot be enabled until the provider's needs are set (`meta` names what is missing). */
+    REFERRALS_NOT_CONFIGURED: 'REFERRALS_NOT_CONFIGURED',
+    /** 409 — another user on the instance already holds that referral code. */
+    REFERRAL_CODE_TAKEN: 'REFERRAL_CODE_TAKEN',
     /** The billing plan still has subscribers and cannot be removed. */
     PLAN_IN_USE: 'PLAN_IN_USE',
     /** The key is valid but for another API surface (e.g. a platform key on the Backend API). */

package/dist/client/error.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/client/error.ts"],"names":[],"mappings":";;;AAoBA,MAAa,aAAc,SAAQ,KAAK;IACpB,IAAI,GAAG,eAAe,CAAC;IACzC,0CAA0C;IACjC,MAAM,CAAS;IACxB,8CAA8C;IACrC,MAAM,CAAmB;IAElC,YAAY,MAAc,EAAE,MAAwB,EAAE,OAAgB;QACpE,KAAK,CAAC,OAAO,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,wCAAwC,MAAM,EAAE,CAAC,CAAC;QACzF,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,uEAAuE;QACvE,sEAAsE;QACtE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACvD,CAAC;IAED,uEAAuE;IACvE,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC;IAC9B,CAAC;IAED,yEAAyE;IACzE,OAAO,CAAC,IAAY;QAClB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAClD,CAAC;CACF;AAzBD,sCAyBC;AAED;;;;GAIG;AACU,QAAA,eAAe,GAAG;IAC7B,+EAA+E;IAC/E,6BAA6B,EAAE,+BAA+B;IAC9D,mEAAmE;IACnE,uBAAuB,EAAE,yBAAyB;IAClD,oGAAoG;IACpG,qBAAqB,EAAE,uBAAuB;IAC9C,oGAAoG;IACpG,qBAAqB,EAAE,uBAAuB;IAC9C,wGAAwG;IACxG,cAAc,EAAE,gBAAgB;IAChC,0FAA0F;IAC1F,aAAa,EAAE,eAAe;IAC9B,uIAAuI;IACvI,eAAe,EAAE,iBAAiB;IAClC,oFAAoF;IACpF,6BAA6B,EAAE,+BAA+B;IAC9D,8EAA8E;IAC9E,6BAA6B,EAAE,+BAA+B;IAC9D,6HAA6H;IAC7H,+BAA+B,EAAE,iCAAiC;IAClE,kGAAkG;IAClG,sCAAsC,EAAE,wCAAwC;IAChF,oEAAoE;IACpE,WAAW,EAAE,aAAa;IAC1B,6FAA6F;IAC7F,iBAAiB,EAAE,mBAAmB;IACtC,gDAAgD;IAChD,WAAW,EAAE,aAAa;IAC1B,SAAS,EAAE,WAAW;IACtB,iBAAiB,EAAE,mBAAmB;IACtC,YAAY,EAAE,cAAc;IAC5B,4FAA4F;IAC5F,oBAAoB,EAAE,sBAAsB;IAC5C,yFAAyF;IACzF,cAAc,EAAE,gBAAgB;IAChC,eAAe,EAAE,iBAAiB;IAClC,oBAAoB,EAAE,sBAAsB;IAC5C,eAAe,EAAE,iBAAiB;IAClC,aAAa,EAAE,eAAe;IAC9B,SAAS,EAAE,WAAW;IACtB,QAAQ,EAAE,UAAU;CACZ,CAAC"}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/client/error.ts"],"names":[],"mappings":";;;AAoBA,MAAa,aAAc,SAAQ,KAAK;IACpB,IAAI,GAAG,eAAe,CAAC;IACzC,0CAA0C;IACjC,MAAM,CAAS;IACxB,8CAA8C;IACrC,MAAM,CAAmB;IAElC,YAAY,MAAc,EAAE,MAAwB,EAAE,OAAgB;QACpE,KAAK,CAAC,OAAO,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,wCAAwC,MAAM,EAAE,CAAC,CAAC;QACzF,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,uEAAuE;QACvE,sEAAsE;QACtE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACvD,CAAC;IAED,uEAAuE;IACvE,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC;IAC9B,CAAC;IAED,yEAAyE;IACzE,OAAO,CAAC,IAAY;QAClB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAClD,CAAC;CACF;AAzBD,sCAyBC;AAED;;;;GAIG;AACU,QAAA,eAAe,GAAG;IAC7B,+EAA+E;IAC/E,6BAA6B,EAAE,+BAA+B;IAC9D,mEAAmE;IACnE,uBAAuB,EAAE,yBAAyB;IAClD,oGAAoG;IACpG,qBAAqB,EAAE,uBAAuB;IAC9C,oGAAoG;IACpG,qBAAqB,EAAE,uBAAuB;IAC9C,wGAAwG;IACxG,cAAc,EAAE,gBAAgB;IAChC,0FAA0F;IAC1F,aAAa,EAAE,eAAe;IAC9B,uIAAuI;IACvI,eAAe,EAAE,iBAAiB;IAClC,oFAAoF;IACpF,6BAA6B,EAAE,+BAA+B;IAC9D,8EAA8E;IAC9E,6BAA6B,EAAE,+BAA+B;IAC9D,6HAA6H;IAC7H,+BAA+B,EAAE,iCAAiC;IAClE,kGAAkG;IAClG,sCAAsC,EAAE,wCAAwC;IAChF,2GAA2G;IAC3G,wBAAwB,EAAE,0BAA0B;IACpD,2EAA2E;IAC3E,mBAAmB,EAAE,qBAAqB;IAC1C,oEAAoE;IACpE,WAAW,EAAE,aAAa;IAC1B,6FAA6F;IAC7F,iBAAiB,EAAE,mBAAmB;IACtC,gDAAgD;IAChD,WAAW,EAAE,aAAa;IAC1B,SAAS,EAAE,WAAW;IACtB,iBAAiB,EAAE,mBAAmB;IACtC,YAAY,EAAE,cAAc;IAC5B,4FAA4F;IAC5F,oBAAoB,EAAE,sBAAsB;IAC5C,yFAAyF;IACzF,cAAc,EAAE,gBAAgB;IAChC,eAAe,EAAE,iBAAiB;IAClC,oBAAoB,EAAE,sBAAsB;IAC5C,eAAe,EAAE,iBAAiB;IAClC,aAAa,EAAE,eAAe;IAC9B,SAAS,EAAE,WAAW;IACtB,QAAQ,EAAE,UAAU;CACZ,CAAC"}

package/dist/client/index.d.ts

@@ -16,6 +16,7 @@ declare function buildNamespaces(request: RequestFn): {
         get(id: string): Promise<import("./users").User>;
         create(body: import("./users").CreateUserBody, idempotencyKey?: string): Promise<import("./users").User>;
         update(id: string, body: import("./users").UpdateUserBody): Promise<import("./users").User>;
+        setExternalId(id: string, externalId: string | null): Promise<import("./users").User>;
         replaceMetadata(id: string, body: import("./users").ReplaceUserMetadataBody): Promise<import("./users").User>;
         ban(id: string): Promise<import("./users").User>;
         unban(id: string): Promise<import("./users").User>;
@@ -23,6 +24,9 @@ declare function buildNamespaces(request: RequestFn): {
             duration_in_seconds?: number;
         }): Promise<import("./users").User>;
         unlock(id: string): Promise<import("./users").User>;
+        flagReferral(id: string, body?: {
+            reason?: string;
+        }, idempotencyKey?: string): Promise<import("./users").UserReferralFlag>;
         delete(id: string): Promise<import("./types").DeletedObject>;
         resetMfa(id: string): Promise<{
             object: "user";
@@ -970,6 +974,28 @@ declare function buildNamespaces(request: RequestFn): {
             deleted: true;
         }>;
     };
+    referrals: {
+        get(): Promise<import("./referrals").ReferralSettings>;
+        update(body: import("./referrals").UpdateReferralSettingsBody, idempotencyKey?: string): Promise<import("./referrals").ReferralSettings>;
+        test(): Promise<import("./referrals").ReferralConnectionTest>;
+        listCalls(params?: import("./referrals").ListReferralCallsParams): Promise<import("./types").ListPage<import("./referrals").ReferralCall>>;
+        retryCall(id: string, idempotencyKey?: string): Promise<import("./referrals").ReferralCall>;
+        retryFailed(filter?: {
+            kind?: import("./referrals").ReferralCallKind;
+            error_code?: string;
+        }, idempotencyKey?: string): Promise<import("./referrals").ReferralRetryFailedResult>;
+        simulate(body?: {
+            code?: string;
+        }): Promise<import("./referrals").ReferralSimulateResult>;
+        backfill(body: import("./referrals").ReferralBackfillBody, idempotencyKey?: string): Promise<import("./referrals").ReferralBackfillJob>;
+        getBackfill(id: string): Promise<import("./referrals").ReferralBackfillJob>;
+        getForUser(userId: string): Promise<import("./users").UserReferralResult>;
+    };
+    userHooks: {
+        getBeforeUserCreate(): Promise<import("./user-hooks").BeforeUserCreateHook>;
+        updateBeforeUserCreate(body: import("./user-hooks").UpdateBeforeUserCreateHookBody): Promise<import("./user-hooks").BeforeUserCreateHook>;
+        testBeforeUserCreate(): Promise<import("./user-hooks").BeforeUserCreateHookTest>;
+    };
     tokens: {
         verify(body: import("./tokens").VerifyTokenBody): Promise<import("./tokens").TokenVerification>;
     };
@@ -1320,6 +1346,8 @@ export * from './radius-clients';
 export * from './lti-platforms';
 export * from './instance';
 export * from './instance-security';
+export * from './referrals';
+export * from './user-hooks';
 export * from './tokens';
 export * from './captcha';
 export * from './design';

package/dist/client/index.js

@@ -60,6 +60,8 @@ const radius_clients_1 = require("./radius-clients");
 const lti_platforms_1 = require("./lti-platforms");
 const instance_1 = require("./instance");
 const instance_security_1 = require("./instance-security");
+const referrals_1 = require("./referrals");
+const user_hooks_1 = require("./user-hooks");
 const tokens_1 = require("./tokens");
 const captcha_1 = require("./captcha");
 const design_1 = require("./design");
@@ -147,6 +149,10 @@ function buildNamespaces(request) {
         ltiPlatforms: (0, lti_platforms_1.ltiPlatformsResource)(request),
         instance: (0, instance_1.instanceResource)(request),
         instanceSecurity: (0, instance_security_1.instanceSecurityResource)(request),
+        // Referral attribution: the instance's referral platform connection and call log.
+        referrals: (0, referrals_1.referralsResource)(request),
+        // The before_user_create hook (sets external_id before the user exists).
+        userHooks: (0, user_hooks_1.userHooksResource)(request),
         tokens: (0, tokens_1.tokensResource)(request),
         // §5 "captcha anywhere" — verify any CAPTCHA token against the instance's
         // centrally-configured provider, server-side, with the secret held by Atlas.
@@ -236,6 +242,8 @@ __exportStar(require("./radius-clients"), exports);
 __exportStar(require("./lti-platforms"), exports);
 __exportStar(require("./instance"), exports);
 __exportStar(require("./instance-security"), exports);
+__exportStar(require("./referrals"), exports);
+__exportStar(require("./user-hooks"), exports);
 __exportStar(require("./tokens"), exports);
 __exportStar(require("./captcha"), exports);
 __exportStar(require("./design"), exports);

package/dist/client/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AA4EA,8CAQC;AApFD,uCAA6F;AAC7F,mCAAwC;AACxC,yCAA8C;AAC9C,mDAAwD;AACxD,mCAA6D;AAC7D,mDAAuD;AACvD,yDAA6D;AAC7D,uDAA2D;AAC3D,+CAAmD;AACnD,uCAA4C;AAC5C,yCAA8C;AAC9C,iDAAsE;AACtE,2DAA+D;AAC/D,iDAAqD;AACrD,+CAAoD;AACpD,yCAA8C;AAC9C,qDAAwD;AACxD,6CAAiD;AACjD,mDAAuD;AACvD,yCAA6C;AAC7C,yCAA8C;AAC9C,uDAA2D;AAC3D,qDAAyD;AACzD,2DAA+D;AAC/D,+BAAoC;AACpC,6CAAuD;AACvD,qDAAwD;AACxD,+CAAmD;AACnD,iDAAqD;AACrD,+CAAmD;AACnD,+CAAmD;AACnD,yCAA8C;AAC9C,uDAA2D;AAC3D,mDAAuD;AACvD,mDAAwD;AACxD,uCAA4C;AAC5C,mDAAkD;AAClD,2CAAgD;AAChD,mDAAuD;AACvD,mEAAsE;AACtE,qDAAyD;AACzD,mDAAuD;AACvD,yCAA8C;AAC9C,2DAA+D;AAC/D,qCAA0C;AAC1C,uCAA4C;AAC5C,qCAA0C;AAC1C,mEAAuE;AACvE,iEAAoE;AACpE,iFAAoF;AACpF,uDAA2D;AAC3D,uCAA4C;AAC5C,6CAAkD;AAClD,mDAAwD;AACxD,iDAAqD;AACrD,yCAAoF;AACpF,uEAA0E;AAC1E,+BAAoC;AACpC,+BAA0D;AAC1D,+CAA6D;AAC7D,mDAAuD;AACvD,mEAAsE;AACtE,uCAA4C;AAC5C,2CAA+C;AAC/C,+CAAoD;AAGpD;;;;;;;;GAQG;AACH,SAAgB,iBAAiB,CAAC,MAAyB;IACzD,MAAM,OAAO,GAAG,IAAA,uBAAa,EAAC,MAAM,CAAC,CAAC;IACtC,OAAO;QACL,GAAG,eAAe,CAAC,OAAO,CAAC;QAC3B,WAAW,CAAC,SAA+B;YACzC,OAAO,iBAAiB,CAAC,EAAE,GAAG,MAAM,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;QACxD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,OAAkB;IACzC,OAAO;QACL,KAAK,EAAE,IAAA,qBAAa,EAAC,OAAO,CAAC;QAC7B,QAAQ,EAAE,IAAA,2BAAgB,EAAC,OAAO,CAAC;QACnC,aAAa,EAAE,IAAA,qCAAqB,EAAC,OAAO,CAAC;QAC7C,KAAK,EAAE,IAAA,qBAAa,EAAC,OAAO,CAAC;QAC7B,WAAW,EAAE,IAAA,2BAAmB,EAAC,OAAO,CAAC;QACzC,YAAY,EAAE,IAAA,oCAAoB,EAAC,OAAO,CAAC;QAC3C,eAAe,EAAE,IAAA,0CAAuB,EAAC,OAAO,CAAC;QACjD,cAAc,EAAE,IAAA,wCAAsB,EAAC,OAAO,CAAC;QAC/C,UAAU,EAAE,IAAA,gCAAkB,EAAC,OAAO,CAAC;QACvC,OAAO,EAAE,IAAA,yBAAe,EAAC,OAAO,CAAC;QACjC,QAAQ,EAAE,IAAA,2BAAgB,EAAC,OAAO,CAAC;QACnC,SAAS,EAAE,IAAA,gCAAiB,EAAC,OAAO,CAAC;QACrC,SAAS,EAAE,IAAA,gCAAiB,EAAC,OAAO,CAAC;QACrC,gBAAgB,EAAE,IAAA,4CAAwB,EAAC,OAAO,CAAC;QACnD,WAAW,EAAE,IAAA,kCAAmB,EAAC,OAAO,CAAC;QACzC,WAAW,EAAE,IAAA,iCAAmB,EAAC,OAAO,CAAC;QACzC,QAAQ,EAAE,IAAA,2BAAgB,EAAC,OAAO,CAAC;QACnC,YAAY,EAAE,IAAA,qCAAoB,EAAC,OAAO,CAAC;QAC3C,SAAS,EAAE,IAAA,8BAAiB,EAAC,OAAO,CAAC;QACrC,YAAY,EAAE,IAAA,oCAAoB,EAAC,OAAO,CAAC;QAC3C,OAAO,EAAE,IAAA,0BAAe,EAAC,OAAO,CAAC;QACjC,8EAA8E;QAC9E,QAAQ,EAAE,IAAA,2BAAgB,EAAC,OAAO,CAAC;QACnC,cAAc,EAAE,IAAA,wCAAsB,EAAC,OAAO,CAAC;QAC/C,aAAa,EAAE,IAAA,sCAAqB,EAAC,OAAO,CAAC;QAC7C,gBAAgB,EAAE,IAAA,4CAAwB,EAAC,OAAO,CAAC;QACnD,GAAG,EAAE,IAAA,iBAAW,EAAC,OAAO,CAAC;QACzB,eAAe,EAAE,IAAA,oCAAuB,EAAC,OAAO,CAAC;QACjD,YAAY,EAAE,IAAA,qCAAoB,EAAC,OAAO,CAAC;QAC3C,UAAU,EAAE,IAAA,gCAAkB,EAAC,OAAO,CAAC;QACvC,WAAW,EAAE,IAAA,kCAAmB,EAAC,OAAO,CAAC;QACzC,UAAU,EAAE,IAAA,gCAAkB,EAAC,OAAO,CAAC;QACvC,UAAU,EAAE,IAAA,gCAAkB,EAAC,OAAO,CAAC;QACvC,QAAQ,EAAE,IAAA,2BAAgB,EAAC,OAAO,CAAC;QACnC,cAAc,EAAE,IAAA,wCAAsB,EAAC,OAAO,CAAC;QAC/C,YAAY,EAAE,IAAA,oCAAoB,EAAC,OAAO,CAAC;QAC3C,aAAa,EAAE,IAAA,qCAAqB,EAAC,OAAO,CAAC;QAC7C,OAAO,EAAE,IAAA,yBAAe,EAAC,OAAO,CAAC;QACjC,OAAO,EAAE,IAAA,+BAAe,EAAC,OAAO,CAAC;QACjC,SAAS,EAAE,IAAA,6BAAiB,EAAC,OAAO,CAAC;QACrC,YAAY,EAAE,IAAA,oCAAoB,EAAC,OAAO,CAAC;QAC3C,mBAAmB,EAAE,IAAA,mDAA2B,EAAC,OAAO,CAAC;QACzD,aAAa,EAAE,IAAA,sCAAqB,EAAC,OAAO,CAAC;QAC7C,YAAY,EAAE,IAAA,oCAAoB,EAAC,OAAO,CAAC;QAC3C,QAAQ,EAAE,IAAA,2BAAgB,EAAC,OAAO,CAAC;QACnC,gBAAgB,EAAE,IAAA,4CAAwB,EAAC,OAAO,CAAC;QACnD,MAAM,EAAE,IAAA,uBAAc,EAAC,OAAO,CAAC;QAC/B,0EAA0E;QAC1E,6EAA6E;QAC7E,OAAO,EAAE,IAAA,yBAAe,EAAC,OAAO,CAAC;QACjC,+EAA+E;QAC/E,MAAM,EAAE,IAAA,uBAAc,EAAC,OAAO,CAAC;QAC/B,oBAAoB,EAAE,IAAA,oDAA4B,EAAC,OAAO,CAAC;QAC3D,kBAAkB,EAAE,IAAA,iDAA0B,EAAC,OAAO,CAAC;QACvD,0BAA0B,EAAE,IAAA,iEAAkC,EAAC,OAAO,CAAC;QACvE,cAAc,EAAE,IAAA,wCAAsB,EAAC,OAAO,CAAC;QAC/C,gDAAgD;QAChD,OAAO,EAAE,IAAA,yBAAe,EAAC,OAAO,CAAC;QACjC,UAAU,EAAE,IAAA,+BAAkB,EAAC,OAAO,CAAC;QACvC,aAAa,EAAE,IAAA,qCAAqB,EAAC,OAAO,CAAC;QAC7C,0EAA0E;QAC1E,WAAW,EAAE,IAAA,kCAAmB,EAAC,OAAO,CAAC;QACzC,MAAM,EAAE,IAAA,yBAAc,EAAC,OAAO,CAAC;QAC/B,KAAK,EAAE,IAAA,wBAAa,EAAC,OAAO,CAAC;QAC7B,eAAe,EAAE,IAAA,kCAAuB,EAAC,OAAO,CAAC;QACjD,GAAG,EAAE,IAAA,iBAAW,EAAC,OAAO,CAAC;QACzB,GAAG,EAAE,IAAA,iBAAW,EAAC,OAAO,CAAC;QACzB,YAAY,EAAE,IAAA,0BAAoB,EAAC,OAAO,CAAC;QAC3C,oBAAoB,EAAE,IAAA,0CAA4B,EAAC,OAAO,CAAC;QAC3D,YAAY,EAAE,IAAA,oCAAoB,EAAC,OAAO,CAAC;QAC3C,mBAAmB,EAAE,IAAA,mDAA2B,EAAC,OAAO,CAAC;QACzD,OAAO,EAAE,IAAA,yBAAe,EAAC,OAAO,CAAC;QACjC,sFAAsF;QACtF,QAAQ,EAAE,IAAA,4BAAgB,EAAC,OAAO,CAAC;QACnC,WAAW,EAAE,IAAA,iCAAmB,EAAC,OAAO,CAAC;QACzC,wEAAwE;QACxE,qBAAqB,EAAE,IAAA,uDAA6B,EAAC,OAAO,CAAC;KAC9D,CAAC;AACJ,CAAC;AAoBD,qCAA4C;AAAnC,0GAAA,eAAe,OAAA;AACxB,iCAA+D;AAAtD,wGAAA,eAAe,OAAA;AACxB,uCAAuD;AAA9C,qHAAA,yBAAyB,OAAA;AAElC,iCAA6D;AAApD,sGAAA,aAAa,OAAA;AACtB,uCAA+C;AAAtC,oGAAA,QAAQ,OAAA;AAAE,mGAAA,OAAO,OAAA;AAE1B,oEAAoE;AACpE,0CAAwB;AACxB,0CAAwB;AACxB,6CAA2B;AAC3B,kDAAgC;AAChC,0CAAwB;AACxB,kDAAgC;AAChC,qDAAmC;AACnC,oDAAkC;AAClC,gDAA8B;AAC9B,4CAA0B;AAC1B,6CAA2B;AAC3B,iDAA+B;AAC/B,sDAAoC;AACpC,iDAA+B;AAC/B,gDAA8B;AAC9B,6CAA2B;AAC3B,mDAAiC;AACjC,+CAA6B;AAC7B,kDAAgC;AAChC,6CAA2B;AAC3B,6CAA2B;AAC3B,oDAAkC;AAClC,mDAAiC;AACjC,sDAAoC;AACpC,wCAAsB;AACtB,+CAA6B;AAC7B,mDAAiC;AACjC,gDAA8B;AAC9B,iDAA+B;AAC/B,gDAA8B;AAC9B,gDAA8B;AAC9B,6CAA2B;AAC3B,oDAAkC;AAClC,kDAAgC;AAChC,kDAAgC;AAChC,4CAA0B;AAC1B,kDAAgC;AAChC,8CAA4B;AAC5B,kDAAgC;AAChC,0DAAwC;AACxC,mDAAiC;AACjC,kDAAgC;AAChC,6CAA2B;AAC3B,sDAAoC;AACpC,2CAAyB;AACzB,4CAA0B;AAC1B,2CAAyB;AACzB,0DAAwC;AACxC,yDAAuC;AACvC,iEAA+C;AAC/C,oDAAkC;AAClC,4CAA0B;AAC1B,+CAA6B;AAC7B,kDAAgC;AAChC,iDAA+B;AAC/B,6CAA2B;AAC3B,wCAAsB;AACtB,wCAAsB;AACtB,gDAA8B;AAC9B,kDAAgC;AAChC,0DAAwC;AACxC,4CAA0B;AAC1B,8CAA4B;AAC5B,gDAA8B;AAC9B,4DAA0C;AAC1C,6CAA2B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}

package/dist/client/referrals.d.ts

@@ -0,0 +1,405 @@
+import { type RequestFn } from './request';
+import type { ListPage } from './types';
+import type { UserReferralResult } from './users';
+/**
+ * Referral attribution: the instance's connection to a referral platform.
+ *
+ * With referrals on, every interactive sign-up is reported to the platform
+ * before `user.created` is sent and before the session is issued. The
+ * platform's answer lands on the user (`referral`, `referral_code`,
+ * `referral_link`). A slow or failing platform never fails a sign-up: the
+ * call is retried, and `user.referral_attributed` is sent when it resolves.
+ *
+ * `provider` is `webhook` (the Atlas referral protocol, which any platform can
+ * implement; see {@link verifyReferralRequest}), `referally` (the built-in
+ * Referally adapter: `endpoint_url` is your Referally base URL, plus
+ * `connection_id`, `signing_secret` and optionally `tracking_token`) or
+ * another built-in vendor adapter.
+ * `signing_secret` and `api_key` are write-only: reads return
+ * `signing_secret_set` / `api_key_set`.
+ */
+/** What a provider can do. An operation it lacks is recorded as `skipped`. */
+export interface ReferralProviderCapabilities {
+    signup: boolean;
+    erase: boolean;
+    export: boolean;
+    partner: boolean;
+    auto_enroll: boolean;
+    signal: boolean;
+    /** Forwards an `external_id` change after sign-up (old id → new id). */
+    alias?: boolean;
+    /** Forwards email, name and ban/unban changes. */
+    user?: boolean;
+    /** Answers a ping (org, program, clock) for the connection test. */
+    ping?: boolean;
+}
+/** A referral provider Atlas supports. */
+export interface ReferralProviderInfo {
+    /** `webhook` (the Atlas referral protocol) or a vendor adapter id (`dub`, `firstpromoter`, …). */
+    id: string;
+    name: string;
+    capabilities: ReferralProviderCapabilities;
+    /** What must be set before `enabled` can be true. */
+    needs: Array<'endpoint_url' | 'signing_secret' | 'api_key' | 'connection_id' | 'tracking_token'>;
+    /** The vendor's own first-party tracking cookie, suggested when this provider is picked. */
+    default_context_cookie: string | null;
+    docs_url: string | null;
+}
+/** Fraud and bot protection for referred sign-ups (`security` on the settings). */
+export interface ReferralSecuritySettings {
+    /**
+     * `always` (default): a sign-up carrying a referral code must pass the bot
+     * challenge, even where the captcha is otherwise off. `inherit`: the
+     * instance captcha policy decides. With no working captcha, `always` behaves
+     * as `inherit` and preflight reports `referrals_without_bot_protection`.
+     */
+    challenge_referred_signups: 'always' | 'inherit';
+    /**
+     * `flag` (default): report the sign-up with its risk. `strip`: report it as
+     * not referred, with `rejected.reason`. `hold`: report nothing until the
+     * email is proven, then re-assess.
+     */
+    on_high_risk: 'flag' | 'strip' | 'hold';
+    /** Hold every referred sign-up until the email is proven. Default false. */
+    hold_until_email_verified: boolean;
+    /** Referred sign-ups per code from one IP network or device per hour before a velocity signal (1-1000, default 5). */
+    max_referred_signups_per_ip_hour: number;
+}
+/** The connection's health, as the settings read reports it. */
+export interface ReferralConnectionStatus {
+    /** The last connection test, or null when never tested. */
+    last_test: {
+        ok: boolean;
+        at: number;
+        http_status: number | null;
+        error: string | null;
+    } | null;
+    /** Calls that failed permanently in the last 7 days. */
+    failed_calls_7d: number;
+    /** Calls waiting for a retry. */
+    retrying_calls: number;
+    /** Epoch ms of the last successful call, or null. */
+    last_success_at: number | null;
+    /** The last ping answer, when the provider supports ping. */
+    last_ping?: ReferralPing | null;
+    /**
+     * A refusal only a person can fix: `signature_rejected` (the platform
+     * answered 401: a rotated secret or clock skew) or `connection_paused`.
+     */
+    alert?: {
+        code: string;
+        message: string;
+        at: number;
+        call_id?: string;
+    } | null;
+}
+/** What a platform answers to a ping. */
+export interface ReferralPing {
+    ok: boolean;
+    connection_id?: string | null;
+    program_id?: string | null;
+    program_name?: string | null;
+    org_name?: string | null;
+    auto_enroll_users?: boolean | null;
+    /** The platform's clock, as it sent it. */
+    server_time?: string | number | null;
+    /** Platform clock minus Atlas clock, in ms. Over 60 s is a warning; over 5 minutes, signatures fail. */
+    clock_skew_ms?: number | null;
+    /** True when `clock_skew_ms` is over 60 seconds. */
+    clock_skew_warning?: boolean;
+    /** Epoch ms of the ping. */
+    at?: number | null;
+    http_status?: number | null;
+    latency_ms?: number | null;
+    error_code?: string | null;
+    error?: string | null;
+}
+/** `GET /v1/instance/referrals`. */
+export interface ReferralSettings {
+    object: 'referral_settings';
+    enabled: boolean;
+    /** `webhook` (the Atlas referral protocol) or a built-in vendor adapter id. */
+    provider: string;
+    /** Base URL of the platform connection (Atlas referral protocol). */
+    endpoint_url: string | null;
+    /** Passed through to the platform. */
+    program_id: string | null;
+    /** Your label for the connection on the platform side. */
+    connection_id: string | null;
+    /** Whether a signing secret is stored (the value is never returned). */
+    signing_secret_set: boolean;
+    /** Whether a vendor API key is stored (the value is never returned). */
+    api_key_set: boolean;
+    /** Query parameters that carry a referral code, in priority order (default `ref`, `via`, `aff`). */
+    url_params: string[];
+    /** First-party tracking cookie read under consent; null = never read a cookie. */
+    context_cookie: string | null;
+    consent_category: string;
+    consent_fallback_category: string | null;
+    /** Every new user becomes a referrer (gets a code and link from the platform). */
+    auto_enroll_users: boolean;
+    /** e.g. `https://app.example.com/join?ref={code}`; builds `referral_link`. */
+    link_template: string | null;
+    /** How long a sign-up waits for the platform (100-5000 ms, default 3000). */
+    timeout_ms: number;
+    security: ReferralSecuritySettings;
+    /** Public tracking token (the `referally` adapter derives the code lookup from it). */
+    tracking_token?: string | null;
+    /** Public, CORS-enabled lookup with `{code}` for "X invited you" on hosted sign-up. */
+    code_lookup_url?: string | null;
+    /** Show an optional "Referral code" field on hosted sign-up. */
+    signup_code_field?: boolean;
+    /** Forward email, name and ban/unban changes to the platform (default true). */
+    forward_lifecycle?: boolean;
+    /** Mirror the result into `public_metadata.referral` (default false). */
+    mirror_to_public_metadata?: boolean;
+    /** Add a `referral_code` claim (the user's own code) to ID tokens and sessions. */
+    include_referral_claims?: boolean;
+    /** What the chosen provider still needs before referrals can be enabled. */
+    missing?: string[];
+    connection?: ReferralConnectionStatus | null;
+    providers: ReferralProviderInfo[];
+    updated_at?: number | null;
+}
+/**
+ * `PATCH /v1/instance/referrals`: only the fields sent change, `null` clears.
+ * Enabling without what the provider needs is `422 REFERRALS_NOT_CONFIGURED`.
+ */
+export interface UpdateReferralSettingsBody {
+    enabled?: boolean;
+    provider?: string;
+    /** https only (http only for localhost on a development instance). */
+    endpoint_url?: string | null;
+    program_id?: string | null;
+    connection_id?: string | null;
+    /** Write-only, 16-512 characters. */
+    signing_secret?: string | null;
+    /** Write-only vendor API key. */
+    api_key?: string | null;
+    /** 1-10 names of `[A-Za-z0-9_.-]{1,40}`. */
+    url_params?: string[];
+    context_cookie?: string | null;
+    consent_category?: string;
+    consent_fallback_category?: string | null;
+    auto_enroll_users?: boolean;
+    /** An https URL containing `{code}`. */
+    link_template?: string | null;
+    /** 100-5000. */
+    timeout_ms?: number;
+    /** Partial: only the security fields sent change. */
+    security?: Partial<ReferralSecuritySettings>;
+    tracking_token?: string | null;
+    /** An https URL containing `{code}`. */
+    code_lookup_url?: string | null;
+    signup_code_field?: boolean;
+    forward_lifecycle?: boolean;
+    mirror_to_public_metadata?: boolean;
+    include_referral_claims?: boolean;
+}
+/** `POST /v1/instance/referrals/test`. */
+export interface ReferralConnectionTest {
+    ok: boolean;
+    http_status?: number | null;
+    latency_ms?: number | null;
+    /** e.g. `signature_rejected` (the platform answered 401/403), `timeout`, `network_error`, `url_blocked`, `http_500`. */
+    error?: {
+        code: string;
+        message: string;
+    };
+    /** The ping answer, when the provider supports ping (the test is then a ping). */
+    ping?: ReferralPing | null;
+    /** `ping`, or `probe` (the older signed export probe). */
+    method?: 'ping' | 'probe';
+    /** Human warnings, e.g. a clock more than 60 seconds off. */
+    warnings?: string[];
+}
+/** `POST /v1/instance/referrals/simulate`: a sign-up call for a fake user, never stored. */
+export interface ReferralSimulateResult {
+    object: 'referral_simulation';
+    ok: boolean;
+    /** The logged call, in the delivery log. */
+    call_id: string | null;
+    /** `atlas_test_<random>`. */
+    customer_ref: string;
+    http_status: number | null;
+    latency_ms: number | null;
+    /** The platform's answer, normalised (null when the call failed). */
+    result: {
+        referral: {
+            partner_id: string | null;
+            partner_external_ref: string | null;
+            matched_via: string | null;
+            status: string | null;
+        } | null;
+        partner: {
+            id: string | null;
+            code: string | null;
+            link: string | null;
+        } | null;
+        notes: string[];
+    } | null;
+    /** The platform's raw answer, personal fields removed. */
+    response: unknown;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+}
+/** `POST /v1/instance/referrals/calls/retry_failed`. */
+export interface ReferralRetryFailedResult {
+    object: 'referral_retry';
+    /** How many failed calls were queued to send now. */
+    requeued: number;
+}
+/** `POST /v1/instance/referrals/backfill`. */
+export interface ReferralBackfillBody {
+    /** ISO 8601 date or date-time: users who signed up at or after it. */
+    since: string;
+    /** customerRef → code (a CSV, for example). Wins over `code_metadata_path`. */
+    codes?: Record<string, string>;
+    /** Where a stored code lives on the user, e.g. `public_metadata.referral_code`. */
+    code_metadata_path?: string;
+}
+/** A backfill job. Users already reported are skipped. */
+export interface ReferralBackfillJob {
+    object: 'referral_backfill';
+    id: string;
+    /** `running` while any queued call is still to be sent, then `completed`. */
+    status: string;
+    /** Epoch ms. */
+    since: number;
+    code_metadata_path?: string | null;
+    /** How many codes were given in `codes`. */
+    codes_given?: number;
+    users_scanned: number;
+    /** Already reported, or no code while auto-enroll is off. */
+    users_skipped: number;
+    calls_queued: number;
+    /** True when the run stopped at its cap: start another from `next_since`. */
+    truncated: boolean;
+    /** Epoch ms, when `truncated`. */
+    next_since?: number | null;
+    /** Where the queued calls stand. */
+    calls: {
+        pending: number;
+        succeeded: number;
+        failed: number;
+        skipped: number;
+        held: number;
+    };
+    created_at: number;
+    finished_at?: number | null;
+}
+export type ReferralCallKind = 'signup' | 'erase' | 'export' | 'partner' | 'signal' | 'alias' | 'user' | 'ping' | 'test';
+export type ReferralCallStatus = 'pending' | 'succeeded' | 'retrying' | 'failed' | 'held' | 'skipped';
+/** The risk verdict sent with a sign-up (camelCase, as on the referral protocol). */
+export interface ReferralRisk {
+    level: 'low' | 'medium' | 'high';
+    /** 0-100. */
+    score: number;
+    /**
+     * e.g. `self_referral`, `ip_velocity`, `device_velocity`, `disposable_email`,
+     * `datacenter_ip`, `tor_ip`, `captcha_not_passed`, `email_unverified`,
+     * `restricted_identifier`.
+     */
+    signals: string[];
+    captcha: 'passed' | 'not_required' | 'not_configured';
+    emailVerified: boolean;
+}
+/** One call in the referral call log. */
+export interface ReferralCall {
+    object: 'referral_call';
+    /** Also the signed `atlas-id` header of every attempt. */
+    id: string;
+    kind: ReferralCallKind;
+    status: ReferralCallStatus;
+    /** Sign-up calls: `referred`, `not_referred` or `stripped`. */
+    outcome?: string | null;
+    customer_ref: string;
+    user_id?: string | null;
+    http_status?: number | null;
+    last_error?: string | null;
+    attempts: number;
+    /** Epoch ms of the next retry, while pending or retrying. */
+    next_attempt_at?: number | null;
+    risk?: ReferralRisk | null;
+    /** What was sent (never secrets). */
+    payload?: Record<string, unknown>;
+    /** Round trip of the last attempt, in ms. */
+    latency_ms?: number | null;
+    /**
+     * Machine code of the last failure, e.g. `signature_rejected` (401, not
+     * retried), `connection_paused` (paused by the merchant, not retried),
+     * `rate_limited`, `timeout`, `network_error`.
+     */
+    error_code?: string | null;
+    /** The platform's last answer, with personal data removed. */
+    response?: unknown;
+    /** Sign-up calls: how the platform matched, the referrer and its notes. */
+    highlights?: {
+        matched_via: string | null;
+        partner_external_ref: string | null;
+        notes: string[];
+    } | null;
+    /** The platform's request id for its last answer, for its support team. */
+    request_id?: string | null;
+    /** The backfill job this call belongs to. */
+    batch_id?: string | null;
+    created_at: number;
+    updated_at?: number;
+}
+export interface ListReferralCallsParams {
+    /** 1-1000 (1-200 on servers before referral attribution v2), default 50, newest first. */
+    limit?: number;
+    status?: ReferralCallStatus;
+    kind?: ReferralCallKind;
+    user_id?: string;
+    /** e.g. `signature_rejected`. */
+    error_code?: string;
+    /** The id of the last call of the previous page. */
+    starting_after?: string;
+}
+export declare function referralsResource(request: RequestFn): {
+    /** `GET /v1/instance/referrals` — settings, connection status and the supported providers. */
+    get(): Promise<ReferralSettings>;
+    /** `PATCH /v1/instance/referrals` — partial update; secrets are write-only. */
+    update(body: UpdateReferralSettingsBody, idempotencyKey?: string): Promise<ReferralSettings>;
+    /**
+     * `POST /v1/instance/referrals/test` — a signed probe of the platform. `ok`
+     * when it answered 2xx or 404; `error.code` `signature_rejected` on 401/403.
+     */
+    test(): Promise<ReferralConnectionTest>;
+    /** `GET /v1/instance/referrals/calls` — the call log, newest first. */
+    listCalls(params?: ListReferralCallsParams): Promise<ListPage<ReferralCall>>;
+    /**
+     * `POST /v1/instance/referrals/calls/:id/retry` — retry a failed, retrying
+     * or skipped call now (a connection test cannot be retried).
+     */
+    retryCall(id: string, idempotencyKey?: string): Promise<ReferralCall>;
+    /** `POST /v1/instance/referrals/calls/retry_failed` — re-queue every failed call (not tests) to send now. */
+    retryFailed(filter?: {
+        kind?: ReferralCallKind;
+        error_code?: string;
+    }, idempotencyKey?: string): Promise<ReferralRetryFailedResult>;
+    /**
+     * `POST /v1/instance/referrals/simulate` — send a sign-up call for a fake
+     * user (`atlas_test_<random>`, never stored) with an optional code, and
+     * return what the platform answered.
+     */
+    simulate(body?: {
+        code?: string;
+    }): Promise<ReferralSimulateResult>;
+    /**
+     * `POST /v1/instance/referrals/backfill` — queue sign-up calls for existing
+     * users with their real sign-up time. Referrals must be on (`422
+     * REFERRALS_NOT_CONFIGURED` otherwise). Returns the job; poll {@link getBackfill}.
+     */
+    backfill(body: ReferralBackfillBody, idempotencyKey?: string): Promise<ReferralBackfillJob>;
+    /** `GET /v1/instance/referrals/backfill/:id`. */
+    getBackfill(id: string): Promise<ReferralBackfillJob>;
+    /**
+     * `GET /v1/users/:id/referral` — the stored result for one user (who
+     * referred them, how, their own code), with no call to the platform.
+     */
+    getForUser(userId: string): Promise<UserReferralResult>;
+};