@referalli/cli 0.4.6 → 0.4.7

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,12 @@ 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.7 - 2026-11-07
9
+
10
+ ### Added
11
+
12
+ - `referalli doctor --program <id> --e2e` tests one program from outside: `aff.js` loads, destinations answer, the page includes `aff.js`, a `/go` link redirects with its code, and with a test key a test sign-up and payment are recorded.
13
+
8
14
  ## 0.4.6 - 2026-11-05
9
15
 
10
16
  - `keys create --programs ''` explains itself rather than printing the server's bare 400.
@@ -449,6 +449,8 @@ export async function apply(io, file, flags, planOnly) {
449
449
  export async function doctor(io, flags) {
450
450
  if (flags.strict && typeof flags.scan !== 'string')
451
451
  throw new CliError('--strict goes with --scan <dir>');
452
+ if (flags.e2e && typeof flags.program !== 'string')
453
+ throw new CliError('--e2e tests one program: add --program <id>');
452
454
  if (typeof flags.scan !== 'string')
453
455
  return runDoctor(io, signedIn(io).client, flags);
454
456
  try {
@@ -8,5 +8,5 @@ export interface Check {
8
8
  fix?: string;
9
9
  }
10
10
  export declare function printChecks(out: (line: string) => void, checks: Check[], json: unknown): void;
11
- /** `referalli doctor [--program <id>] [--json]`: read-only health checks. Exit 1 when any check fails. */
11
+ /** `referalli doctor [--program <id>] [--json]`: read-only health checks, plus `--e2e`. Exit 1 when any check fails. */
12
12
  export declare function runDoctor(io: Io, client: Client, flags: Flags, now?: Date): Promise<number>;
@@ -182,7 +182,82 @@ const ORG_WIDE = {
182
182
  auth: { what: 'auth connections, Atlas sign-ups', scope: 'integrations:read or connections:read' },
183
183
  tracking: { what: 'tracking token, consent mode, configured token', scope: 'org:read' },
184
184
  };
185
- /** `referalli doctor [--program <id>] [--json]`: read-only health checks. Exit 1 when any check fails. */
185
+ const OUTSIDE = { method: 'GET', headers: { 'user-agent': 'referalli-doctor-bot' } };
186
+ /** One program from outside, as a visitor would meet it. Runs here, not on the API, so it can't be aimed at our own network. */
187
+ async function e2eChecks(client, programId, fetchFn, env) {
188
+ const out = [];
189
+ const get = (url, redirect = 'follow') => fetchFn(url, { ...OUTSIDE, redirect, signal: AbortSignal.timeout(10_000) });
190
+ const me = await client.request('GET', '/v1/me');
191
+ // A program-scoped key can't read the org; the token is public (it's in every page's script tag), so the env can supply it.
192
+ const trackingToken = await client
193
+ .request('GET', '/v1/org')
194
+ .then((o) => o.trackingToken)
195
+ .catch((err) => {
196
+ if (err instanceof ApiError && err.status === 403)
197
+ return env.REFERALLI_TRACKING_TOKEN ?? env.NEXT_PUBLIC_REFERALLI_TRACKING_TOKEN;
198
+ throw err;
199
+ });
200
+ if (!trackingToken) {
201
+ return [{ id: 'e2e', status: 'warn', message: "skipped: this key can't read the org's tracking token", fix: 'set REFERALLI_TRACKING_TOKEN and run again' }];
202
+ }
203
+ const live = me.apiKey?.livemode !== false;
204
+ const scriptPath = `/t/${encodeURIComponent(trackingToken)}/aff.js`;
205
+ const script = await get(`${client.baseUrl}${scriptPath}`).catch((err) => err);
206
+ out.push(script instanceof Response && script.ok
207
+ ? { id: 'e2e.script', status: 'ok', message: 'aff.js loads' }
208
+ : { id: 'e2e.script', status: 'fail', message: `aff.js didn't load: ${script instanceof Response ? script.status : script.message}` });
209
+ const links = rows(await client.request('GET', `/v1/links?programId=${encodeURIComponent(programId)}&limit=20`));
210
+ // A key without connections:read can still test its links.
211
+ const conns = await client.request('GET', '/v1/auth/connections').then(rows, () => []);
212
+ const link = links.find((l) => l.destinationUrl);
213
+ const destinations = [
214
+ ...new Set([...conns.filter((c) => c.programId === programId).map((c) => c.destinationUrl), link?.destinationUrl]
215
+ .filter((d) => !!d)
216
+ .map((d) => d.replaceAll('{code}', link?.code ?? 'doctor').replaceAll('%7Bcode%7D', link?.code ?? 'doctor'))),
217
+ ];
218
+ if (destinations.length === 0)
219
+ out.push({ id: 'e2e.destination', status: 'warn', message: 'no destination to test: no link or auth connection in this program has one' });
220
+ for (const url of destinations) {
221
+ const res = await get(url).catch((err) => err);
222
+ if (!(res instanceof Response) || !res.ok) {
223
+ out.push({ id: 'e2e.destination', status: 'fail', message: `${url} didn't answer 200: ${res instanceof Response ? res.status : res.message}`, fix: 'update destinationUrl on the link or auth connection' });
224
+ continue;
225
+ }
226
+ out.push({ id: 'e2e.destination', status: 'ok', message: `${url} answers ${res.status}` });
227
+ const html = await res.text();
228
+ out.push(html.includes(scriptPath)
229
+ ? { id: 'e2e.landing', status: 'ok', message: `${url} includes aff.js with this org's token` }
230
+ : { id: 'e2e.landing', status: 'warn', message: `${url} doesn't include aff.js with this org's token in its HTML (a tag manager would load it later)`, fix: '/settings → Install' });
231
+ }
232
+ if (!link) {
233
+ out.push({ id: 'e2e.go', status: 'warn', message: 'no partner link to test in this program' });
234
+ }
235
+ else {
236
+ const res = await get(`${client.baseUrl}/go/${encodeURIComponent(trackingToken)}/${encodeURIComponent(link.code)}`, 'manual').catch((err) => err);
237
+ const to = res instanceof Response ? res.headers.get('location') : null;
238
+ out.push(to?.includes(`via=${encodeURIComponent(link.code)}`)
239
+ ? { id: 'e2e.go', status: 'ok', message: `/go/…/${link.code} redirects with the code` }
240
+ : { id: 'e2e.go', status: 'fail', message: `/go/…/${link.code} didn't redirect with its code: ${res instanceof Response ? res.status : res.message}` });
241
+ }
242
+ out.push({ id: 'e2e.cookie', status: 'warn', message: 'not checked: aff.js sets the cookie in a browser', fix: 'open a /go link in a browser and look for the referral cookie' });
243
+ if (live) {
244
+ out.push({ id: 'e2e.conversion', status: 'warn', message: 'skipped with a live key, so it never earns real commissions', fix: 'run again with a test key and a test-mode program' });
245
+ }
246
+ else if (!link) {
247
+ out.push({ id: 'e2e.conversion', status: 'warn', message: 'skipped: it needs a partner link in this program' });
248
+ }
249
+ else {
250
+ try {
251
+ await client.request('POST', '/v1/sandbox/simulate', { scenario: 'signup_and_pay', programId, code: link.code });
252
+ out.push({ id: 'e2e.conversion', status: 'ok', message: 'test sign-up and payment recorded' });
253
+ }
254
+ catch (err) {
255
+ out.push({ id: 'e2e.conversion', status: 'fail', message: `test sign-up and payment failed: ${reason(err)}` });
256
+ }
257
+ }
258
+ return out;
259
+ }
260
+ /** `referalli doctor [--program <id>] [--json]`: read-only health checks, plus `--e2e`. Exit 1 when any check fails. */
186
261
  export async function runDoctor(io, client, flags, now = new Date()) {
187
262
  const program = typeof flags.program === 'string' ? flags.program : undefined;
188
263
  const key = await guard('key', 'referalli login', () => keyCheck(client, now));
@@ -207,6 +282,7 @@ export async function runDoctor(io, client, flags, now = new Date()) {
207
282
  guard('billing', undefined, () => billingChecks(client)),
208
283
  orgWide('auth', () => authChecks(client, now)),
209
284
  orgWide('tracking', () => trackingCheck(client, io.env)),
285
+ ...(flags.e2e && program ? [guard('e2e', undefined, () => e2eChecks(client, program, io.fetchFn ?? fetch, io.env))] : []),
210
286
  ])).flat(),
211
287
  ];
212
288
  printChecks((l) => io.out(l), checks, flags.json);
@@ -3,6 +3,6 @@ export { readConfig, writeConfig, configPath, type CliConfig } from './config.js
3
3
  export { createClient, ApiError } from './client.js';
4
4
  export type { Io } from './commands.js';
5
5
  export { VERSION } from './version.js';
6
- export declare const HELP = "referalli: the Referalli command line\n\nUsage:\n referalli login [--key rk_\u2026] [--base-url URL] [--no-browser]\n referalli logout\n referalli whoami\n referalli listen [--forward-to URL] [--events topic,topic] [--max-events N]\n referalli trigger <topic> [--data JSON]\n referalli trigger --billing <event> --connection <id> [--data JSON] (test mode; e.g. payment.paid)\n referalli trigger --stripe <event> --connection <id> [--data JSON] (test mode)\n referalli events tail [--events topic,topic] [--since 1h|ISO] [--json] [--max N]\n referalli logs tail [--max N]\n referalli open [docs|dashboard|keys|webhooks|spec|status]\n referalli api <METHOD> <path> [--data JSON] [--secret-file PATH]\n referalli keys create --name NAME [--owner WHO] [--mode both|live|test] [--scopes full,\u2026] [--programs ID,\u2026] [--expires-days N | --expires-at ISO]\n referalli keys list [--owner WHO] [--mode live|test]\n referalli keys revoke <key id> [--pair] [--cascade]\n referalli plan <referalli.yaml> [--check]\n referalli apply <referalli.yaml> [--plan] [--check] [--secret-file PATH]\n referalli doctor [--program <id>] [--json]\n referalli doctor --scan <dir> [--strict] [--json] (old Referally names in a source tree; no key needed)\n referalli partners list --program <id> [--since 7d|ISO] [--json]\n referalli env pull [--mode live|test] (.env lines on stdout; default: the key's mode)\n\nEnvironment:\n REFERALLI_API_KEY use this key instead of the saved login\n REFERALLI_API_URL API base URL (default: the hosted API)\n REFERALLI_CONFIG_DIR where the login is saved (default ~/.config/referalli)\n REFERALLI_TRACKING_TOKEN doctor checks it is this mode's token (or NEXT_PUBLIC_REFERALLI_TRACKING_TOKEN)\n REFERALLY_* spellings of these still work, with a notice";
6
+ export declare const HELP = "referalli: the Referalli command line\n\nUsage:\n referalli login [--key rk_\u2026] [--base-url URL] [--no-browser]\n referalli logout\n referalli whoami\n referalli listen [--forward-to URL] [--events topic,topic] [--max-events N]\n referalli trigger <topic> [--data JSON]\n referalli trigger --billing <event> --connection <id> [--data JSON] (test mode; e.g. payment.paid)\n referalli trigger --stripe <event> --connection <id> [--data JSON] (test mode)\n referalli events tail [--events topic,topic] [--since 1h|ISO] [--json] [--max N]\n referalli logs tail [--max N]\n referalli open [docs|dashboard|keys|webhooks|spec|status]\n referalli api <METHOD> <path> [--data JSON] [--secret-file PATH]\n referalli keys create --name NAME [--owner WHO] [--mode both|live|test] [--scopes full,\u2026] [--programs ID,\u2026] [--expires-days N | --expires-at ISO]\n referalli keys list [--owner WHO] [--mode live|test]\n referalli keys revoke <key id> [--pair] [--cascade]\n referalli plan <referalli.yaml> [--check]\n referalli apply <referalli.yaml> [--plan] [--check] [--secret-file PATH]\n referalli doctor [--program <id>] [--json]\n referalli doctor --program <id> --e2e [--json] (also tests the program from outside; see the docs)\n referalli doctor --scan <dir> [--strict] [--json] (old Referally names in a source tree; no key needed)\n referalli partners list --program <id> [--since 7d|ISO] [--json]\n referalli env pull [--mode live|test] (.env lines on stdout; default: the key's mode)\n\nEnvironment:\n REFERALLI_API_KEY use this key instead of the saved login\n REFERALLI_API_URL API base URL (default: the hosted API)\n REFERALLI_CONFIG_DIR where the login is saved (default ~/.config/referalli)\n REFERALLI_TRACKING_TOKEN doctor checks it is this mode's token (or NEXT_PUBLIC_REFERALLI_TRACKING_TOKEN)\n REFERALLY_* spellings of these still work, with a notice";
7
7
  /** Run one command; returns the process exit code. */
8
8
  export declare function runCli(argv: string[], baseIo: Io): Promise<number>;
package/dist/src/index.js CHANGED
@@ -26,6 +26,7 @@ Usage:
26
26
  referalli plan <referalli.yaml> [--check]
27
27
  referalli apply <referalli.yaml> [--plan] [--check] [--secret-file PATH]
28
28
  referalli doctor [--program <id>] [--json]
29
+ referalli doctor --program <id> --e2e [--json] (also tests the program from outside; see the docs)
29
30
  referalli doctor --scan <dir> [--strict] [--json] (old Referally names in a source tree; no key needed)
30
31
  referalli partners list --program <id> [--since 7d|ISO] [--json]
31
32
  referalli env pull [--mode live|test] (.env lines on stdout; default: the key's mode)
@@ -76,6 +77,7 @@ export async function runCli(argv, baseIo) {
76
77
  json: { type: 'boolean' },
77
78
  scan: { type: 'string' },
78
79
  strict: { type: 'boolean' },
80
+ e2e: { type: 'boolean' },
79
81
  help: { type: 'boolean', short: 'h' },
80
82
  version: { type: 'boolean', short: 'v' },
81
83
  },
@@ -1,2 +1,2 @@
1
1
  /** Kept in step with package.json by test/version.test.ts. */
2
- export declare const VERSION = "0.4.6";
2
+ export declare const VERSION = "0.4.7";
@@ -1,2 +1,2 @@
1
1
  /** Kept in step with package.json by test/version.test.ts. */
2
- export const VERSION = '0.4.6';
2
+ export const VERSION = '0.4.7';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@referalli/cli",
3
- "version": "0.4.6",
3
+ "version": "0.4.7",
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",