@straitlink/cli 0.2.2 → 0.3.0

package/README.md

@@ -15,6 +15,8 @@ One command sets up Strait deep links in your app. Every link open and install i
 npx @straitlink/cli init                                     # set up deep links in your app
 npx @straitlink/cli doctor --host acme.strait.link          # check the link host lists your app
 npx @straitlink/cli links create summer https://acme.com/s  # create a link (secret key in env)
+npx @straitlink/cli test                                    # key, engine and link domain: pass/fail (secret key in env)
+npx @straitlink/cli events add purchase                     # print the code that tracks an event
 ```
 
 `strait init` sets up Strait deep links in a React Native, Expo, Flutter or Android (Kotlin) app:
@@ -96,6 +98,38 @@ These call the [public API](https://straitlink.in/docs/api/) (`POST /v1/links`,
 
 Exit codes: `0` done, `1` the API said no or can't be reached (its message on stderr), `2` usage problem.
 
+## Am I set up right? `strait test`
+
+```bash
+export STRAIT_SECRET_KEY=st_live_…        # Dashboard → Settings → Secret keys
+npx @straitlink/cli test
+```
+
+```
+Strait test
+
+  pass  Engine       https://strait.link answers (version ddca50a)
+  pass  Key          valid live key st_live_3f9a… for workspace "Acme"
+  pass  Link domain  acme.strait.link (plan starter)
+  pass  iPhone       acme.strait.link lists TEAM123.com.acme.shop
+  pass  Android      acme.strait.link lists com.acme.shop
+
+All checks passed.
+Your app's own setup (intent filters, Associated Domains): strait doctor --android <package> --ios <bundleId>.
+```
+
+One read-only pass: the engine answers (`GET /healthz`), the secret key is valid and which workspace it belongs to, test or live (`GET /v1/workspace`), and the workspace's link domain serves `apple-app-site-association` and `assetlinks.json` listing your apps (the same checks as `strait doctor`). A failed check prints its fix; checks that need it are skipped. Exit `1` when any check fails, `2` for a missing or wrong kind of key, so it can gate a CI job. `--json` prints `{ ok, workspace, checks }`. Same key rules as `strait links`: never printed, publishable keys refused.
+
+## Track an event: `strait events add`
+
+```bash
+npx @straitlink/cli events add purchase                 # platform detected from the project files
+npx @straitlink/cli events add sign_up --platform ios   # react-native | flutter | ios | android | web
+npx @straitlink/cli events add purchase ./mobile         # [dir]: the app folder, default the current one
+```
+
+Prints ready-to-paste code with each SDK's own call: `trackEvent` in React Native (and Expo), Flutter, iOS and Android, using the client `strait init` wrote; on the web, `reportWebOpen` on page load plus `trackEvent` from `@straitlink/web`. The platform is detected from `package.json`, `pubspec.yaml`, Gradle files, an `.xcodeproj` or `Package.swift`. Nothing is written. Event names are 1-64 letters, numbers, spaces and `_ . : -`.
+
 ## Install lines: one constant
 
 Every install line the CLI prints comes from `INSTALL` in `src/install.mjs` (`source` + `githubOwner`). It mirrors `install` in `site/site.config.json` and `INSTALL` in `dashboard/src/lib/install.ts`, and `test/install.test.mjs` fails if they drift while the repos sit side by side. Moving the SDK repos to an organisation means changing `githubOwner`. Publishing to npm, pub.dev and Maven Central means changing `source` to `"registry"`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@straitlink/cli",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Strait deep links from the terminal: init sets them up in a React Native, Expo, Flutter or Android app, doctor checks your link host, links creates and lists links and saves QR codes.",
   "keywords": [
     "strait",

package/src/cli.mjs

@@ -9,6 +9,8 @@ import { resolve } from 'node:path';
 import { formatDoctor, runDoctor } from './doctor.mjs';
 import { ApiError, DEFAULT_API_URL, apiClient, linksCommand, secretKey } from './links.mjs';
 import { CLI_VERSION } from './version.mjs';
+import { formatSelfTest, runSelfTest } from './selftest.mjs';
+import { eventsCommand } from './events.mjs';
 
 const OPTIONS = {
   init: {
@@ -43,6 +45,14 @@ const OPTIONS = {
     force: { type: 'boolean', default: false },
     json: { type: 'boolean', default: false },
   },
+  test: {
+    'secret-key': { type: 'string' },
+    'api-url': { type: 'string' },
+    json: { type: 'boolean', default: false },
+  },
+  events: {
+    platform: { type: 'string' },
+  },
 };
 
 export const HELP = `strait: set up and check Strait deep links, and manage links
@@ -53,6 +63,8 @@ Usage
   strait links create <slug> <url> [options]  Create a link
   strait links list [options]                 List links
   strait links qr <slug> [options]            Save a link's QR code
+  strait test [options]                       Check your key, the engine and your link domain
+  strait events add <name> [dir] [options]    Print ready-to-paste code that tracks an event
 
 init options
   --key <st_pub_live_…>   Publishable key (Dashboard → Get started)
@@ -83,6 +95,16 @@ links options
   --format png|svg, --size <px>, --out <file>, --force  qr: output (default <slug>.png)
   --json                  Print the API answer as JSON
 
+test options
+  --secret-key, --api-url   As for links (env STRAIT_SECRET_KEY, STRAIT_API_URL)
+  --json                  Print { ok, workspace, checks } as JSON
+  Checks the engine answers, the key is valid (which workspace, test or live), and the
+  workspace's link domain serves apple-app-site-association and assetlinks.json. Exit 1
+  when a check fails (so it can run in CI), 2 for a missing or wrong kind of key.
+
+events options
+  --platform <name>       react-native | flutter | ios | android | web (detected by default)
+
 Environment
   STRAIT_PUBLISHABLE_KEY, STRAIT_LINK_HOST, STRAIT_SECRET_KEY, STRAIT_API_URL
 
@@ -91,6 +113,8 @@ Examples
   npx @straitlink/cli init --key st_pub_live_… --host acme.strait.link --dry-run
   npx @straitlink/cli doctor --host acme.strait.link --android com.acme.shop --ios com.acme.shop
   STRAIT_SECRET_KEY=st_live_… npx @straitlink/cli links create summer https://acme.com/summer
+  STRAIT_SECRET_KEY=st_live_… npx @straitlink/cli test
+  npx @straitlink/cli events add purchase
 `;
 
 /**
@@ -122,7 +146,7 @@ export async function main(argv, io = {}) {
   }
   if (cmd !== 'init') {
     try {
-      return await (cmd === 'doctor' ? doctor : links)(args, { out, err, env, io });
+      return await { doctor, links, test: selfTest, events }[cmd](args, { out, err, env, io });
     } catch (e) {
       if (e instanceof UsageError) {
         err.write(`strait: ${e.message}\n`);
@@ -208,6 +232,24 @@ async function doctor({ values: v }, { out, env, io }) {
   return result.ok ? 0 : 1;
 }
 
+async function selfTest({ values: v, positionals }, { out, env, io }) {
+  if (positionals.length) throw new UsageError(`strait test takes no arguments ("${positionals[0]}"). Options: --secret-key, --api-url, --json.`);
+  const key = secretKey(v['secret-key'] ?? env.STRAIT_SECRET_KEY);
+  const apiUrl = String(v['api-url'] || env.STRAIT_API_URL || DEFAULT_API_URL).replace(/\/+$/, '');
+  const fetchImpl = io.fetch ?? fetch;
+  const call = apiClient({ apiUrl, key, fetch: fetchImpl, userAgent: `strait-cli/${CLI_VERSION}` });
+  const result = await runSelfTest({ call, apiUrl, key, fetch: fetchImpl });
+  out.write((v.json ? JSON.stringify(result, null, 2) : formatSelfTest(result)) + '\n');
+  return result.ok ? 0 : 1;
+}
+
+async function events({ values: v, positionals }, { out, env, io }) {
+  const [sub, name, dirArg, extra] = positionals;
+  if (extra !== undefined) throw new UsageError(`Too many arguments ("${extra}"). Usage: strait events add <name> [dir] [--platform …]`);
+  out.write(eventsCommand(sub, name === undefined ? [] : [name], v, { dir: resolve(io.cwd ?? process.cwd(), dirArg ?? '.'), env }) + '\n');
+  return 0;
+}
+
 async function links({ values: v, positionals }, { out, env, io }) {
   const [sub, ...rest] = positionals;
   if (!['create', 'list', 'qr'].includes(sub)) return linksCommand(sub, rest, v, {});

package/src/events.mjs

@@ -0,0 +1,105 @@
+// `strait events add <name>`: prints ready-to-paste tracking code (ADR 0001). Each snippet is the
+// SDK's own call, read from its source on 5 Nov 2026:
+//   React Native 0.11  links.trackEvent(name, { value, currency, eventId })        src/strait.ts (0.10.2: no eventId)
+//   Flutter 0.10       links.trackEvent(name, value:, currency:, linkId:, clickId:, eventId:) lib/src/client.dart
+//   iOS 0.10           strait.trackEvent(_:value:currency:linkId:clickId:eventId:completion:)  StraitLinks.swift
+//   Android 0.8        client.trackEvent(name, value, currency, linkId, clickId, eventId)  StraitClient.kt (blocks)
+//   Web (Unreleased)   trackEvent(config, name, { value, currency, eventId })   src/index.ts (sdk-web ADR 0002)
+// `links` / `StraitLinks.client` are the names `strait init` writes (templates.mjs).
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { detectProject } from './detect.mjs';
+import { PACKAGES, VERSIONS } from './install.mjs';
+import { UsageError, normalizeHost } from './validate.mjs';
+
+export const PLATFORMS = ['react-native', 'flutter', 'ios', 'android', 'web'];
+const LABEL = { 'react-native': 'React Native', flutter: 'Flutter', ios: 'iOS (Swift)', android: 'Android (Kotlin)', web: 'Web' };
+// The engine takes any name up to 64 characters; this subset can't break or inject into the printed code.
+const NAME = /^[A-Za-z0-9_.:-](?:[A-Za-z0-9 _.:-]{0,62}[A-Za-z0-9_.:-])?$/;
+
+/** The platform for a folder from its files, or null. Expo uses the React Native SDK. */
+export function detectPlatform(dir) {
+  const p = detectProject(dir);
+  if (p) return { platform: p.framework === 'expo' ? 'react-native' : p.framework, sdkInstalled: p.sdkInstalled };
+  let names = [];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return null;
+  }
+  if (names.includes('Package.swift') || names.some((n) => n.endsWith('.xcodeproj') || n.endsWith('.xcworkspace'))) return { platform: 'ios', sdkInstalled: null };
+  if (existsSync(join(dir, 'package.json'))) return { platform: 'web', sdkInstalled: null };
+  return null;
+}
+
+/** @returns {string} what to print */
+export function eventsCommand(sub, positionals, v, { dir, env }) {
+  const usage = 'Usage: strait events add <name> [dir] [--platform react-native|flutter|ios|android|web]';
+  if (sub !== 'add') throw new UsageError(`${usage}${sub ? ` ("${sub}" is not a subcommand)` : ''}`);
+  const [name] = positionals;
+  if (name === undefined) throw new UsageError(usage);
+  if (!NAME.test(name)) {
+    throw new UsageError('That event name would break the code. Use 1-64 letters, numbers, spaces and _ . : - (for example purchase or sign_up).');
+  }
+  let platform = v.platform?.trim().toLowerCase();
+  let sdkInstalled = null;
+  if (platform && !PLATFORMS.includes(platform)) throw new UsageError(`--platform is one of ${PLATFORMS.join(', ')}, not "${v.platform}".`);
+  if (!platform) {
+    const found = detectPlatform(dir);
+    if (!found) throw new UsageError(`No app found in ${dir}. Pass --platform react-native|flutter|ios|android|web.`);
+    ({ platform, sdkInstalled } = found);
+  }
+  // Only values that can't break the quoted string go into the code; anything else stays a placeholder.
+  const envKey = String(env.STRAIT_PUBLISHABLE_KEY ?? '').trim();
+  const key = /^st_pub_(live|test)_[A-Za-z0-9]{8,64}$/.test(envKey) ? envKey : 'st_pub_live_…';
+  let host = '<your-handle>.strait.link';
+  try {
+    if (env.STRAIT_LINK_HOST) host = normalizeHost(env.STRAIT_LINK_HOST);
+  } catch {
+    // keep the placeholder
+  }
+  const out = [`"${name}" event for ${LABEL[platform]}${v.platform ? '' : ' (detected)'}. Paste it where the action happens:`, '', SNIPPETS[platform](name, { key, host }).trimEnd(), ''];
+  if (sdkInstalled === false) out.push('The Strait SDK is not in this project yet: run strait init first, it writes the client this code uses.');
+  out.push('Events show in Dashboard → Analytics, on the tap that brought the user (for 7 days).');
+  return out.join('\n');
+}
+
+const SNIPPETS = {
+  'react-native': (n) => `import { links } from './links'; // the client strait init wrote; fix the path for this file
+
+// Resolves true when Strait took it; never throws. For revenue add
+// { value: 49.99, currency: 'USD', eventId: order.id } (eventId: a retry is counted once;
+// eventId needs ${PACKAGES.reactNative} 0.11.0+).
+await links.trackEvent('${n}');
+`,
+  flutter: (n) => `import 'links.dart'; // lib/links.dart, the client strait init wrote
+
+// Resolves true when Strait took it; never throws. For revenue add
+// value: 49.99, currency: 'USD', eventId: order.id (eventId: a retry is counted once;
+// needs ${PACKAGES.flutter} 0.10.0+).
+await links.trackEvent('${n}');
+`,
+  ios: (n) => `// strait: your StraitLinks instance (strait-sdk-swift README, "Use"). Never throws.
+// For revenue add value: 49.99, currency: "USD", eventId: order.id (a retry is counted once;
+// eventId needs StraitSDK ${VERSIONS.version}+: SwiftPM from: "${VERSIONS.version}").
+strait.trackEvent("${n}") { ok in
+    // ok == false: not sent now; kept and sent later when it was the network
+}
+`,
+  android: (n) => `// It sends on the calling thread: call it off the main thread. Never throws.
+// For revenue add value = 49.99, currency = "USD", eventId = order.id (a retry is counted once;
+// eventId needs ${PACKAGES.android} ${VERSIONS.androidVersion}+, what strait init installs).
+val ok = StraitLinks.client.trackEvent("${n}")
+`,
+  web: (n, { key, host }) => `import { reportWebOpen, trackEvent } from '@straitlink/web';
+
+const strait = { publishableKey: '${key}', endpoint: 'https://${host}' };
+
+// On page load: counts the open and remembers the tap this visit came from.
+await reportWebOpen(strait);
+
+// Where "${n}" happens. Resolves true when Strait took it; never throws. For revenue add
+// { value: 49.99, currency: 'USD', eventId: order.id } (eventId: a repeat is counted once).
+await trackEvent(strait, '${n}');
+`,
+};

package/src/install.mjs

@@ -19,12 +19,13 @@ export const sourceFor = (src, registry) => (typeof src.source === 'string' ? sr
 /**
  * SDK versions the generated code is written for. Must equal site/site.config.json `packages`
  * (the one source of truth; test/install.test.mjs fails if they differ). Bump both together.
+ * `strait events add` reads them too: its iOS/Android eventId needs these SDKs.
  */
 export const VERSIONS = {
-  version: '0.9.5', // Swift (Unity is not written by this CLI)
+  version: '0.11.0', // Swift (Unity is not written by this CLI)
   rnVersion: '0.10.2',
-  flutterVersion: '0.9.7',
-  androidVersion: '0.8.4',
+  flutterVersion: '0.10.1',
+  androidVersion: '0.10.0',
 };
 
 export const PACKAGES = {

package/src/selftest.mjs

@@ -0,0 +1,86 @@
+// `strait test`: one pass for "am I set up right?" (ADR 0001). The engine answers (GET /healthz),
+// the secret key is valid and says which workspace (GET /v1/workspace), and the workspace's link
+// domain serves apple-app-site-association and assetlinks.json (the same doctor as `strait doctor`).
+// Every failure is a `fail` line, never a throw; later checks that depend on it are `skip`.
+import { ApiError, redact } from './links.mjs';
+import { normalizeHost } from './validate.mjs';
+import { runDoctor } from './doctor.mjs';
+
+const pass = (id, label, title) => ({ id, label, status: 'pass', title, fix: '' });
+const fail = (id, label, title, fix = '') => ({ id, label, status: 'fail', title, fix });
+const skip = (id, label, why) => ({ id, label, status: 'skip', title: why, fix: '' });
+
+const DOMAIN_CHECKS = [['domain', 'Link domain'], ['ios', 'iPhone'], ['android', 'Android']];
+
+/**
+ * @param {{ call: Function, apiUrl: string, key: string, fetch: typeof fetch }} opts
+ * @returns {Promise<{ ok: boolean, workspace?: object, checks: object[] }>}
+ */
+export async function runSelfTest({ call, apiUrl, key, fetch: fetchImpl }) {
+  const checks = [];
+  let workspace;
+  const done = () => ({ ok: !checks.some((c) => c.status === 'fail'), ...(workspace ? { workspace } : {}), checks });
+
+  try {
+    const h = await (await call('GET', '/healthz')).json().catch(() => ({}));
+    if (h?.ok !== true) throw new ApiError(`${apiUrl} answered, but not like a Strait engine`);
+    checks.push(pass('engine', 'Engine', `${apiUrl} answers${h.version ? ` (version ${h.version})` : ''}`));
+  } catch (e) {
+    if (!(e instanceof ApiError)) throw e;
+    checks.push(fail('engine', 'Engine', e.message, 'Check your connection and --api-url, or https://straitlink.in/platform-status/.'));
+    checks.push(skip('key', 'Key', 'needs the engine'), ...DOMAIN_CHECKS.map(([id, l]) => skip(id, l, 'needs the engine')));
+    return done();
+  }
+
+  const mode = key.startsWith('st_test_') ? 'test' : 'live';
+  try {
+    const w = await (await call('GET', '/v1/workspace')).json().catch(() => null);
+    if (typeof w?.linkDomain !== 'string' || !w.linkDomain) throw new ApiError("GET /v1/workspace: the engine's answer has no link domain");
+    // Only strings are shown; the prefix is cut to the 12 characters the engine sends, in case a server echoes more.
+    const str = (x) => (typeof x === 'string' ? x : null);
+    const prefix = str(w.key?.prefix) && redact(w.key.prefix, key).slice(0, 12);
+    workspace = {
+      name: str(w.name), handle: str(w.handle), linkDomain: w.linkDomain,
+      customDomains: Array.isArray(w.customDomains) ? w.customDomains.filter((d) => typeof d === 'string') : [],
+      plan: str(w.plan), mode, keyPrefix: prefix || null, keyScope: str(w.key?.scope),
+    };
+    const access = workspace.keyScope && workspace.keyScope !== 'full' ? `, ${workspace.keyScope} access` : '';
+    checks.push(pass('key', 'Key', `valid ${mode} key${prefix ? ` ${prefix}…` : ''} for workspace "${workspace.name ?? '?'}"${access}`));
+  } catch (e) {
+    if (!(e instanceof ApiError)) throw e;
+    checks.push(fail('key', 'Key', e.message, 'Create a secret key in Dashboard → Settings → Secret keys and set STRAIT_SECRET_KEY.'));
+    checks.push(...DOMAIN_CHECKS.map(([id, l]) => skip(id, l, 'needs a valid key')));
+    return done();
+  }
+
+  let host;
+  try {
+    host = normalizeHost(workspace.linkDomain);
+  } catch {
+    checks.push(fail('domain', 'Link domain', `"${workspace.linkDomain}" is not a host name`, 'Contact support@straitlink.in: the engine sent a bad link domain.'));
+    checks.push(skip('ios', 'iPhone', 'needs a link domain'), skip('android', 'Android', 'needs a link domain'));
+    return done();
+  }
+  const others = workspace.customDomains.filter((d) => d !== host);
+  checks.push(pass('domain', 'Link domain', `${host}${workspace.plan ? ` (plan ${workspace.plan})` : ''}${others.length ? `; also ${others.join(', ')}` : ''}`));
+  const doc = await runDoctor({ host, fetch: fetchImpl });
+  for (const [id, label] of [['ios', 'iPhone'], ['android', 'Android']]) {
+    const f = doc[id].findings.find((x) => x.severity === 'error') ?? doc[id].findings[0];
+    checks.push(f.severity === 'error' ? fail(id, label, f.title, f.fix) : pass(id, label, f.title));
+  }
+  return done();
+}
+
+/** The readable list: one line per check, its fix under a failure, then the verdict. */
+export function formatSelfTest(result) {
+  const lines = ['Strait test', ''];
+  for (const c of result.checks) {
+    lines.push(`  ${c.status}  ${c.label.padEnd(12)} ${c.title}`);
+    if (c.fix) lines.push(`${' '.repeat(21)}Fix: ${c.fix}`);
+  }
+  const failed = result.checks.filter((c) => c.status === 'fail').length;
+  lines.push('', failed ? `${failed} check${failed > 1 ? 's' : ''} failed.` : 'All checks passed.');
+  if (!failed) lines.push('Your app\'s own setup (intent filters, Associated Domains): strait doctor --android <package> --ios <bundleId>.');
+  // Workspace names and served files are other people's text: no terminal control characters.
+  return lines.join('\n').replace(/[\u0000-\u0009\u000b-\u001f\u007f-\u009f]/g, '');
+}

package/src/version.mjs

@@ -1,2 +1,2 @@
 // Kept equal to package.json version (test/links.test.mjs checks it). Sent as the API User-Agent.
-export const CLI_VERSION = '0.2.2';
+export const CLI_VERSION = '0.3.0';