@atlasauth/cli 0.16.0 → 0.18.0

package/dist/commands/referrals.js

@@ -5,6 +5,9 @@ exports.pingSkewMs = pingSkewMs;
 exports.describeTestLines = describeTestLines;
 exports.parseCodeCsv = parseCodeCsv;
 exports.referalliKeyMode = referalliKeyMode;
+exports.referalliList = referalliList;
+exports.referalliLinkTemplate = referalliLinkTemplate;
+exports.webhookScope = webhookScope;
 exports.referrals = referrals;
 const node_crypto_1 = require("node:crypto");
 const referral_conformance_1 = require("@atlasauth/referral-conformance");
@@ -17,7 +20,7 @@ const secrets_1 = require("../secrets");
 const project_commands_1 = require("./project-commands");
 const shared_1 = require("./shared");
 /**
- * `atlas referrals connect | backfill | status`: referral attribution from the
+ * `atlas referrals connect | backfill | resync | status`: referral attribution from the
  * terminal.
  *
  * `connect --provider referalli` is bring-your-own-key: the Referalli merchant
@@ -108,7 +111,7 @@ function describeTestLines(test, receivedAt) {
     return lines;
 }
 /** A `customerRef,code` CSV → map; throws on a bad line. A header row is skipped. */
-function parseCodeCsv(text) {
+function parseCodeCsv(text, flag = '--map') {
     const out = {};
     const lines = text.split(/\r?\n/);
     lines.forEach((line, i) => {
@@ -119,9 +122,9 @@ function parseCodeCsv(text) {
         if (i === 0 && /^(customer_?ref|user_?id|external_?id|user)$/i.test(ref ?? ''))
             return;
         if (!ref || !code)
-            throw new errors_1.CliError(`--map line ${i + 1}: expected customerRef,code.`);
+            throw new errors_1.CliError(`${flag} line ${i + 1}: expected customerRef,code.`);
         if (!/^[A-Za-z0-9_-]{3,64}$/.test(code))
-            throw new errors_1.CliError(`--map line ${i + 1}: '${code}' is not a valid code.`);
+            throw new errors_1.CliError(`${flag} line ${i + 1}: '${code}' is not a valid code.`);
         out[ref] = code;
     });
     return out;
@@ -186,19 +189,111 @@ exports.REFERALLI_SYNC_TOPICS = [
  * `known` is false when Referalli reports no mode (no test mode there).
  */
 async function referalliKeyMode(ctx, input) {
+    const org = await referalliTry(ctx, { ...input, path: '/v1/org', what: 'read the organization' });
+    if (typeof org?.livemode === 'boolean')
+        return { live: org.livemode, known: true, org };
+    if (input.key.startsWith('rk_test_'))
+        return { live: false, known: true, org };
+    if (input.key.startsWith('rk_live_'))
+        return { live: true, known: true, org };
+    return { live: true, known: false, org };
+}
+/** A best-effort Referalli read: null when it fails (an older Referalli, a key without access). */
+async function referalliTry(ctx, input) {
     try {
-        const org = await referalliRequest(ctx, { ...input, method: 'GET', path: '/v1/org', what: 'read the organization' });
-        if (typeof org.livemode === 'boolean')
-            return { live: org.livemode, known: true };
+        return await referalliRequest(ctx, { ...input, method: 'GET' });
     }
-    catch {
-        /* fall back to the key prefix */
+    catch (err) {
+        if (err instanceof errors_1.CliError)
+            return null;
+        throw err;
     }
-    if (input.key.startsWith('rk_test_'))
-        return { live: false, known: true };
-    if (input.key.startsWith('rk_live_'))
-        return { live: true, known: true };
-    return { live: true, known: false };
+}
+/** A Referalli list answer: a plain array (API version 2026-10-21) or a `{ data: [...] }` page. */
+function referalliList(body) {
+    const rows = Array.isArray(body) ? body : body && typeof body === 'object' && Array.isArray(body.data) ? body.data : [];
+    return rows.filter((r) => !!r && typeof r === 'object' && !Array.isArray(r));
+}
+/** Referalli's public tracked link for a code: `{host}/go/{trackingToken}/{code}`, on the org's link domain once it is active. */
+function referalliLinkTemplate(baseUrl, trackingToken, branding) {
+    const domain = branding?.linkDomainStatus === 'active' && typeof branding.linkDomain === 'string' && branding.linkDomain ? branding.linkDomain : null;
+    return `${domain ? `https://${domain}` : baseUrl}/go/${encodeURIComponent(trackingToken)}/{code}`;
+}
+/** The merchant key from --referalli-key / --referalli-key-file / REFERALLI_API_KEY (or their old names); never printed. */
+function referalliKeyFrom(ctx, v) {
+    const oldKeyFile = (0, args_1.str)(v, LEGACY.keyFileFlag);
+    const oldKey = (0, args_1.str)(v, LEGACY.keyFlag);
+    if (oldKeyFile)
+        legacyNotice(ctx, `--${LEGACY.keyFileFlag}`, '--referalli-key-file');
+    if (oldKey)
+        legacyNotice(ctx, `--${LEGACY.keyFlag}`, '--referalli-key');
+    const legacyKey = ctx.env[LEGACY.apiKeyEnv]?.trim();
+    if (!ctx.env.REFERALLI_API_KEY?.trim() && legacyKey)
+        legacyNotice(ctx, LEGACY.apiKeyEnv, 'REFERALLI_API_KEY');
+    const keyFile = (0, args_1.str)(v, 'referalli-key-file') ?? oldKeyFile;
+    return ((0, args_1.str)(v, 'referalli-key') ??
+        oldKey ??
+        (keyFile ? readKeyFile(ctx, keyFile, 'the Referalli key') : (ctx.env.REFERALLI_API_KEY?.trim() || legacyKey || undefined)));
+}
+/** The `programIds` a Referalli webhook endpoint is limited to: null or [] means every program in the organization. */
+function webhookScope(endpoint) {
+    if (!endpoint)
+        return { scope: 'unknown', program_ids: null };
+    const ids = Array.isArray(endpoint.programIds) ? endpoint.programIds.filter((x) => typeof x === 'string') : [];
+    return ids.length ? { scope: 'program', program_ids: ids } : { scope: 'all_programs', program_ids: null };
+}
+/**
+ * The two-way sync webhook on Referalli, limited to the connected program
+ * (`programIds: [program]`) so another product's referrals in a shared
+ * organization never reach this instance. Idempotent: an endpoint already
+ * pointing at this instance's inbound URL is reused and re-scoped in place
+ * (an unscoped one from an earlier run is repaired); its secret is rotated
+ * only when Atlas does not hold it (`held`: the endpoint whose secret Atlas
+ * stores). `secret` is null when nothing new needs saving.
+ */
+async function referalliSyncEndpoint(ctx, input) {
+    const { baseUrl, key } = input;
+    const scope = { topics: [...exports.REFERALLI_SYNC_TOPICS], legacySignature: false, programIds: [input.program] };
+    const listed = await referalliTry(ctx, { baseUrl, key, path: '/v1/webhook-endpoints', what: 'list the webhook endpoints' });
+    const mine = referalliList(listed).filter((e) => e.url === input.url && typeof e.id === 'string');
+    const found = mine.find((e) => e.id === input.held) ?? mine[0];
+    if (!found) {
+        const endpoint = await referalliRequest(ctx, {
+            baseUrl,
+            key,
+            method: 'POST',
+            path: '/v1/webhook-endpoints',
+            body: { url: input.url, ...scope },
+            what: 'register the referral event webhook',
+        });
+        if (typeof endpoint.id !== 'string' || typeof endpoint.secret !== 'string') {
+            throw new errors_1.CliError('Referalli answered without a webhook endpoint id and secret.');
+        }
+        return { id: endpoint.id, secret: endpoint.secret, duplicates: [] };
+    }
+    const id = found.id;
+    const duplicates = mine.filter((e) => e !== found).map((e) => e.id);
+    await referalliRequest(ctx, {
+        baseUrl,
+        key,
+        method: 'PATCH',
+        path: `/v1/webhook-endpoints/${encodeURIComponent(id)}`,
+        body: scope,
+        what: 'limit the referral event webhook to the program',
+    });
+    if (id === input.held)
+        return { id, secret: null, duplicates };
+    const rotated = await referalliRequest(ctx, {
+        baseUrl,
+        key,
+        method: 'POST',
+        path: `/v1/webhook-endpoints/${encodeURIComponent(id)}/rotate-secret`,
+        body: {},
+        what: 'rotate the referral event webhook secret',
+    });
+    if (typeof rotated.secret !== 'string')
+        throw new errors_1.CliError('Referalli answered without a webhook secret.');
+    return { id, secret: rotated.secret, duplicates };
 }
 /**
  * `connect --provider referalli --oauth`: Atlas starts an OAuth install at
@@ -301,19 +396,7 @@ async function connect(ctx, args) {
         if (!baseRaw)
             throw new errors_1.CliError('Pass --base-url <your Referalli base URL> (or set REFERALLI_BASE_URL).');
         const baseUrl = httpsUrl(baseRaw, '--base-url');
-        const oldKeyFile = (0, args_1.str)(v, LEGACY.keyFileFlag);
-        const oldKey = (0, args_1.str)(v, LEGACY.keyFlag);
-        if (oldKeyFile)
-            legacyNotice(ctx, `--${LEGACY.keyFileFlag}`, '--referalli-key-file');
-        if (oldKey)
-            legacyNotice(ctx, `--${LEGACY.keyFlag}`, '--referalli-key');
-        const legacyKey = ctx.env[LEGACY.apiKeyEnv]?.trim();
-        if (!ctx.env.REFERALLI_API_KEY?.trim() && legacyKey)
-            legacyNotice(ctx, LEGACY.apiKeyEnv, 'REFERALLI_API_KEY');
-        const keyFile = (0, args_1.str)(v, 'referalli-key-file') ?? oldKeyFile;
-        const key = (0, args_1.str)(v, 'referalli-key') ??
-            oldKey ??
-            (keyFile ? readKeyFile(ctx, keyFile, 'the Referalli key') : (ctx.env.REFERALLI_API_KEY?.trim() ?? legacyKey));
+        const key = referalliKeyFrom(ctx, v);
         if (!key) {
             throw new errors_1.CliError('Pass your Referalli merchant key with --referalli-key-file <path|-> (or --referalli-key, or REFERALLI_API_KEY). It is used once and never stored.');
         }
@@ -336,17 +419,49 @@ async function connect(ctx, args) {
         else if (!mode.known && !instanceLive) {
             ctx.io.err(`atlas: warning: Referalli did not say whether this key reaches test data; instance ${instance.id} is ${instance.environment ?? 'not production'}.`);
         }
-        const created = await referalliCreateConnection(ctx, {
-            baseUrl,
-            key,
-            body: {
-                provider: 'atlas',
-                instanceId: instance.id,
-                programId: program,
-                ...(v['auto-enroll'] === true ? { autoEnrollUsers: true } : {}),
-                ...(destination ? { destinationUrl: destination } : {}),
-            },
-        });
+        const enrollment = {
+            ...(v['auto-enroll'] === true ? { autoEnrollUsers: true } : {}),
+            ...(destination ? { destinationUrl: destination } : {}),
+        };
+        const current = await http.get('/v1/instance/referrals');
+        // Re-runs reuse the instance's connection, updated in place: Referalli keeps one per instance per organization.
+        const listed = await referalliTry(ctx, { baseUrl, key, path: '/v1/auth/connections', what: 'list the connections' });
+        const existing = referalliList(listed).find((c) => c.provider === 'atlas' && c.instanceId === instance.id && typeof c.id === 'string');
+        if (existing && typeof existing.programId === 'string' && existing.programId !== program) {
+            throw new errors_1.CliError(`Referalli already has connection ${String(existing.id)} for instance ${instance.id}, in program ${existing.programId}. ` +
+                `It allows one per instance: run again with --program ${existing.programId}, or delete that connection on Referalli first.`);
+        }
+        let connectionId;
+        // Null when Atlas already holds the reused connection's secret.
+        let secret = null;
+        let createdToken = null;
+        if (existing) {
+            connectionId = existing.id;
+            if (current.connection_id !== connectionId || !current.signing_secret_set) {
+                // Atlas does not hold this connection's secret: rotate it (the old one keeps verifying for 24 hours).
+                const rotated = await referalliRequest(ctx, {
+                    baseUrl,
+                    key,
+                    method: 'POST',
+                    path: `/v1/auth/connections/${encodeURIComponent(connectionId)}/rotate-secret`,
+                    body: {},
+                    what: 'rotate the connection secret',
+                });
+                if (typeof rotated.secret !== 'string')
+                    throw new errors_1.CliError('Referalli answered without a connection secret.');
+                secret = rotated.secret;
+            }
+        }
+        else {
+            const created = await referalliCreateConnection(ctx, {
+                baseUrl,
+                key,
+                body: { provider: 'atlas', instanceId: instance.id, programId: program, ...enrollment },
+            });
+            connectionId = created.id;
+            secret = created.secret;
+            createdToken = typeof created.trackingToken === 'string' ? created.trackingToken : null;
+        }
         // Atlas always signs with v2: require it from the first call, so v1 is never accepted on this connection.
         let signatureV2 = true;
         try {
@@ -354,24 +469,32 @@ async function connect(ctx, args) {
                 baseUrl,
                 key,
                 method: 'PATCH',
-                path: `/v1/auth/connections/${encodeURIComponent(created.id)}`,
-                body: { signatureVersion: 'v2' },
-                what: 'require v2 signatures on the connection',
+                path: `/v1/auth/connections/${encodeURIComponent(connectionId)}`,
+                body: { signatureVersion: 'v2', ...(existing ? enrollment : {}) },
+                what: existing ? 'update the connection' : 'require v2 signatures on the connection',
             });
         }
         catch (err) {
             signatureV2 = false;
             ctx.io.err(`atlas: warning: ${err instanceof Error ? err.message : String(err)} It switches to v2 on Atlas's first call anyway.`);
         }
-        const trackingToken = (0, args_1.str)(v, 'tracking-token') ?? (typeof created.trackingToken === 'string' ? created.trackingToken : null);
+        // The org's public tracking token (GET /v1/org) builds Referalli's tracked links; a link template set before is kept.
+        const orgToken = typeof mode.org?.trackingToken === 'string' ? mode.org.trackingToken : null;
+        const trackingToken = (0, args_1.str)(v, 'tracking-token') ?? orgToken ?? createdToken;
+        let linkTemplate = (0, args_1.str)(v, 'link-template') ?? null;
+        if (!linkTemplate && !current.link_template && trackingToken) {
+            const branding = await referalliTry(ctx, { baseUrl, key, path: '/v1/branding', what: 'read the link domain' });
+            linkTemplate = referalliLinkTemplate(baseUrl, trackingToken, branding);
+        }
         patch = {
             provider: 'referalli',
             endpoint_url: baseUrl,
-            connection_id: created.id,
-            signing_secret: created.secret,
+            connection_id: connectionId,
+            ...(secret ? { signing_secret: secret } : {}),
             program_id: program,
             ...(v['auto-enroll'] === true ? { auto_enroll_users: true } : {}),
             ...(trackingToken ? { tracking_token: trackingToken } : {}),
+            ...(linkTemplate ? { link_template: linkTemplate } : {}),
         };
         let saved;
         try {
@@ -379,51 +502,60 @@ async function connect(ctx, args) {
         }
         catch (err) {
             // The secret is shown once by Referalli: keep it so the merchant can finish by hand.
-            const saved = (0, secrets_1.deliverSecret)({
-                io: out,
-                env: ctx.env,
-                product,
-                fileName: `referalli-connection-${created.id}.env`,
-                entries: { REFERALLI_CONNECTION_ID: created.id, REFERALLI_CONNECTION_SECRET: created.secret },
-                label: 'The Referalli connection secret (not saved on Atlas)',
-                force: v.force === true,
-                comment: `Referalli connection ${created.id}: saving it on the Atlas instance failed. Paste it in Users → Referrals.`,
-            });
-            ctx.io.err(`atlas: the connection ${created.id} was created on Referalli, but saving it on the instance failed.${saved.path ? ` Its secret is in ${saved.path}.` : ''}`);
+            const kept = secret
+                ? (0, secrets_1.deliverSecret)({
+                    io: out,
+                    env: ctx.env,
+                    product,
+                    fileName: `referalli-connection-${connectionId}.env`,
+                    entries: { REFERALLI_CONNECTION_ID: connectionId, REFERALLI_CONNECTION_SECRET: secret },
+                    label: 'The Referalli connection secret (not saved on Atlas)',
+                    force: v.force === true,
+                    comment: `Referalli connection ${connectionId}: saving it on the Atlas instance failed. Paste it in Users → Referrals.`,
+                })
+                : { path: undefined };
+            ctx.io.err(`atlas: the connection ${connectionId} ${existing ? 'exists' : 'was created'} on Referalli, but saving it on the instance failed.${kept.path ? ` Its secret is in ${kept.path}.` : ''}`);
             throw err;
         }
-        // Two-way sync: Referalli's referral events go to the instance's inbound URL.
+        // Two-way sync: Referalli's referral events for this program go to the instance's inbound URL.
         let syncEndpoint = null;
+        let syncScope = null;
         const inboundUrl = saved?.inbound?.url ?? null;
         if (v['no-sync'] !== true && inboundUrl) {
             try {
-                const endpoint = await referalliRequest(ctx, {
+                const sync = await referalliSyncEndpoint(ctx, {
                     baseUrl,
                     key,
-                    method: 'POST',
-                    path: '/v1/webhook-endpoints',
-                    body: { url: inboundUrl, topics: [...exports.REFERALLI_SYNC_TOPICS], legacySignature: false },
-                    what: 'register the referral event webhook',
+                    url: inboundUrl,
+                    program,
+                    held: current.inbound?.secret_set ? (current.inbound.endpoint_id ?? null) : null,
                 });
-                if (typeof endpoint.id !== 'string' || typeof endpoint.secret !== 'string') {
-                    throw new errors_1.CliError('Referalli answered without a webhook endpoint id and secret.');
+                if (!sync.secret) {
+                    syncEndpoint = sync.id;
+                    syncScope = [program];
                 }
-                try {
-                    await http.patch('/v1/instance/referrals', { inbound_secret: endpoint.secret, inbound_endpoint_id: endpoint.id });
-                    syncEndpoint = endpoint.id;
+                else {
+                    try {
+                        await http.patch('/v1/instance/referrals', { inbound_secret: sync.secret, inbound_endpoint_id: sync.id });
+                        syncEndpoint = sync.id;
+                        syncScope = [program];
+                    }
+                    catch (err) {
+                        const kept = (0, secrets_1.deliverSecret)({
+                            io: out,
+                            env: ctx.env,
+                            product,
+                            fileName: `referalli-webhook-${sync.id}.env`,
+                            entries: { REFERALLI_WEBHOOK_ENDPOINT_ID: sync.id, REFERALLI_WEBHOOK_SECRET: sync.secret },
+                            label: 'The Referalli webhook secret (not saved on Atlas)',
+                            force: v.force === true,
+                            comment: `Referalli webhook ${sync.id}: saving it on the Atlas instance failed. Paste it as the inbound secret in Users → Referrals.`,
+                        });
+                        ctx.io.err(`atlas: warning: the webhook ${sync.id} was registered on Referalli, but saving its secret failed (${err instanceof Error ? err.message : String(err)}).${kept.path ? ` It is in ${kept.path}.` : ''}`);
+                    }
                 }
-                catch (err) {
-                    const kept = (0, secrets_1.deliverSecret)({
-                        io: out,
-                        env: ctx.env,
-                        product,
-                        fileName: `referalli-webhook-${endpoint.id}.env`,
-                        entries: { REFERALLI_WEBHOOK_ENDPOINT_ID: endpoint.id, REFERALLI_WEBHOOK_SECRET: endpoint.secret },
-                        label: 'The Referalli webhook secret (not saved on Atlas)',
-                        force: v.force === true,
-                        comment: `Referalli webhook ${endpoint.id}: saving it on the Atlas instance failed. Paste it as the inbound secret in Users → Referrals.`,
-                    });
-                    ctx.io.err(`atlas: warning: the webhook ${endpoint.id} was registered on Referalli, but saving its secret failed (${err instanceof Error ? err.message : String(err)}).${kept.path ? ` It is in ${kept.path}.` : ''}`);
+                if (sync.duplicates.length) {
+                    ctx.io.err(`atlas: warning: Referalli has more webhook endpoints for this instance (${sync.duplicates.join(', ')}). Atlas cannot verify their deliveries; delete them on Referalli.`);
                 }
             }
             catch (err) {
@@ -432,21 +564,38 @@ async function connect(ctx, args) {
                 ctx.io.err(`atlas: warning: ${err.message} Referral changes on Referalli won't reach Atlas until it is registered (see the docs).`);
             }
         }
+        // What connect could not set: the exact settings call that finishes it.
+        const leftToDo = {};
+        if (!(trackingToken ?? current.tracking_token))
+            leftToDo.tracking_token = '<your Referalli tracking token (tk_…), from GET /v1/org on Referalli>';
+        if (!(linkTemplate ?? current.link_template))
+            leftToDo.link_template = 'https://<your Referalli link host>/go/<tracking token>/{code}';
         summary = {
             provider: 'referalli',
             instance_id: instance.id,
             endpoint_url: baseUrl,
-            connection_id: created.id,
+            connection_id: connectionId,
+            reused: Boolean(existing),
             program_id: program,
-            tracking_token: trackingToken,
+            tracking_token: trackingToken ?? current.tracking_token ?? null,
+            link_template: linkTemplate ?? current.link_template ?? null,
             livemode: mode.known ? mode.live : null,
             signature_v2_required: signatureV2,
             sync_endpoint_id: syncEndpoint,
+            sync_program_ids: syncScope,
+            left_to_do: Object.keys(leftToDo).length ? { method: 'PATCH', path: '/v1/instance/referrals', body: leftToDo } : null,
         };
         if (!json) {
-            out.out(`Created Referalli connection ${created.id} for instance ${instance.id} and saved it (the secret was not printed).`);
+            out.out(existing
+                ? `Reused Referalli connection ${connectionId} for instance ${instance.id} and updated it${secret ? ' (new secret saved, not printed)' : ''}.`
+                : `Created Referalli connection ${connectionId} for instance ${instance.id} and saved it (the secret was not printed).`);
             if (syncEndpoint)
-                out.out(`Referral changes on Referalli sync back to Atlas (webhook ${syncEndpoint}).`);
+                out.out(`Referral changes on Referalli sync back to Atlas (webhook ${syncEndpoint}, program ${program} only).`);
+            if (Object.keys(leftToDo).length) {
+                out.out(`Left to do: ${Object.keys(leftToDo).join(' and ')} could not be read from Referalli. Set them with PATCH /v1/instance/referrals:`);
+                out.out(`  ${JSON.stringify(leftToDo)}`);
+                out.out('  (or run this again with --tracking-token <tk_…> and --link-template <url with {code}>)');
+            }
         }
     }
     else {
@@ -527,27 +676,40 @@ async function backfill(ctx, args) {
     if (!since || !/^\d{4}-\d{2}-\d{2}(T.*)?$/.test(since) || Number.isNaN(Date.parse(since))) {
         throw new errors_1.CliError('referrals backfill needs --since <YYYY-MM-DD>.');
     }
-    const mapFile = (0, args_1.str)(v, 'map');
-    let codes;
-    if (mapFile) {
+    const readMap = (flag, file) => {
+        if (!file)
+            return undefined;
         let text;
         try {
-            text = ctx.readFile(mapFile === '-' ? '/dev/stdin' : mapFile);
+            text = ctx.readFile(file === '-' ? '/dev/stdin' : file);
         }
         catch {
-            throw new errors_1.CliError(`Could not read ${mapFile}.`);
+            throw new errors_1.CliError(`Could not read ${file}.`);
         }
-        codes = parseCodeCsv(text);
-    }
-    const metadataPath = (0, args_1.str)(v, 'metadata-path');
-    if (metadataPath && !/^(public|private|unsafe)_metadata(\.[A-Za-z0-9_-]{1,64}){1,4}$/.test(metadataPath)) {
-        throw new errors_1.CliError(`--metadata-path must look like public_metadata.referral_code, got '${metadataPath}'.`);
-    }
+        return parseCodeCsv(text, `--${flag}`);
+    };
+    const checkPath = (flag) => {
+        const p = (0, args_1.str)(v, flag);
+        if (p && !/^(public|private|unsafe)_metadata(\.[A-Za-z0-9_-]{1,64}){1,4}$/.test(p)) {
+            throw new errors_1.CliError(`--${flag} must look like public_metadata.referral_code, got '${p}'.`);
+        }
+        return p;
+    };
+    const mapFile = (0, args_1.str)(v, 'map');
+    const ownMapFile = (0, args_1.str)(v, 'own-map');
+    if (mapFile === '-' && ownMapFile === '-')
+        throw new errors_1.CliError('Only one of --map and --own-map can read stdin.');
+    const codes = readMap('map', mapFile);
+    const ownCodes = readMap('own-map', ownMapFile);
+    const metadataPath = checkPath('metadata-path');
+    const ownMetadataPath = checkPath('own-metadata-path');
     const http = (0, project_1.httpFor)(ctx, (0, project_commands_1.instanceCredential)(ctx, args));
     let job = await http.post('/v1/instance/referrals/backfill', {
         since,
         ...(codes && Object.keys(codes).length ? { codes } : {}),
         ...(metadataPath ? { code_metadata_path: metadataPath } : {}),
+        ...(ownCodes && Object.keys(ownCodes).length ? { own_codes: ownCodes } : {}),
+        ...(ownMetadataPath ? { own_code_metadata_path: ownMetadataPath } : {}),
     });
     const running = (s) => s === 'queued' || s === 'running' || s === 'pending';
     if (v.wait === true) {
@@ -569,6 +731,13 @@ async function backfill(ctx, args) {
         ctx.io.out(`Backfill ${job.id}: ${job.status}${counts.length ? ` (${counts.join(', ')})` : ''}.`);
         if (codes)
             ctx.io.out(`${Object.keys(codes).length} code(s) read from ${mapFile}.`);
+        if (ownCodes)
+            ctx.io.out(`${Object.keys(ownCodes).length} own code(s) read from ${ownMapFile}.`);
+        if (typeof job.own_codes_set === 'number' && (ownCodes || ownMetadataPath))
+            ctx.io.out(`${job.own_codes_set} own code(s) kept.`);
+        if (job.own_codes_taken?.length) {
+            ctx.io.err(`atlas: ${job.own_codes_taken.length} own code(s) already belong to another user, not set: ${job.own_codes_taken.join(', ')}`);
+        }
         if (running(job.status) && v.wait !== true)
             ctx.io.out("Add --wait to follow it, or watch the delivery log in the dashboard.");
         if (job.truncated && job.next_since) {
@@ -579,6 +748,24 @@ async function backfill(ctx, args) {
     }
     return job.status === 'failed' || (job.calls?.failed ?? 0) > 0 ? 1 : 0;
 }
+async function resync(ctx, args) {
+    const userId = args.positionals[2];
+    if (!userId)
+        throw new errors_1.CliError('referrals resync needs a user id: atlas referrals resync <user_id> [--dry-run].');
+    const http = (0, project_1.httpFor)(ctx, (0, project_commands_1.instanceCredential)(ctx, args));
+    const res = await http.post(`/v1/users/${encodeURIComponent(userId)}/referral/resync${args.values['dry-run'] === true ? '?dry_run=true' : ''}`, {});
+    if ((0, shared_1.wantsJson)(args.values))
+        (0, output_1.printJson)(ctx.io, res);
+    else {
+        ctx.io.out(`Re-reported ${res.user_id}: call ${res.call_id ?? '-'} ${res.call_status ?? 'not sent'}${args.values['dry-run'] === true ? ' (dry run, nothing sent)' : ''}.`);
+        if (res.error)
+            ctx.io.err(`atlas: ${res.error}`);
+        const code = res.referral?.referral_code;
+        if (code)
+            ctx.io.out(`Referral code ${code}${res.referral?.referral_link ? `, link ${res.referral.referral_link}` : ''}.`);
+    }
+    return res.call_status === 'failed' ? 1 : 0;
+}
 const FINDING_COLUMNS = [
     { header: 'SEVERITY', get: (f) => f.severity },
     { header: 'CODE', get: (f) => f.code },
@@ -596,8 +783,47 @@ async function status(ctx, args) {
         if (!(err instanceof backend_1.AtlasApiError))
             throw err;
     }
+    // The sync webhook's program scope lives on Referalli: read it when a merchant key is given (never required).
+    const inbound = settings.inbound;
+    let webhook = null;
+    const key = settings.provider === 'referalli' && settings.endpoint_url && inbound?.endpoint_id ? referalliKeyFrom(ctx, args.values) : undefined;
+    if (key && settings.endpoint_url && inbound?.endpoint_id) {
+        webhook = await referalliTry(ctx, {
+            baseUrl: settings.endpoint_url,
+            key,
+            path: `/v1/webhook-endpoints/${encodeURIComponent(inbound.endpoint_id)}`,
+            what: 'read the referral event webhook',
+        });
+    }
+    const scope = webhookScope(webhook);
     if ((0, shared_1.wantsJson)(args.values)) {
-        (0, output_1.printJson)(ctx.io, { settings, findings });
+        const c = settings.connection ?? null;
+        (0, output_1.printJson)(ctx.io, {
+            // Flat, stable fields for scripts; `settings` is the raw GET /v1/instance/referrals answer.
+            status: {
+                enabled: settings.enabled,
+                provider: settings.provider,
+                connection_id: settings.connection_id,
+                program_id: settings.program_id,
+                signing_secret_set: settings.signing_secret_set,
+                webhook: {
+                    endpoint_id: inbound?.endpoint_id ?? null,
+                    url: inbound?.url ?? null,
+                    secret_set: inbound?.secret_set ?? false,
+                    // program: limited to program_ids; all_programs: every program in the organization; unknown: no merchant key given.
+                    scope: inbound?.endpoint_id ? scope.scope : null,
+                    program_ids: scope.program_ids,
+                },
+                link_template_set: Boolean(settings.link_template),
+                tracking_token_set: Boolean(settings.tracking_token),
+                last_sync: inbound?.last_event ?? null,
+                last_test: c?.last_test ?? null,
+                last_success_at: c?.last_success_at ?? null,
+                missing: settings.missing ?? [],
+            },
+            settings,
+            findings,
+        });
         return findings.some((f) => f.severity === 'error') ? 1 : 0;
     }
     const c = settings.connection ?? null;
@@ -608,6 +834,8 @@ async function status(ctx, args) {
         `Connection ID:        ${settings.connection_id ?? '(not set)'}`,
         `Program ID:           ${settings.program_id ?? '(not set)'}`,
         `Signing secret:       ${settings.signing_secret_set ? 'set' : 'not set'}`,
+        `Link template:        ${settings.link_template ?? '(not set)'}`,
+        `Tracking token:       ${settings.tracking_token ?? '(not set)'}`,
     ];
     if (settings.forward_lifecycle !== undefined)
         lines.push(`Forward lifecycle:    ${settings.forward_lifecycle ? 'on' : 'off'}`);
@@ -618,11 +846,13 @@ async function status(ctx, args) {
     }
     if (c)
         lines.push(`Failed (7 days):      ${c.failed_calls_7d ?? 0}    Retrying: ${c.retrying_calls ?? 0}`);
-    const inbound = settings.inbound;
     if (inbound?.url) {
         // Referalli needs its own webhook secret; the Atlas protocol falls back to the signing secret.
         const syncing = inbound.secret_set || (settings.provider === 'webhook' && settings.signing_secret_set);
         lines.push(`Two-way sync:         ${syncing ? 'on' : 'off (no inbound secret)'}${inbound.endpoint_id ? ` (webhook ${inbound.endpoint_id})` : ''}`);
+        if (scope.scope !== 'unknown') {
+            lines.push(`Webhook scope:        ${scope.program_ids ? `program ${scope.program_ids.join(', ')}` : 'every program (re-run connect to limit it)'}`);
+        }
         lines.push(`Inbound URL:          ${inbound.url}`);
         if (inbound.last_event) {
             lines.push(`Last event:           ${inbound.last_event.type} → ${inbound.last_event.outcome} at ${new Date(inbound.last_event.at).toISOString()}`);
@@ -713,14 +943,16 @@ async function referrals(ctx, args) {
             return connect(ctx, args);
         case 'backfill':
             return backfill(ctx, args);
+        case 'resync':
+            return resync(ctx, args);
         case 'status':
             return status(ctx, args);
         case 'conformance':
             return conformance(ctx, args);
         default:
             throw new errors_1.CliError(sub
-                ? `Unknown subcommand 'referrals ${sub}'. Try: connect, backfill, status, conformance.`
-                : 'referrals needs a subcommand: connect, backfill, status, conformance.');
+                ? `Unknown subcommand 'referrals ${sub}'. Try: connect, backfill, resync, status, conformance.`
+                : 'referrals needs a subcommand: connect, backfill, resync, status, conformance.');
     }
 }
 //# sourceMappingURL=referrals.js.map