@referalli/cli 0.4.8 → 0.4.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,14 @@ All notable changes to `@referalli/cli` are recorded here. The format follows
5
5
  [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Before 1.0, a minor
6
6
  bump may include breaking changes; they are called out under **Changed**.
7
7
 
8
+ ## 0.4.9 - 2026-11-11
9
+
10
+ ### Changed
11
+ - `doctor --program` only fails on the program's own resources. Other programs' problems become one line (`scope.other`), and an org-wide connection the program doesn't use is a warning.
12
+ - The `tracking.consent` check uses the program's own `trackingConsent`, and never suggests an org-wide change for a program that overrides it.
13
+ - Auth connections show the last refused sign-up call.
14
+ - `keys list` shows each key's programs.
15
+
8
16
  ## 0.4.8 - 2026-11-11
9
17
 
10
18
  ### Added
@@ -375,7 +375,7 @@ export async function keys(io, sub, arg, flags) {
375
375
  const rows = Array.isArray(res) ? res : res.data;
376
376
  for (const k of rows) {
377
377
  const state = k.revokedAt ? 'revoked' : k.expired ? 'expired' : 'active';
378
- io.out([k.id, k.livemode ? 'live' : 'test', state, `${k.prefix}…`, k.name, k.owner ?? '-', k.scopes.join(','), k.lastUsedAt ? `used ${k.lastUsedAt}` : 'never used']
378
+ io.out([k.id, k.livemode ? 'live' : 'test', state, `${k.prefix}…`, k.name, k.owner ?? '-', k.scopes.join(','), k.programIds?.length ? `programs ${k.programIds.join(',')}` : 'all programs', k.lastUsedAt ? `used ${k.lastUsedAt}` : 'never used']
379
379
  .join(' '));
380
380
  }
381
381
  return 0;
@@ -48,6 +48,11 @@ async function loadPrograms(client, scope) {
48
48
  }
49
49
  /** Outside the scope: limited to programs, none of them in it. Org-wide (null) resources concern every program. */
50
50
  const outside = (scope, programIds) => Boolean(scope && programIds && programIds.length > 0 && !programIds.some((id) => scope.includes(id)));
51
+ /**
52
+ * RF-1: a scoped run meets an org-wide resource the scoped programs don't use (each has one of its own):
53
+ * its failure is ⚠ with a note, never ✗.
54
+ */
55
+ const unusedOrgWide = (c, note) => c.status === 'fail' ? { ...c, status: 'warn', message: `${c.message} (org-wide, ${note})` } : c;
51
56
  async function termsChecks(client, programs) {
52
57
  if (programs.length === 0)
53
58
  return [{ id: 'programs', status: 'warn', message: 'no active programs', fix: '/programs' }];
@@ -63,8 +68,10 @@ async function termsChecks(client, programs) {
63
68
  }
64
69
  }))).then((all) => all.flat());
65
70
  }
66
- async function webhookChecks(client, scope) {
67
- const endpoints = rows(await client.request('GET', '/v1/webhook-endpoints')).filter((e) => !outside(scope, e.programIds));
71
+ async function webhookChecks(client, scope, tally) {
72
+ const all = rows(await client.request('GET', '/v1/webhook-endpoints'));
73
+ tally.other += all.filter((e) => outside(scope, e.programIds) && e.health !== 'healthy').length;
74
+ const endpoints = all.filter((e) => !outside(scope, e.programIds));
68
75
  if (endpoints.length === 0)
69
76
  return [{ id: 'webhooks', status: 'ok', message: 'no webhook endpoints' }];
70
77
  return endpoints.map((e) => {
@@ -77,25 +84,34 @@ async function webhookChecks(client, scope) {
77
84
  return { id, status: 'warn', message: `${e.url} is ${why}`, fix };
78
85
  });
79
86
  }
80
- async function billingChecks(client, scope) {
81
- const conns = rows(await client.request('GET', '/v1/billing/connections')).filter((c) => !outside(scope, c.programIds));
87
+ function billingChecks(scope, all, tally) {
88
+ const conns = all.filter((c) => !outside(scope, c.programIds));
89
+ tally.other += all.filter((c) => outside(scope, c.programIds) && billingCheck(c).status !== 'ok').length;
82
90
  if (conns.length === 0) {
83
91
  return [{ id: 'billing', status: 'warn', message: "no billing connection: payments won't earn commission", fix: 'POST /v1/billing/connections' }];
84
92
  }
93
+ // An org-wide connection matters to the scope only when one of its programs has no connection of its own.
94
+ const usesOrgWide = !scope || scope.some((p) => !all.some((c) => c.programIds?.includes(p)));
85
95
  return conns.map((c) => {
86
- const id = `billing.${c.id}`;
87
- const label = `${c.provider} connection "${c.name}"`;
88
- if (c.status === 'awaiting_secret') {
89
- return { id, status: 'fail', message: `${label}: provider secret not set, every event is refused`, fix: `PUT /v1/billing/connections/${c.id}/secret {"webhookSecret":"…"}` };
90
- }
91
- if (c.status === 'paused')
92
- return { id, status: 'warn', message: `${label} is paused`, fix: `PATCH /v1/billing/connections/${c.id} {"status":"active"}` };
93
- return { id, status: 'ok', message: `${label} is ${c.status}` };
96
+ const check = billingCheck(c);
97
+ return usesOrgWide || c.programIds?.length ? check : unusedOrgWide(check, 'not used by this program: it has its own billing connection');
94
98
  });
95
99
  }
96
- async function authChecks(client, now, programs, scope) {
97
- const conns = rows(await client.request('GET', '/v1/auth/connections')).filter((c) => !scope || !c.programId || scope.includes(c.programId));
98
- const out = conns.map((c) => {
100
+ function billingCheck(c) {
101
+ const id = `billing.${c.id}`;
102
+ const label = `${c.provider} connection "${c.name}"`;
103
+ if (c.status === 'awaiting_secret') {
104
+ return { id, status: 'fail', message: `${label}: provider secret not set, every event is refused`, fix: `PUT /v1/billing/connections/${c.id}/secret {"webhookSecret":"…"}` };
105
+ }
106
+ if (c.status === 'paused')
107
+ return { id, status: 'warn', message: `${label} is paused`, fix: `PATCH /v1/billing/connections/${c.id} {"status":"active"}` };
108
+ return { id, status: 'ok', message: `${label} is ${c.status}` };
109
+ }
110
+ async function authChecks(client, now, programs, scope, tally) {
111
+ const all = rows(await client.request('GET', '/v1/auth/connections'));
112
+ const isOutside = (c) => outside(scope, c.programId ? [c.programId] : null);
113
+ const conns = all.filter((c) => !isOutside(c));
114
+ const check = (c) => {
99
115
  // Receipt time when the API has it: a late-filed sign-up must not look like a fresh one (R-30).
100
116
  const lastSignupAt = c.lastSignupReceivedAt ?? c.lastSignupAt;
101
117
  const id = `auth.${c.id}`;
@@ -111,14 +127,18 @@ async function authChecks(client, now, programs, scope) {
111
127
  }
112
128
  // Protocol connections (Atlas, custom) can't be pinged with an API key: when it last filed a sign-up says it's wired.
113
129
  // undefined: an API from before lastSignupAt, nothing to say.
130
+ const rejected = c.lastRejectedAt ? `; last refused call ${c.lastRejectedAt}${c.lastRejectedReason ? ` (${c.lastRejectedReason})` : ''}` : '';
114
131
  if (lastSignupAt === null) {
115
- return { id, status: 'warn', message: `${label} is ${c.status} but has never filed a sign-up`, fix: `sign up a user in your app (test sign-ups don't count) and check the platform calls connection ${c.id}` };
132
+ return { id, status: 'warn', message: `${label} is ${c.status} but has never filed a sign-up${rejected}`, fix: `sign up a user in your app (test sign-ups don't count) and check the platform calls connection ${c.id}` };
116
133
  }
117
134
  if (lastSignupAt && now.getTime() - new Date(lastSignupAt).getTime() > 30 * DAY) {
118
135
  return { id, status: 'warn', message: `${label} is ${c.status}; no sign-up since ${lastSignupAt}`, fix: `check the platform still calls connection ${c.id}` };
119
136
  }
120
- return { id, status: 'ok', message: `${label} is ${c.status}${lastSignupAt ? `; last sign-up ${lastSignupAt}` : ''}` };
121
- });
137
+ return { id, status: 'ok', message: `${label} is ${c.status}${lastSignupAt ? `; last sign-up ${lastSignupAt}` : ''}${rejected}` };
138
+ };
139
+ tally.other += all.filter((c) => isOutside(c) && check(c).status !== 'ok').length;
140
+ const usesOrgWide = !scope || scope.some((p) => !all.some((c) => c.programId === p));
141
+ const out = conns.map((c) => (usesOrgWide || c.programId ? check(c) : unusedOrgWide(check(c), 'not used by this program: it has its own auth connection')));
122
142
  // R-06: the Atlas referral panel mints widget tokens, which needs the program's widget set up.
123
143
  for (const c of conns.filter((x) => x.provider === 'atlas' && x.status === 'active')) {
124
144
  const p = programs.find((x) => x.id === c.programId);
@@ -140,7 +160,33 @@ async function authChecks(client, now, programs, scope) {
140
160
  }
141
161
  return out;
142
162
  }
143
- async function trackingCheck(client, env) {
163
+ /**
164
+ * RF-2: the consent mode aff.js serves each program: its own trackingConsent, else the org's.
165
+ * Scoped: the scope's programs. Unscoped: the org's mode, naming the programs that override it.
166
+ */
167
+ function consentCheck(c, programs, scope) {
168
+ const id = 'tracking.consent';
169
+ const overrides = c.programOverrides ?? [];
170
+ const own = (p) => p.trackingConsent ?? overrides.find((o) => o.programId === p.id)?.mode ?? null;
171
+ const why = 'aff.js stores the referral before the visitor chooses';
172
+ if (scope && programs.length > 0) {
173
+ const none = programs.filter((p) => (own(p) ?? c.mode) === 'none');
174
+ if (none.length > 0) {
175
+ const fixes = none.map((p) => (own(p) ? `PATCH /v1/programs/${p.id} {"trackingConsent":"auto"}` : null));
176
+ const fix = [...new Set(fixes.map((f) => f ?? `PUT /v1/org/tracking-consent {"mode":"auto"} (or /settings → Install)`))].join('; ');
177
+ return [{ id, status: 'warn', message: `tracking consent is 'none' for ${none.map((p) => `"${p.name}"`).join(', ')}: ${why}`, fix }];
178
+ }
179
+ const modes = programs.map((p) => (own(p) ? `uses ${own(p)}` : `uses the org's mode, ${c.mode}`));
180
+ return [{ id, status: 'ok', message: programs.length === 1 ? `program ${modes[0]}` : programs.map((p, i) => `"${p.name}" ${modes[i]}`).join('; ') }];
181
+ }
182
+ const listed = overrides.length ? `; programs with their own mode: ${overrides.map((o) => `"${o.programName}" ${o.mode}`).join(', ')}` : '';
183
+ // Every active program overrides 'none': the org's mode reaches nobody, so nothing to change org-wide.
184
+ const covered = programs.length > 0 && programs.every((p) => own(p));
185
+ return c.mode === 'none' && !covered
186
+ ? [{ id, status: 'warn', message: `tracking consent is 'none': ${why}${listed}`, fix: `PUT /v1/org/tracking-consent {"mode":"auto"} (or /settings → Install)` }]
187
+ : [{ id, status: 'ok', message: `tracking consent: ${c.mode}${listed}` }];
188
+ }
189
+ async function trackingCheck(client, env, programs, scope) {
144
190
  const org = await client.request('GET', '/v1/org');
145
191
  const out = [];
146
192
  try {
@@ -154,12 +200,7 @@ async function trackingCheck(client, env) {
154
200
  }
155
201
  // Consent mode `none` (orgs from before consent support start there): aff.js stores the referral before the visitor chooses.
156
202
  if (org.livemode !== false) {
157
- out.push(...(await guard('tracking.consent', '/settings → Install', async () => {
158
- const c = await client.request('GET', '/v1/org/tracking-consent');
159
- return c.mode === 'none'
160
- ? [{ id: 'tracking.consent', status: 'warn', message: "tracking consent is 'none': aff.js stores the referral before the visitor chooses", fix: `PUT /v1/org/tracking-consent {"mode":"auto"} (or /settings → Install)` }]
161
- : [{ id: 'tracking.consent', status: 'ok', message: `tracking consent: ${c.mode}` }];
162
- })));
203
+ out.push(...(await guard('tracking.consent', '/settings → Install', async () => consentCheck(await client.request('GET', '/v1/org/tracking-consent'), programs, scope))));
163
204
  }
164
205
  // The token the product is configured with (run doctor with the app's env) must be this mode's.
165
206
  const name = env.REFERALLI_TRACKING_TOKEN ? 'REFERALLI_TRACKING_TOKEN' : env.NEXT_PUBLIC_REFERALLI_TRACKING_TOKEN ? 'NEXT_PUBLIC_REFERALLI_TRACKING_TOKEN' : null;
@@ -187,9 +228,13 @@ async function trackingCheck(client, env) {
187
228
  * Every GET /v1/integration-health check, as `health.<id>`. A failed one is ✗ when the API marks it
188
229
  * `severity: "error"` (or critical), else ⚠. Scoped, never ✗: it may be about another program.
189
230
  */
190
- async function healthChecks(client, scope) {
231
+ async function healthChecks(client, scope, billing, tally) {
191
232
  const res = await client.request('GET', '/v1/integration-health');
192
- return res.checks.map((h) => {
233
+ // RF-1: a check about another program's billing connection (billing.<provider>.<id>) goes into the tally.
234
+ const others = new Set(billing.filter((c) => outside(scope, c.programIds)).map((c) => c.id));
235
+ const theirs = (h) => h.id.split('.').some((part) => others.has(part));
236
+ tally.other += res.checks.filter((h) => !h.ok && theirs(h)).length;
237
+ return res.checks.filter((h) => !theirs(h)).map((h) => {
193
238
  const id = `health.${h.id}`;
194
239
  if (h.ok)
195
240
  return { id, status: 'ok', message: h.detail };
@@ -373,20 +418,23 @@ export async function runDoctor(io, client, flags, now = new Date()) {
373
418
  return [{ id, status: 'warn', message: `skipped, this program-scoped key can't read it (${what})`, fix: `run doctor with an org-wide key (no programs) with ${scope}; read or full also work` }];
374
419
  }
375
420
  });
421
+ const tally = { other: 0 };
376
422
  let programs = [];
377
423
  const programChecks = await guard('programs', undefined, async () => {
378
424
  programs = await loadPrograms(client, scope);
379
425
  return termsChecks(client, programs);
380
426
  });
427
+ // Read once: the billing checks and the health checks' tally both need it (health: empty if it can't be read; billing says why).
428
+ const billingList = client.request('GET', '/v1/billing/connections').then(rows);
381
429
  const checks = [
382
430
  ...key,
383
431
  ...programChecks,
384
432
  ...(await Promise.all([
385
- guard('webhooks', undefined, () => webhookChecks(client, scope)),
386
- guard('billing', undefined, () => billingChecks(client, scope)),
387
- orgWide('auth', () => authChecks(client, now, programs, scope)),
388
- orgWide('tracking', () => trackingCheck(client, io.env)),
389
- orgWide('health', () => healthChecks(client, scope)),
433
+ guard('webhooks', undefined, () => webhookChecks(client, scope, tally)),
434
+ guard('billing', undefined, async () => billingChecks(scope, await billingList, tally)),
435
+ orgWide('auth', () => authChecks(client, now, programs, scope, tally)),
436
+ orgWide('tracking', () => trackingCheck(client, io.env, programs, scope)),
437
+ orgWide('health', async () => healthChecks(client, scope, await billingList.catch(() => []), tally)),
390
438
  orgWide('payouts', () => payoutChecks(client, programs, apiKey?.livemode !== false)),
391
439
  orgWide('email', () => emailChecks(client, programs)),
392
440
  guard('commissions', undefined, () => unpaidChecks(client, programs, now)),
@@ -394,6 +442,10 @@ export async function runDoctor(io, client, flags, now = new Date()) {
394
442
  ...(flags.e2e && program ? [guard('e2e', undefined, () => e2eChecks(client, program, fetchFn, io.env))] : []),
395
443
  ])).flat(),
396
444
  ];
445
+ if (tally.other > 0) {
446
+ const how = program ? 'run without --program (and REFERALLI_PROGRAM_ID)' : 'run with an org-wide key';
447
+ checks.push({ id: 'scope.other', status: 'info', message: `${tally.other} issue(s) in other programs; ${how} to see them` });
448
+ }
397
449
  printChecks((l) => io.out(l), checks, flags.json);
398
450
  return checks.some((c) => c.status === 'fail') ? 1 : 0;
399
451
  }
@@ -1,2 +1,2 @@
1
1
  /** Kept in step with package.json by test/version.test.ts. */
2
- export declare const VERSION = "0.4.8";
2
+ export declare const VERSION = "0.4.9";
@@ -1,2 +1,2 @@
1
1
  /** Kept in step with package.json by test/version.test.ts. */
2
- export const VERSION = '0.4.8';
2
+ export const VERSION = '0.4.9';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@referalli/cli",
3
- "version": "0.4.8",
3
+ "version": "0.4.9",
4
4
  "description": "The Referalli command line: sign in, forward webhooks to localhost, trigger test events, tail events and API logs.",
5
5
  "license": "MIT",
6
6
  "type": "module",