@atlasauth/backend 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @atlasauth/backend changelog
 
+## 0.13.0
+
+### Added
+
+- **Two-way referral sync.** Referral settings carry two-way sync: `inbound` (`url`, `secret_set`, `endpoint_id`, `last_event`) on reads, write-only `inbound_secret` and `inbound_endpoint_id` on updates (null clears), and provider capability `inbound`.
+- `signReferralUpdatedEvent(...)` (and `referralUpdatedEvent` on `createTestIssuer()`): builds and signs a `referral.updated` event for a referral platform reporting changes to `POST /v1/webhooks/referrals/{instance_id}`.
+
+## 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`).

package/README.md

@@ -456,3 +456,25 @@ app.post('/atlas/:endpoint', express.raw({ type: '*/*' }), async (req, res) => {
 ```
 
 A retry of one call keeps its `atlas-id` (`deliveryId`). Sign-ups are idempotent on `customerRef`: answer a retry the same way.
+
+### Two-way sync
+
+A provider with the `inbound` capability can send referral changes made after sign-up back to Atlas. The settings report `inbound.url` (give it to the platform), `inbound.secret_set`, `inbound.endpoint_id` and `inbound.last_event` (`{ at, type, outcome }`). Store the platform's event secret with `inbound_secret` (write-only, 16-512 characters) and its subscription id with `inbound_endpoint_id`:
+
+```ts
+await atlas.referrals.update({ inbound_secret: process.env.REFERRAL_INBOUND_SECRET, inbound_endpoint_id: 'we_123' });
+const { inbound } = await atlas.referrals.get(); // inbound.last_event?.outcome: 'applied', 'stale', …
+```
+
+A platform on the Atlas referral protocol sends a `referral.updated` event to `inbound.url`, signed like an Atlas webhook with the inbound secret (or the connection's signing secret when none is set). `signReferralUpdatedEvent` builds it:
+
+```ts
+import { signReferralUpdatedEvent } from '@atlasauth/backend';
+
+const e = signReferralUpdatedEvent({
+  inboundUrl: settings.inbound.url,
+  secret: process.env.REFERRAL_SIGNING_SECRET!,
+  event: { customerRef: 'user_123', referralId: 'ref_1', status: 'qualified' },
+});
+await fetch(e.request());
+```

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>;
@@ -979,6 +980,21 @@ declare function buildNamespaces(request: RequestFn): {
         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>;
@@ -1331,6 +1347,7 @@ 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

@@ -61,6 +61,7 @@ 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");
@@ -150,6 +151,8 @@ function buildNamespaces(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.
@@ -240,6 +243,7 @@ __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":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"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"}

package/dist/client/referrals.d.ts

@@ -1,5 +1,6 @@
 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.
  *
@@ -10,9 +11,16 @@ import type { ListPage } from './types';
  * 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}) or a built-in vendor adapter.
- * `signing_secret` and `api_key` are write-only: reads return
- * `signing_secret_set` / `api_key_set`.
+ * 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`, `api_key` and `inbound_secret` are write-only: reads
+ * return `signing_secret_set` / `api_key_set` / `inbound.secret_set`.
+ *
+ * Two-way sync: a provider with the `inbound` capability sends referral
+ * changes made after sign-up to `inbound.url`; Atlas applies them to the
+ * user's referral and reports the latest one in `inbound.last_event`.
  */
 /** What a provider can do. An operation it lacks is recorded as `skipped`. */
 export interface ReferralProviderCapabilities {
@@ -22,6 +30,14 @@ export interface ReferralProviderCapabilities {
     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;
+    /** Sends referral changes made after sign-up to Atlas (two-way sync). */
+    inbound?: boolean;
 }
 /** A referral provider Atlas supports. */
 export interface ReferralProviderInfo {
@@ -30,7 +46,7 @@ export interface ReferralProviderInfo {
     name: string;
     capabilities: ReferralProviderCapabilities;
     /** What must be set before `enabled` can be true. */
-    needs: Array<'endpoint_url' | 'signing_secret' | 'api_key' | 'connection_id'>;
+    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;
@@ -70,6 +86,56 @@ export interface ReferralConnectionStatus {
     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 Atlas did with an inbound referral event. */
+export type ReferralInboundOutcome = 'applied' | 'unchanged' | 'stale' | 'unknown_customer' | 'other_program' | 'ignored';
+/** Two-way sync (`inbound` on the settings). */
+export interface ReferralInboundStatus {
+    /** Give this URL to the platform; null when the provider sends no events. */
+    url: string | null;
+    /** Whether an inbound secret is stored (the value is never returned). */
+    secret_set: boolean;
+    /** The platform's id for Atlas's event subscription, kept for reference. */
+    endpoint_id: string | null;
+    /** The latest event received, or null when none yet. */
+    last_event: {
+        at: number;
+        type: string;
+        outcome: ReferralInboundOutcome;
+    } | 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 {
@@ -100,9 +166,23 @@ export interface ReferralSettings {
     /** 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;
+    /** Two-way sync: where the platform sends referral changes, and the latest one received. */
+    inbound?: ReferralInboundStatus;
     providers: ReferralProviderInfo[];
     updated_at?: number | null;
 }
@@ -121,6 +201,14 @@ export interface UpdateReferralSettingsBody {
     signing_secret?: string | null;
     /** Write-only vendor API key. */
     api_key?: string | null;
+    /**
+     * Write-only, 16-512 characters. Verifies the platform's events to
+     * `inbound.url`. Optional for the Atlas referral protocol (the signing
+     * secret is used when unset).
+     */
+    inbound_secret?: string | null;
+    /** The platform's id for Atlas's event subscription, kept for reference. */
+    inbound_endpoint_id?: string | null;
     /** 1-10 names of `[A-Za-z0-9_.-]{1,40}`. */
     url_params?: string[];
     context_cookie?: string | null;
@@ -133,6 +221,13 @@ export interface UpdateReferralSettingsBody {
     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 {
@@ -144,8 +239,91 @@ export interface ReferralConnectionTest {
         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' | 'test';
+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 {
@@ -180,15 +358,39 @@ export interface ReferralCall {
     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-200, default 50, newest first. */
+    /** 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. */
@@ -207,4 +409,30 @@ export declare function referralsResource(request: RequestFn): {
      * 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>;
 };

package/dist/client/referrals.js

@@ -34,6 +34,37 @@ function referralsResource(request) {
                 idempotencyKey,
             });
         },
+        /** `POST /v1/instance/referrals/calls/retry_failed` — re-queue every failed call (not tests) to send now. */
+        retryFailed(filter = {}, idempotencyKey) {
+            return request({ method: 'POST', path: '/v1/instance/referrals/calls/retry_failed', body: filter, idempotencyKey });
+        },
+        /**
+         * `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 = {}) {
+            return request({ method: 'POST', path: '/v1/instance/referrals/simulate', body });
+        },
+        /**
+         * `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, idempotencyKey) {
+            return request({ method: 'POST', path: '/v1/instance/referrals/backfill', body, idempotencyKey });
+        },
+        /** `GET /v1/instance/referrals/backfill/:id`. */
+        getBackfill(id) {
+            return request({ method: 'GET', path: `/v1/instance/referrals/backfill/${(0, request_1.enc)(id)}` });
+        },
+        /**
+         * `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) {
+            return request({ method: 'GET', path: `/v1/users/${(0, request_1.enc)(userId)}/referral` });
+        },
     };
 }
 //# sourceMappingURL=referrals.js.map

package/dist/client/referrals.js.map

@@ -1 +1 @@
-{"version":3,"file":"referrals.js","sourceRoot":"","sources":["../../src/client/referrals.ts"],"names":[],"mappings":";;AAqMA,8CAiCC;AAtOD,uCAAgD;AAqMhD,SAAgB,iBAAiB,CAAC,OAAkB;IAClD,OAAO;QACL,8FAA8F;QAC9F,GAAG;YACD,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,wBAAwB,EAAE,CAAC,CAAC;QACpE,CAAC;QACD,+EAA+E;QAC/E,MAAM,CAAC,IAAgC,EAAE,cAAuB;YAC9D,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC;QAC5F,CAAC;QACD;;;WAGG;QACH,IAAI;YACF,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,6BAA6B,EAAE,CAAC,CAAC;QAC1E,CAAC;QACD,uEAAuE;QACvE,SAAS,CAAC,SAAkC,EAAE;YAC5C,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,8BAA8B,EAAE,KAAK,EAAE,EAAE,GAAG,MAAM,EAAE,EAAE,CAAC,CAAC;QAChG,CAAC;QACD;;;WAGG;QACH,SAAS,CAAC,EAAU,EAAE,cAAuB;YAC3C,OAAO,OAAO,CAAC;gBACb,MAAM,EAAE,MAAM;gBACd,IAAI,EAAE,gCAAgC,IAAA,aAAG,EAAC,EAAE,CAAC,QAAQ;gBACrD,cAAc;aACf,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"referrals.js","sourceRoot":"","sources":["../../src/client/referrals.ts"],"names":[],"mappings":";;AAsYA,8CAmEC;AAzcD,uCAAgD;AAsYhD,SAAgB,iBAAiB,CAAC,OAAkB;IAClD,OAAO;QACL,8FAA8F;QAC9F,GAAG;YACD,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,wBAAwB,EAAE,CAAC,CAAC;QACpE,CAAC;QACD,+EAA+E;QAC/E,MAAM,CAAC,IAAgC,EAAE,cAAuB;YAC9D,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC;QAC5F,CAAC;QACD;;;WAGG;QACH,IAAI;YACF,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,6BAA6B,EAAE,CAAC,CAAC;QAC1E,CAAC;QACD,uEAAuE;QACvE,SAAS,CAAC,SAAkC,EAAE;YAC5C,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,8BAA8B,EAAE,KAAK,EAAE,EAAE,GAAG,MAAM,EAAE,EAAE,CAAC,CAAC;QAChG,CAAC;QACD;;;WAGG;QACH,SAAS,CAAC,EAAU,EAAE,cAAuB;YAC3C,OAAO,OAAO,CAAC;gBACb,MAAM,EAAE,MAAM;gBACd,IAAI,EAAE,gCAAgC,IAAA,aAAG,EAAC,EAAE,CAAC,QAAQ;gBACrD,cAAc;aACf,CAAC,CAAC;QACL,CAAC;QACD,6GAA6G;QAC7G,WAAW,CACT,SAA2D,EAAE,EAC7D,cAAuB;YAEvB,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,2CAA2C,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC;QACtH,CAAC;QACD;;;;WAIG;QACH,QAAQ,CAAC,OAA0B,EAAE;YACnC,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,iCAAiC,EAAE,IAAI,EAAE,CAAC,CAAC;QACpF,CAAC;QACD;;;;WAIG;QACH,QAAQ,CAAC,IAA0B,EAAE,cAAuB;YAC1D,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,iCAAiC,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC;QACpG,CAAC;QACD,iDAAiD;QACjD,WAAW,CAAC,EAAU;YACpB,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,mCAAmC,IAAA,aAAG,EAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QACxF,CAAC;QACD;;;WAGG;QACH,UAAU,CAAC,MAAc;YACvB,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,IAAA,aAAG,EAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;QAC/E,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/client/user-hooks.d.ts

@@ -0,0 +1,58 @@
+import type { RequestFn } from './request';
+/**
+ * The `before_user_create` hook: just before Atlas creates a user from an
+ * interactive sign-up, it calls your endpoint (signed exactly like a webhook:
+ * `atlas-id`, `atlas-timestamp`, `atlas-signature`, verify with
+ * {@link verifyWebhook}) with an event of type `user.before_create`, and stamps
+ * the `external_id` and metadata you answer. A referral call then goes out
+ * with your id. Slow or failing hooks never block a sign-up.
+ *
+ * Answer `{ external_id?, public_metadata?, private_metadata?, unsafe_metadata? }`.
+ */
+export interface BeforeUserCreateHook {
+    object: 'before_user_create_hook';
+    enabled: boolean;
+    url: string | null;
+    /** The secret is write-only. */
+    signing_secret_set: boolean;
+    /** At most 5000, default 3000. */
+    timeout_ms: number;
+    /** The last call Atlas made to the hook. */
+    last_call: {
+        at: number;
+        status: string | null;
+        error: string | null;
+    } | null;
+    updated_at: number | null;
+}
+export interface UpdateBeforeUserCreateHookBody {
+    enabled?: boolean;
+    /** https (http only for localhost on a development instance); `null` clears. */
+    url?: string | null;
+    /** Write-only; `null` clears. */
+    signing_secret?: string | null;
+    timeout_ms?: number;
+}
+/** `POST …/test`: a sample draft sent to the hook; nothing is stored. */
+export interface BeforeUserCreateHookTest {
+    ok: boolean;
+    latency_ms: number;
+    answer?: {
+        external_id: string | null;
+        public_metadata: Record<string, unknown> | null;
+        private_metadata_set: boolean;
+        unsafe_metadata: Record<string, unknown> | null;
+    };
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export declare function userHooksResource(request: RequestFn): {
+    /** `GET /v1/instance/hooks/before_user_create`. */
+    getBeforeUserCreate(): Promise<BeforeUserCreateHook>;
+    /** `PATCH /v1/instance/hooks/before_user_create` — partial; the secret is write-only. */
+    updateBeforeUserCreate(body: UpdateBeforeUserCreateHookBody): Promise<BeforeUserCreateHook>;
+    /** `POST /v1/instance/hooks/before_user_create/test`. */
+    testBeforeUserCreate(): Promise<BeforeUserCreateHookTest>;
+};

package/dist/client/user-hooks.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.userHooksResource = userHooksResource;
+const PATH = '/v1/instance/hooks/before_user_create';
+function userHooksResource(request) {
+    return {
+        /** `GET /v1/instance/hooks/before_user_create`. */
+        getBeforeUserCreate() {
+            return request({ method: 'GET', path: PATH });
+        },
+        /** `PATCH /v1/instance/hooks/before_user_create` — partial; the secret is write-only. */
+        updateBeforeUserCreate(body) {
+            return request({ method: 'PATCH', path: PATH, body });
+        },
+        /** `POST /v1/instance/hooks/before_user_create/test`. */
+        testBeforeUserCreate() {
+            return request({ method: 'POST', path: `${PATH}/test` });
+        },
+    };
+}
+//# sourceMappingURL=user-hooks.js.map

package/dist/client/user-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-hooks.js","sourceRoot":"","sources":["../../src/client/user-hooks.ts"],"names":[],"mappings":";;AAkDA,8CAeC;AAjBD,MAAM,IAAI,GAAG,uCAAuC,CAAC;AAErD,SAAgB,iBAAiB,CAAC,OAAkB;IAClD,OAAO;QACL,mDAAmD;QACnD,mBAAmB;YACjB,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,CAAC;QACD,yFAAyF;QACzF,sBAAsB,CAAC,IAAoC;YACzD,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,yDAAyD;QACzD,oBAAoB;YAClB,OAAO,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,OAAO,EAAE,CAAC,CAAC;QAC3D,CAAC;KACF,CAAC;AACJ,CAAC"}