@referalli/cli 0.4.8 → 0.4.10

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,19 @@ 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.10 - 2026-11-11
9
+
10
+ ### Fixed
11
+ - `doctor --program`: when several org-wide billing connections exist (one per product in a shared org), a broken one is ⚠ as long as another works, with the fix to limit it to its programs. It still fails when it's the only connection the program could use.
12
+
13
+ ## 0.4.9 - 2026-11-11
14
+
15
+ ### Changed
16
+ - `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.
17
+ - The `tracking.consent` check uses the program's own `trackingConsent`, and never suggests an org-wide change for a program that overrides it.
18
+ - Auth connections show the last refused sign-up call.
19
+ - `keys list` shows each key's programs.
20
+
8
21
  ## 0.4.8 - 2026-11-11
9
22
 
10
23
  ### 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,39 @@ 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
+ // Scoped: a failing org-wide connection fails the run only when the program has nothing else that works
94
+ // (several products often share one org, each with its own org-wide connection).
95
+ const working = conns.filter((c) => billingCheck(c).status !== 'fail').length;
85
96
  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}` };
97
+ const check = billingCheck(c);
98
+ if (!scope || c.programIds?.length || working === 0 || check.status !== 'fail')
99
+ return check;
100
+ const own = all.some((o) => scope.some((p) => o.programIds?.includes(p)));
101
+ const why = own ? 'not used by this program: it has its own billing connection' : 'this program has another working connection';
102
+ return { ...unusedOrgWide(check, why), fix: `if it belongs to other programs, limit it: PATCH /v1/billing/connections/${c.id} {"programIds":["prg_…"]}` };
94
103
  });
95
104
  }
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) => {
105
+ function billingCheck(c) {
106
+ const id = `billing.${c.id}`;
107
+ const label = `${c.provider} connection "${c.name}"`;
108
+ if (c.status === 'awaiting_secret') {
109
+ return { id, status: 'fail', message: `${label}: provider secret not set, every event is refused`, fix: `PUT /v1/billing/connections/${c.id}/secret {"webhookSecret":"…"}` };
110
+ }
111
+ if (c.status === 'paused')
112
+ return { id, status: 'warn', message: `${label} is paused`, fix: `PATCH /v1/billing/connections/${c.id} {"status":"active"}` };
113
+ return { id, status: 'ok', message: `${label} is ${c.status}` };
114
+ }
115
+ async function authChecks(client, now, programs, scope, tally) {
116
+ const all = rows(await client.request('GET', '/v1/auth/connections'));
117
+ const isOutside = (c) => outside(scope, c.programId ? [c.programId] : null);
118
+ const conns = all.filter((c) => !isOutside(c));
119
+ const check = (c) => {
99
120
  // Receipt time when the API has it: a late-filed sign-up must not look like a fresh one (R-30).
100
121
  const lastSignupAt = c.lastSignupReceivedAt ?? c.lastSignupAt;
101
122
  const id = `auth.${c.id}`;
@@ -111,14 +132,18 @@ async function authChecks(client, now, programs, scope) {
111
132
  }
112
133
  // Protocol connections (Atlas, custom) can't be pinged with an API key: when it last filed a sign-up says it's wired.
113
134
  // undefined: an API from before lastSignupAt, nothing to say.
135
+ const rejected = c.lastRejectedAt ? `; last refused call ${c.lastRejectedAt}${c.lastRejectedReason ? ` (${c.lastRejectedReason})` : ''}` : '';
114
136
  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}` };
137
+ 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
138
  }
117
139
  if (lastSignupAt && now.getTime() - new Date(lastSignupAt).getTime() > 30 * DAY) {
118
140
  return { id, status: 'warn', message: `${label} is ${c.status}; no sign-up since ${lastSignupAt}`, fix: `check the platform still calls connection ${c.id}` };
119
141
  }
120
- return { id, status: 'ok', message: `${label} is ${c.status}${lastSignupAt ? `; last sign-up ${lastSignupAt}` : ''}` };
121
- });
142
+ return { id, status: 'ok', message: `${label} is ${c.status}${lastSignupAt ? `; last sign-up ${lastSignupAt}` : ''}${rejected}` };
143
+ };
144
+ tally.other += all.filter((c) => isOutside(c) && check(c).status !== 'ok').length;
145
+ const usesOrgWide = !scope || scope.some((p) => !all.some((c) => c.programId === p));
146
+ 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
147
  // R-06: the Atlas referral panel mints widget tokens, which needs the program's widget set up.
123
148
  for (const c of conns.filter((x) => x.provider === 'atlas' && x.status === 'active')) {
124
149
  const p = programs.find((x) => x.id === c.programId);
@@ -140,7 +165,33 @@ async function authChecks(client, now, programs, scope) {
140
165
  }
141
166
  return out;
142
167
  }
143
- async function trackingCheck(client, env) {
168
+ /**
169
+ * RF-2: the consent mode aff.js serves each program: its own trackingConsent, else the org's.
170
+ * Scoped: the scope's programs. Unscoped: the org's mode, naming the programs that override it.
171
+ */
172
+ function consentCheck(c, programs, scope) {
173
+ const id = 'tracking.consent';
174
+ const overrides = c.programOverrides ?? [];
175
+ const own = (p) => p.trackingConsent ?? overrides.find((o) => o.programId === p.id)?.mode ?? null;
176
+ const why = 'aff.js stores the referral before the visitor chooses';
177
+ if (scope && programs.length > 0) {
178
+ const none = programs.filter((p) => (own(p) ?? c.mode) === 'none');
179
+ if (none.length > 0) {
180
+ const fixes = none.map((p) => (own(p) ? `PATCH /v1/programs/${p.id} {"trackingConsent":"auto"}` : null));
181
+ const fix = [...new Set(fixes.map((f) => f ?? `PUT /v1/org/tracking-consent {"mode":"auto"} (or /settings → Install)`))].join('; ');
182
+ return [{ id, status: 'warn', message: `tracking consent is 'none' for ${none.map((p) => `"${p.name}"`).join(', ')}: ${why}`, fix }];
183
+ }
184
+ const modes = programs.map((p) => (own(p) ? `uses ${own(p)}` : `uses the org's mode, ${c.mode}`));
185
+ return [{ id, status: 'ok', message: programs.length === 1 ? `program ${modes[0]}` : programs.map((p, i) => `"${p.name}" ${modes[i]}`).join('; ') }];
186
+ }
187
+ const listed = overrides.length ? `; programs with their own mode: ${overrides.map((o) => `"${o.programName}" ${o.mode}`).join(', ')}` : '';
188
+ // Every active program overrides 'none': the org's mode reaches nobody, so nothing to change org-wide.
189
+ const covered = programs.length > 0 && programs.every((p) => own(p));
190
+ return c.mode === 'none' && !covered
191
+ ? [{ id, status: 'warn', message: `tracking consent is 'none': ${why}${listed}`, fix: `PUT /v1/org/tracking-consent {"mode":"auto"} (or /settings → Install)` }]
192
+ : [{ id, status: 'ok', message: `tracking consent: ${c.mode}${listed}` }];
193
+ }
194
+ async function trackingCheck(client, env, programs, scope) {
144
195
  const org = await client.request('GET', '/v1/org');
145
196
  const out = [];
146
197
  try {
@@ -154,12 +205,7 @@ async function trackingCheck(client, env) {
154
205
  }
155
206
  // Consent mode `none` (orgs from before consent support start there): aff.js stores the referral before the visitor chooses.
156
207
  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
- })));
208
+ out.push(...(await guard('tracking.consent', '/settings → Install', async () => consentCheck(await client.request('GET', '/v1/org/tracking-consent'), programs, scope))));
163
209
  }
164
210
  // The token the product is configured with (run doctor with the app's env) must be this mode's.
165
211
  const name = env.REFERALLI_TRACKING_TOKEN ? 'REFERALLI_TRACKING_TOKEN' : env.NEXT_PUBLIC_REFERALLI_TRACKING_TOKEN ? 'NEXT_PUBLIC_REFERALLI_TRACKING_TOKEN' : null;
@@ -187,9 +233,13 @@ async function trackingCheck(client, env) {
187
233
  * Every GET /v1/integration-health check, as `health.<id>`. A failed one is ✗ when the API marks it
188
234
  * `severity: "error"` (or critical), else ⚠. Scoped, never ✗: it may be about another program.
189
235
  */
190
- async function healthChecks(client, scope) {
236
+ async function healthChecks(client, scope, billing, tally) {
191
237
  const res = await client.request('GET', '/v1/integration-health');
192
- return res.checks.map((h) => {
238
+ // RF-1: a check about another program's billing connection (billing.<provider>.<id>) goes into the tally.
239
+ const others = new Set(billing.filter((c) => outside(scope, c.programIds)).map((c) => c.id));
240
+ const theirs = (h) => h.id.split('.').some((part) => others.has(part));
241
+ tally.other += res.checks.filter((h) => !h.ok && theirs(h)).length;
242
+ return res.checks.filter((h) => !theirs(h)).map((h) => {
193
243
  const id = `health.${h.id}`;
194
244
  if (h.ok)
195
245
  return { id, status: 'ok', message: h.detail };
@@ -373,20 +423,23 @@ export async function runDoctor(io, client, flags, now = new Date()) {
373
423
  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
424
  }
375
425
  });
426
+ const tally = { other: 0 };
376
427
  let programs = [];
377
428
  const programChecks = await guard('programs', undefined, async () => {
378
429
  programs = await loadPrograms(client, scope);
379
430
  return termsChecks(client, programs);
380
431
  });
432
+ // Read once: the billing checks and the health checks' tally both need it (health: empty if it can't be read; billing says why).
433
+ const billingList = client.request('GET', '/v1/billing/connections').then(rows);
381
434
  const checks = [
382
435
  ...key,
383
436
  ...programChecks,
384
437
  ...(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)),
438
+ guard('webhooks', undefined, () => webhookChecks(client, scope, tally)),
439
+ guard('billing', undefined, async () => billingChecks(scope, await billingList, tally)),
440
+ orgWide('auth', () => authChecks(client, now, programs, scope, tally)),
441
+ orgWide('tracking', () => trackingCheck(client, io.env, programs, scope)),
442
+ orgWide('health', async () => healthChecks(client, scope, await billingList.catch(() => []), tally)),
390
443
  orgWide('payouts', () => payoutChecks(client, programs, apiKey?.livemode !== false)),
391
444
  orgWide('email', () => emailChecks(client, programs)),
392
445
  guard('commissions', undefined, () => unpaidChecks(client, programs, now)),
@@ -394,6 +447,10 @@ export async function runDoctor(io, client, flags, now = new Date()) {
394
447
  ...(flags.e2e && program ? [guard('e2e', undefined, () => e2eChecks(client, program, fetchFn, io.env))] : []),
395
448
  ])).flat(),
396
449
  ];
450
+ if (tally.other > 0) {
451
+ const how = program ? 'run without --program (and REFERALLI_PROGRAM_ID)' : 'run with an org-wide key';
452
+ checks.push({ id: 'scope.other', status: 'info', message: `${tally.other} issue(s) in other programs; ${how} to see them` });
453
+ }
397
454
  printChecks((l) => io.out(l), checks, flags.json);
398
455
  return checks.some((c) => c.status === 'fail') ? 1 : 0;
399
456
  }
@@ -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.10";
@@ -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.10';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@referalli/cli",
3
- "version": "0.4.8",
3
+ "version": "0.4.10",
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",