@referalli/cli 0.4.0 → 0.4.1

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,11 @@ 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.1 - 2026-11-03
9
+
10
+ - New `env pull [--mode live|test]`: prints one mode's tracking token (`REFERALLI_TRACKING_TOKEN`, `NEXT_PUBLIC_REFERALLI_TRACKING_TOKEN`), aff.js URL, link base and, for the key's own mode, the program id as `.env` lines. Keys are never pulled.
11
+ - `doctor` checks the Atlas adapter: each auth connection's last sign-up (`lastSignupAt`; warns when none or none in 30 days), `auth.atlas` (warns when no auth connection reports sign-ups), and `tracking.configured` (your `REFERALLI_TRACKING_TOKEN` is the token for the key's mode).
12
+
8
13
  ## 0.4.0 - 2026-11-03
9
14
 
10
15
  - `apply` manages `billingConnections`: matched by `name`, with `provider`, `programs` (slugs), `status`, `customerRefMetadataKey`, `filter`, and `stripeKeyEnv` (Stripe one-call connect, create only). Missing connections are created, changed fields PATCHed, none deleted; the new `webhookSecret` goes to `--secret-file` (or is printed once, like other new secrets). `--check` exits 2 on billing connection drift too.
@@ -42,3 +42,9 @@ export declare function api(io: Io, method: string | undefined, path: string | u
42
42
  export declare function apply(io: Io, file: string | undefined, flags: Flags, planOnly: boolean): Promise<number>;
43
43
  /** `referalli doctor [--program <id>] [--json]`. */
44
44
  export declare const doctor: (io: Io, flags: Flags) => Promise<number>;
45
+ /**
46
+ * `referalli env pull [--mode live|test]`: one mode's public ids as .env lines
47
+ * on stdout (`> .env.test`). Default: the key's mode. Program ids differ per
48
+ * mode and are listed only for the key's own; secrets are never pulled.
49
+ */
50
+ export declare function env(io: Io, sub: string | undefined, flags: Flags): Promise<number>;
@@ -438,3 +438,39 @@ export async function apply(io, file, flags, planOnly) {
438
438
  }
439
439
  /** `referalli doctor [--program <id>] [--json]`. */
440
440
  export const doctor = (io, flags) => runDoctor(io, signedIn(io).client, flags);
441
+ /**
442
+ * `referalli env pull [--mode live|test]`: one mode's public ids as .env lines
443
+ * on stdout (`> .env.test`). Default: the key's mode. Program ids differ per
444
+ * mode and are listed only for the key's own; secrets are never pulled.
445
+ */
446
+ export async function env(io, sub, flags) {
447
+ if (sub !== 'pull')
448
+ throw new CliError('Usage: referalli env pull [--mode live|test]');
449
+ const { client } = signedIn(io);
450
+ const t = await client.request('GET', '/v1/org/tracking-tokens');
451
+ const mode = typeof flags.mode === 'string' ? flags.mode : t.mode;
452
+ if (mode !== 'live' && mode !== 'test')
453
+ throw new CliError('--mode is live or test');
454
+ const v = t[mode];
455
+ io.out(`# Referalli ${mode} mode, org ${v.orgId}`);
456
+ io.out(`REFERALLI_TRACKING_TOKEN=${v.trackingToken}`);
457
+ io.out(`NEXT_PUBLIC_REFERALLI_TRACKING_TOKEN=${v.trackingToken}`);
458
+ io.out(`REFERALLI_SCRIPT_URL=${v.scriptUrl}`);
459
+ io.out(`REFERALLI_LINK_BASE_URL=${v.linkBaseUrl}`);
460
+ if (mode !== t.mode) {
461
+ io.out(`# REFERALLI_PROGRAM_ID: ${mode} programs have their own ids; run env pull with a ${mode} key to list them`);
462
+ }
463
+ else {
464
+ const res = await client.request('GET', '/v1/programs');
465
+ const programs = (Array.isArray(res) ? res : res.data).filter((p) => p.status === 'active');
466
+ if (programs.length === 1)
467
+ io.out(`REFERALLI_PROGRAM_ID=${programs[0].id}`);
468
+ else if (programs.length === 0)
469
+ io.out(`# REFERALLI_PROGRAM_ID: no active ${mode} programs yet`);
470
+ else
471
+ for (const p of programs)
472
+ io.out(`# REFERALLI_PROGRAM_ID=${p.id} # ${p.name}`);
473
+ }
474
+ io.out(`# REFERALLI_API_KEY=rk_${mode}_… (secret, not pulled: referalli keys create --name NAME --mode ${mode})`);
475
+ return 0;
476
+ }
@@ -90,12 +90,9 @@ async function billingChecks(client) {
90
90
  return { id, status: 'ok', message: `${label} is ${c.status}` };
91
91
  });
92
92
  }
93
- async function authChecks(client) {
93
+ async function authChecks(client, now) {
94
94
  const conns = rows(await client.request('GET', '/v1/auth/connections'));
95
- if (conns.length === 0)
96
- return [{ id: 'auth', status: 'ok', message: 'no auth connections' }];
97
- // Protocol connections (Atlas, custom) can't be pinged with an API key: status and settings only.
98
- return conns.map((c) => {
95
+ const out = conns.map((c) => {
99
96
  const id = `auth.${c.id}`;
100
97
  const label = `${c.provider} auth connection${c.name ? ` "${c.name}"` : ''}`;
101
98
  if (c.status === 'paused')
@@ -103,20 +100,57 @@ async function authChecks(client) {
103
100
  if (c.tokenVerification && c.allowedOrigins.length === 0) {
104
101
  return { id, status: 'warn', message: `${label} verifies tokens but has no allowedOrigins: the widget session refuses browsers`, fix: `PATCH /v1/auth/connections/${c.id} {"allowedOrigins":["https://your.app"]}` };
105
102
  }
106
- return { id, status: 'ok', message: `${label} is ${c.status}` };
103
+ // Protocol connections (Atlas, custom) can't be pinged with an API key: when it last filed a sign-up says it's wired.
104
+ // undefined: an API from before lastSignupAt, nothing to say.
105
+ if (c.lastSignupAt === null) {
106
+ 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}` };
107
+ }
108
+ if (c.lastSignupAt && now.getTime() - new Date(c.lastSignupAt).getTime() > 30 * DAY) {
109
+ return { id, status: 'warn', message: `${label} is ${c.status}; no sign-up since ${c.lastSignupAt}`, fix: `check the platform still calls connection ${c.id}` };
110
+ }
111
+ return { id, status: 'ok', message: `${label} is ${c.status}${c.lastSignupAt ? `; last sign-up ${c.lastSignupAt}` : ''}` };
107
112
  });
113
+ if (!conns.some((c) => c.provider === 'atlas')) {
114
+ const other = conns.find((c) => c.status === 'active');
115
+ out.push(other
116
+ ? { id: 'auth.atlas', status: 'ok', message: `no Atlas connection; sign-ups come through ${other.provider}` }
117
+ : { id: 'auth.atlas', status: 'warn', message: 'no Atlas connection (and no other active auth connection): sign-ups are attributed only if your app calls associate', fix: 'POST /v1/auth/connections {"provider":"atlas","programId":"prg_…","instanceId":"…"}' });
118
+ }
119
+ return out;
108
120
  }
109
- async function trackingCheck(client) {
121
+ async function trackingCheck(client, env) {
110
122
  const org = await client.request('GET', '/v1/org');
123
+ const out = [];
111
124
  try {
112
125
  const cfg = await client.request('GET', `/t/${encodeURIComponent(org.trackingToken)}/config.json`);
113
- return [{ id: 'tracking', status: 'ok', message: `tracking token ${org.trackingToken} answers; cookie window ${cfg.cookieWindowDays} days` }];
126
+ out.push({ id: 'tracking', status: 'ok', message: `tracking token ${org.trackingToken} answers; cookie window ${cfg.cookieWindowDays} days` });
114
127
  }
115
128
  catch (err) {
116
129
  if (!(err instanceof ApiError && err.status === 404))
117
130
  throw err;
118
- return [{ id: 'tracking', status: 'fail', message: `tracking token ${org.trackingToken} is unknown to /t/…/config.json`, fix: '/settings' }];
131
+ out.push({ id: 'tracking', status: 'fail', message: `tracking token ${org.trackingToken} is unknown to /t/…/config.json`, fix: '/settings' });
132
+ }
133
+ // The token the product is configured with (run doctor with the app's env) must be this mode's.
134
+ const name = env.REFERALLI_TRACKING_TOKEN ? 'REFERALLI_TRACKING_TOKEN' : env.NEXT_PUBLIC_REFERALLI_TRACKING_TOKEN ? 'NEXT_PUBLIC_REFERALLI_TRACKING_TOKEN' : null;
135
+ if (!name)
136
+ return out;
137
+ const configured = env[name].trim();
138
+ const mode = org.livemode === false ? 'test' : 'live';
139
+ const id = 'tracking.configured';
140
+ const fix = `referalli env pull --mode ${mode}`;
141
+ if (configured === org.trackingToken) {
142
+ out.push({ id, status: 'ok', message: `${name} is the org's ${mode} token` });
143
+ return out;
119
144
  }
145
+ const other = mode === 'live' ? 'test' : 'live';
146
+ const tokens = await guard(id, fix, async () => {
147
+ const t = await client.request('GET', '/v1/org/tracking-tokens');
148
+ if (t[other].trackingToken === configured) {
149
+ return [{ id, status: 'warn', message: `${name} is the org's ${other} token but this key is ${mode}: run doctor with a ${other} key, or switch the app to the ${mode} token`, fix }];
150
+ }
151
+ return [{ id, status: 'fail', message: `${name}=${configured} is neither the org's live nor its test token: aff.js and links won't attribute to this org`, fix }];
152
+ });
153
+ return [...out, ...tokens];
120
154
  }
121
155
  const MARK = { ok: '✓', warn: '⚠', fail: '✗' };
122
156
  /** `referalli doctor [--program <id>] [--json]`: read-only health checks. Exit 1 when any check fails. */
@@ -127,8 +161,8 @@ export async function runDoctor(io, client, flags, now = new Date()) {
127
161
  guard('programs', undefined, () => termsChecks(client, program)),
128
162
  guard('webhooks', undefined, () => webhookChecks(client)),
129
163
  guard('billing', undefined, () => billingChecks(client)),
130
- guard('auth', undefined, () => authChecks(client)),
131
- guard('tracking', undefined, () => trackingCheck(client)),
164
+ guard('auth', undefined, () => authChecks(client, now)),
165
+ guard('tracking', undefined, () => trackingCheck(client, io.env)),
132
166
  ])).flat();
133
167
  if (flags.json)
134
168
  io.out(JSON.stringify({ checks }, null, 2));
@@ -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] [--expires-days N]\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\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)";
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] [--expires-days N]\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 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)";
7
7
  /** Run one command; returns the process exit code. */
8
8
  export declare function runCli(argv: string[], io: Io): Promise<number>;
package/dist/src/index.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { parseArgs } from 'node:util';
2
2
  import { ApiError } from './client.js';
3
- import { api, apply, CliError, doctor, eventsTail, keys, login, listen, logout, logsTail, open, trigger, whoami } from './commands.js';
3
+ import { api, apply, CliError, doctor, env, eventsTail, keys, login, listen, logout, logsTail, open, trigger, whoami } from './commands.js';
4
4
  import { VERSION } from './version.js';
5
5
  export { readConfig, writeConfig, configPath } from './config.js';
6
6
  export { createClient, ApiError } from './client.js';
@@ -25,11 +25,13 @@ Usage:
25
25
  referalli plan <referalli.yaml> [--check]
26
26
  referalli apply <referalli.yaml> [--plan] [--check] [--secret-file PATH]
27
27
  referalli doctor [--program <id>] [--json]
28
+ referalli env pull [--mode live|test] (.env lines on stdout; default: the key's mode)
28
29
 
29
30
  Environment:
30
31
  REFERALLI_API_KEY use this key instead of the saved login
31
32
  REFERALLI_API_URL API base URL (default: the hosted API)
32
- REFERALLI_CONFIG_DIR where the login is saved (default ~/.config/referalli)`;
33
+ REFERALLI_CONFIG_DIR where the login is saved (default ~/.config/referalli)
34
+ REFERALLI_TRACKING_TOKEN doctor checks it is this mode's token (or NEXT_PUBLIC_REFERALLI_TRACKING_TOKEN)`;
33
35
  /** Run one command; returns the process exit code. */
34
36
  export async function runCli(argv, io) {
35
37
  let parsed;
@@ -118,6 +120,8 @@ export async function runCli(argv, io) {
118
120
  return await apply(io, rest[0], flags, command === 'plan');
119
121
  case 'doctor':
120
122
  return await doctor(io, flags);
123
+ case 'env':
124
+ return await env(io, rest[0], flags);
121
125
  default:
122
126
  io.err(`Unknown command "${command}".`);
123
127
  io.err(HELP);
@@ -1,2 +1,2 @@
1
1
  /** Kept in step with package.json by test/version.test.ts. */
2
- export declare const VERSION = "0.4.0";
2
+ export declare const VERSION = "0.4.1";
@@ -1,2 +1,2 @@
1
1
  /** Kept in step with package.json by test/version.test.ts. */
2
- export const VERSION = '0.4.0';
2
+ export const VERSION = '0.4.1';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@referalli/cli",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
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",