@straitlink/cli 0.1.4 → 0.2.0

package/README.md

@@ -12,7 +12,9 @@ One command sets up Strait deep links in your app. Every link open and install i
 `@straitlink/cli`
 
 ```bash
-npx @straitlink/cli init
+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)
 ```
 
 `strait init` sets up Strait deep links in a React Native, Expo, Flutter or Android (Kotlin) app:
@@ -56,6 +58,44 @@ From a checkout of this repo: `node bin/strait.mjs init ../my-app`, or `npm link
 
 Exit codes: `0` done, `2` usage problem (message on stderr), `1` unexpected error.
 
+## Check your setup: `strait doctor`
+
+```bash
+npx @straitlink/cli doctor --host acme.strait.link --android com.acme.shop --ios com.acme.shop
+```
+
+Runs the same checks, with the same finding ids and wording, as `doctor()` in the Strait SDKs (React Native 0.9.3, Swift 0.9.4, Android 0.8.4, Flutter 0.9.4; contract B23, the 43 shared cases in `test/doctor-vectors.json`). It fetches `https://<host>/.well-known/assetlinks.json` and `apple-app-site-association` once each and tells you whether your package, bundle ID and (with `--cert`) signing certificate are listed, with the fix for each problem:
+
+```
+Android (assetlinks.json)
+  error  app.missing       acme.strait.link doesn't list com.acme.shop
+                           Fix: Add com.acme.shop in Dashboard → Apps & stores (listed now: com.acme.app).
+```
+
+| Option | |
+|---|---|
+| `--host` | Your link domain. Env: `STRAIT_LINK_HOST` |
+| `--android <package>` / `--ios <bundleId>` | The app to look for. With neither, both files are checked and the apps they list are shown |
+| `--cert <sha256>` | Android signing certificate fingerprint, any format; repeat for debug, release and Play App Signing |
+| `--key` | Also check the publishable key. Env: `STRAIT_PUBLISHABLE_KEY`. Left out, the key check is skipped |
+| `--json` | The reports as JSON, for CI and agents |
+
+Exit codes: `0` no errors (warnings allowed), `1` a check failed, `2` usage problem. What a terminal can't see (intent filters, the Associated Domains entitlement) is checked by `doctor()` inside a debug build and by the [free tools](https://straitlink.in/tools/).
+
+## Manage links: `strait links`
+
+```bash
+export STRAIT_SECRET_KEY=st_live_…        # Dashboard → Settings → Secret keys
+npx @straitlink/cli links create summer https://acme.com/summer --campaign sale --tag email
+npx @straitlink/cli links list --status active --limit 20
+npx @straitlink/cli links qr summer --size 512          # writes summer.png
+npx @straitlink/cli links qr summer --format svg --out summer.svg
+```
+
+These call the [public API](https://straitlink.in/docs/api/) (`POST /v1/links`, `GET /v1/links`, `GET /v1/links/{slug}/qr`) with a secret key from `STRAIT_SECRET_KEY` or `--secret-key` (the environment is better: flags stay in your shell history). The key is never printed, not even inside an API error. A publishable key is refused here. `--api-url` (env `STRAIT_API_URL`) points at another engine and must be https. `--json` prints the API answer as is. A QR file is never overwritten without `--force`.
+
+Exit codes: `0` done, `1` the API said no or can't be reached (its message on stderr), `2` usage problem.
+
 ## 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,7 +1,7 @@
 {
   "name": "@straitlink/cli",
-  "version": "0.1.4",
-  "description": "npx @straitlink/cli init: set up Strait deep links in a React Native, Expo, Flutter or Android app.",
+  "version": "0.2.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",
     "deep-linking",
@@ -12,6 +12,7 @@
     "expo",
     "flutter",
     "android",
+    "qr-code",
     "cli"
   ],
   "homepage": "https://straitlink.in/docs/",

package/src/cli.mjs

@@ -6,13 +6,55 @@ import { detectProject } from './detect.mjs';
 import { formatPlan, planInit, writeFiles } from './init.mjs';
 import { UsageError, normalizeHost, normalizeKey, normalizeScheme, suggestScheme } from './validate.mjs';
 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';
 
-export const HELP = `strait: set up Strait deep links in your app
+const OPTIONS = {
+  init: {
+    key: { type: 'string' },
+    host: { type: 'string' },
+    scheme: { type: 'string' },
+    framework: { type: 'string' },
+    'dry-run': { type: 'boolean', default: false },
+    force: { type: 'boolean', default: false },
+    yes: { type: 'boolean', short: 'y', default: false },
+  },
+  doctor: {
+    host: { type: 'string' },
+    key: { type: 'string' },
+    android: { type: 'string' },
+    ios: { type: 'string' },
+    cert: { type: 'string', multiple: true },
+    json: { type: 'boolean', default: false },
+  },
+  links: {
+    'secret-key': { type: 'string' },
+    'api-url': { type: 'string' },
+    title: { type: 'string' },
+    campaign: { type: 'string' },
+    tag: { type: 'string', multiple: true },
+    limit: { type: 'string' },
+    status: { type: 'string' },
+    cursor: { type: 'string' },
+    format: { type: 'string' },
+    size: { type: 'string' },
+    out: { type: 'string' },
+    force: { type: 'boolean', default: false },
+    json: { type: 'boolean', default: false },
+  },
+};
+
+export const HELP = `strait: set up and check Strait deep links, and manage links
 
 Usage
-  strait init [dir] [options]
+  strait init [dir] [options]                 Write the Strait integration into your app
+  strait doctor --host <host> [options]       Check your link host is set up for your app
+  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
 
-Options
+init options
   --key <st_pub_live_…>   Publishable key (Dashboard → Get started)
   --host <host>           Your link domain, e.g. acme.strait.link
   --scheme <scheme>       Your app's custom scheme, the one in Dashboard → Apps & stores,
@@ -21,14 +63,34 @@ Options
   --dry-run               Print what would be written; write nothing
   --force                 Replace an existing integration file
   --yes, -y               Never prompt; fail if something is missing
-  --help, -h              Show this help
+
+doctor options (the same checks and messages as doctor() in the SDKs)
+  --host <host>           Your link domain (env STRAIT_LINK_HOST)
+  --android <package>     Android package, e.g. com.acme.shop
+  --ios <bundleId>        iPhone bundle ID, e.g. com.acme.shop
+  --cert <sha256>         Android signing certificate fingerprint (repeatable)
+  --key <st_pub_live_…>   Also check the publishable key (env STRAIT_PUBLISHABLE_KEY)
+  --json                  Print the reports as JSON
+  With neither --android nor --ios, both files are checked and the apps they list are shown.
+  Exit 1 when a check fails.
+
+links options
+  --secret-key <st_live_…>  Secret key (Dashboard → Settings → Secret keys). Prefer the
+                            env STRAIT_SECRET_KEY: flags stay in your shell history
+  --api-url <url>         API base (env STRAIT_API_URL, default https://strait.link)
+  --title, --campaign, --tag <tag> (repeatable)   create: link details
+  --limit <n>, --status active|paused, --cursor <c>  list: paging and filter
+  --format png|svg, --size <px>, --out <file>, --force  qr: output (default <slug>.png)
+  --json                  Print the API answer as JSON
 
 Environment
-  STRAIT_PUBLISHABLE_KEY, STRAIT_LINK_HOST are used when the flags are absent.
+  STRAIT_PUBLISHABLE_KEY, STRAIT_LINK_HOST, STRAIT_SECRET_KEY, STRAIT_API_URL
 
 Examples
   npx @straitlink/cli init
   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
 `;
 
 /**
@@ -40,35 +102,40 @@ export async function main(argv, io = {}) {
   const err = io.stderr ?? process.stderr;
   const env = io.env ?? process.env;
   const isTTY = io.isTTY ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const cmd = argv[0]?.startsWith('-') ? undefined : argv[0];
+  if (!cmd || !(cmd in OPTIONS)) {
+    const help = !cmd && argv.some((a) => a === '--help' || a === '-h');
+    if (cmd) err.write(`Unknown command "${cmd}".\n\n${HELP}`);
+    else out.write(HELP);
+    return help ? 0 : 2;
+  }
   let args;
   try {
-    args = parseArgs({
-      args: argv,
-      allowPositionals: true,
-      options: {
-        key: { type: 'string' },
-        host: { type: 'string' },
-        scheme: { type: 'string' },
-        framework: { type: 'string' },
-        'dry-run': { type: 'boolean', default: false },
-        force: { type: 'boolean', default: false },
-        yes: { type: 'boolean', short: 'y', default: false },
-        help: { type: 'boolean', short: 'h', default: false },
-      },
-    });
+    args = parseArgs({ args: argv.slice(1), allowPositionals: true, options: { ...OPTIONS[cmd], help: { type: 'boolean', short: 'h', default: false } } });
   } catch (e) {
     err.write(`${e.message}\n\n${HELP}`);
     return 2;
   }
-  const [cmd, dirArg] = args.positionals;
-  if (args.values.help || !cmd) {
+  if (args.values.help) {
     out.write(HELP);
-    return args.values.help ? 0 : 2;
+    return 0;
   }
   if (cmd !== 'init') {
-    err.write(`Unknown command "${cmd}".\n\n${HELP}`);
-    return 2;
+    try {
+      return await (cmd === 'doctor' ? doctor : links)(args, { out, err, env, io });
+    } catch (e) {
+      if (e instanceof UsageError) {
+        err.write(`strait: ${e.message}\n`);
+        return 2;
+      }
+      if (e instanceof ApiError) {
+        err.write(`strait: ${e.message}\n`);
+        return 1;
+      }
+      throw e;
+    }
   }
+  const [dirArg] = args.positionals;
 
   const v = args.values;
   const dir = resolve(dirArg ?? '.');
@@ -129,3 +196,23 @@ async function askValid(ask, question, normalize, err) {
 async function terminalAsker(input, output) {
   return createInterface({ input, output });
 }
+
+async function doctor({ values: v }, { out, env, io }) {
+  const hostIn = v.host ?? env.STRAIT_LINK_HOST;
+  if (!hostIn) throw new UsageError('Missing --host: your link domain from Dashboard → Get started, e.g. --host acme.strait.link.');
+  const host = normalizeHost(hostIn);
+  const keyIn = v.key ?? env.STRAIT_PUBLISHABLE_KEY;
+  const key = keyIn ? String(keyIn).trim() : undefined;
+  const result = await runDoctor({ host, key, android: v.android?.trim(), ios: v.ios?.trim(), certs: v.cert ?? [], fetch: io.fetch ?? fetch });
+  out.write((v.json ? JSON.stringify(result, null, 2) : formatDoctor(result)) + '\n');
+  return result.ok ? 0 : 1;
+}
+
+async function links({ values: v, positionals }, { out, env, io }) {
+  const [sub, ...rest] = positionals;
+  if (!['create', 'list', 'qr'].includes(sub)) return linksCommand(sub, rest, v, {});
+  const key = secretKey(v['secret-key'] ?? env.STRAIT_SECRET_KEY);
+  const call = apiClient({ apiUrl: v['api-url'] ?? env.STRAIT_API_URL ?? DEFAULT_API_URL, key, fetch: io.fetch ?? fetch, userAgent: `strait-cli/${CLI_VERSION}` });
+  out.write((await linksCommand(sub, rest, v, { call, cwd: io.cwd ?? process.cwd() })) + '\n');
+  return 0;
+}

package/src/doctor.mjs

@@ -0,0 +1,146 @@
+// `strait doctor`: the SDK setup check (contract B23, shared-spec docs/adr/0002-sdk-doctor.md) from a
+// terminal. `doctorFindings` is a line-for-line port of strait-sdk-react-native 0.9.3 src/doctor.ts:
+// same finding ids, severities and wording as every SDK (test/doctor-vectors.json, 43 shared cases).
+
+/** The endpoint's host when it is an `https://` URL with a host, else null. */
+export function doctorHost(endpoint) {
+  const m = /^https:\/\/([^/?#\s@]+)(?:[/?#]|$)/i.exec(String(endpoint ?? '').trim());
+  return m ? m[1].toLowerCase() : null;
+}
+
+/** Upper-case, colon-separated, as assetlinks.json writes it. */
+const normFp = (s) => (s.replace(/[^0-9a-f]/gi, '').toUpperCase().match(/../g) ?? []).join(':');
+
+const ok = (id, title) => ({ id, severity: 'ok', title, fix: '' });
+const err = (id, title, fix) => ({ id, severity: 'error', title, fix });
+
+/** Android: package → fingerprints; iOS: full appIDs (value unused). Null = not the JSON expected. */
+function listedApps(platform, body) {
+  let json;
+  try {
+    json = JSON.parse(body);
+  } catch {
+    return null;
+  }
+  const apps = new Map();
+  if (platform === 'android') {
+    if (!Array.isArray(json)) return null;
+    for (const s of json) {
+      const t = s?.target;
+      if (t?.namespace !== 'android_app' || typeof t.package_name !== 'string') continue;
+      const fps = Array.isArray(t.sha256_cert_fingerprints) ? t.sha256_cert_fingerprints.filter((f) => typeof f === 'string') : [];
+      apps.set(t.package_name, [...(apps.get(t.package_name) ?? []), ...fps.map(normFp)]);
+    }
+    return apps;
+  }
+  const details = json?.applinks?.details;
+  if (!Array.isArray(details)) return null;
+  for (const d of details) {
+    for (const id of [...(Array.isArray(d?.appIDs) ? d.appIDs : []), d?.appID]) if (typeof id === 'string') apps.set(id, []);
+  }
+  return apps;
+}
+
+/**
+ * @param {{ publishableKey: string, endpoint: string, platform: 'android'|'ios', appId?: string,
+ *   certSha256?: string[], file?: { status?: number, body?: string } }} input
+ * @returns {{ ok: boolean, findings: { id: string, severity: 'ok'|'warn'|'error', title: string, fix: string }[] }}
+ */
+export function doctorFindings(input) {
+  const findings = [];
+  const key = input.publishableKey ?? '';
+  if (key.startsWith('st_pub_')) findings.push(ok('key.ok', 'Publishable key is set'));
+  else if (key.startsWith('st_live_') || key.startsWith('st_test_'))
+    findings.push(err('key.secret', 'This is a secret key, not the publishable key', 'Use the publishable key (st_pub_…) from Dashboard → Get started, and revoke this secret key in Dashboard → Settings → Secret keys: it has been inside your app.'));
+  else findings.push(err('key.invalid', 'Not a publishable key', 'Copy the publishable key (st_pub_…) from Dashboard → Get started.'));
+
+  const host = doctorHost(input.endpoint ?? '');
+  if (!host) {
+    findings.push(err('endpoint.invalid', "The endpoint isn't an https link domain", 'Set endpoint to your link domain from Dashboard → Get started, e.g. https://<handle>.strait.link.'));
+  } else if (input.file) findings.push(...hostFindings(input, host, input.file));
+  return { ok: !findings.some((f) => f.severity === 'error'), findings };
+}
+
+function hostFindings(input, host, file) {
+  const android = input.platform === 'android';
+  if (file.status === undefined)
+    return [err('host.unreachable', `Can't reach ${host}`, 'Check that endpoint is your link domain (Dashboard → Get started) and that this device is online.')];
+  const apps = file.status === 200 ? listedApps(input.platform, file.body ?? '') : null;
+  if (!apps)
+    return [err('host.file_missing', `${host} doesn't serve ${android ? 'assetlinks.json' : 'apple-app-site-association'}`, 'Use your Strait link domain as endpoint (Dashboard → Get started); Strait serves this file there.')];
+  if (!apps.size) return [err('app.none', `No ${android ? 'Android' : 'iOS'} app is set up for ${host}`, 'Add your app in Dashboard → Apps & stores.')];
+
+  const listed = [...apps.keys()].join(', ');
+  const app = input.appId?.trim();
+  if (!app) return [{ id: 'app.unknown', severity: 'warn', title: `${host} lists ${listed}`, fix: 'Make sure your app is one of these.' }];
+  const match = android ? (apps.has(app) ? app : undefined) : [...apps.keys()].find((id) => id.endsWith(`.${app}`));
+  if (!match) return [err('app.missing', `${host} doesn't list ${app}`, `Add ${app} in Dashboard → Apps & stores (listed now: ${listed}).`)];
+
+  const out = [ok('app.listed', `${host} lists ${match}`)];
+  const certs = android ? (input.certSha256 ?? []).map(normFp).filter(Boolean) : [];
+  if (certs.length) {
+    const fps = apps.get(match);
+    out.push(
+      certs.some((c) => fps.includes(c))
+        ? ok('cert.listed', "This build's signing certificate is listed")
+        : err('cert.missing', `This build's signing certificate isn't listed for ${app}`, `Add ${certs.join(', ')} in Dashboard → Apps & stores. Debug, release and Play App Signing keys each have their own fingerprint.`),
+    );
+  }
+  return out;
+}
+
+const FILES = { android: 'assetlinks.json', ios: 'apple-app-site-association' };
+
+/** One GET of the platform's well-known file, like the SDKs do. No status = the GET failed. */
+async function fetchFile(fetchImpl, host, platform) {
+  try {
+    const res = await fetchImpl(`https://${host}/.well-known/${FILES[platform]}`, { method: 'GET', signal: AbortSignal.timeout(10_000) });
+    return { status: res.status, body: await res.text() };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Runs the doctor for each platform asked (both when neither app id is given). With no publishable
+ * key the key check is left out rather than failed: the CLI checks the host, the key lives in the app.
+ * @returns {Promise<{ ok: boolean, host: string, android?: object, ios?: object }>}
+ */
+export async function runDoctor({ host, key, android, ios, certs = [], fetch: fetchImpl = fetch }) {
+  const platforms = android || ios ? [android && 'android', ios && 'ios'].filter(Boolean) : ['android', 'ios'];
+  const result = { ok: true, host };
+  await Promise.all(
+    platforms.map(async (platform) => {
+      const file = await fetchFile(fetchImpl, host, platform);
+      const report = doctorFindings({
+        publishableKey: key ?? 'st_pub_',
+        endpoint: `https://${host}`,
+        platform,
+        appId: platform === 'android' ? android : ios,
+        certSha256: platform === 'android' ? certs : [],
+        file,
+      });
+      if (!key) report.findings = report.findings.filter((f) => !f.id.startsWith('key.'));
+      report.ok = !report.findings.some((f) => f.severity === 'error');
+      result[platform] = report;
+      if (!report.ok) result.ok = false;
+    }),
+  );
+  return result;
+}
+
+const LABEL = { android: 'Android (assetlinks.json)', ios: 'iPhone (apple-app-site-association)' };
+
+/** Plain text: the key line once, then each platform's checks with their fixes. */
+export function formatDoctor(result) {
+  const line = (f) => `  ${f.severity.padEnd(5)}  ${f.id.padEnd(17)} ${f.title}${f.fix ? `\n${' '.repeat(27)}Fix: ${f.fix}` : ''}`;
+  const reports = ['android', 'ios'].filter((p) => result[p]);
+  const keyLines = result[reports[0]].findings.filter((f) => f.id.startsWith('key.'));
+  const out = [`Strait doctor for ${result.host}`];
+  if (keyLines.length) out.push('', 'Key', ...keyLines.map(line));
+  for (const p of reports) out.push('', LABEL[p], ...result[p].findings.filter((f) => !f.id.startsWith('key.')).map(line));
+  const warned = reports.some((p) => result[p].findings.some((f) => f.severity === 'warn'));
+  out.push('', !result.ok ? 'Fix the errors above, then run strait doctor again.' : warned ? 'No errors. Check the warnings above.' : 'All checks passed.');
+  out.push("Intent filters and the Associated Domains entitlement aren't visible from here: call doctor() in a debug build, or see https://straitlink.in/tools/.");
+  return out.join('\n');
+}

package/src/install.mjs

@@ -23,8 +23,8 @@ export const sourceFor = (src, registry) => (typeof src.source === 'string' ? sr
 export const VERSIONS = {
   version: '0.9.4', // Swift (Unity is not written by this CLI)
   rnVersion: '0.9.3',
-  flutterVersion: '0.9.3',
-  androidVersion: '0.8.3',
+  flutterVersion: '0.9.4',
+  androidVersion: '0.8.4',
 };
 
 export const PACKAGES = {

package/src/links.mjs

@@ -0,0 +1,104 @@
+// `strait links create|list|qr`: the public link API (https://straitlink.in/docs/api/) with a secret key.
+// The key is read from --secret-key or STRAIT_SECRET_KEY (same name as @straitlink/mcp) and is never
+// printed: anything we print goes through `redact` first.
+import { existsSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { UsageError } from './validate.mjs';
+
+export const DEFAULT_API_URL = 'https://strait.link';
+const SECRET = /^st_(live|test)_[A-Za-z0-9]{8,}$/;
+
+/** A runtime failure (API said no, network down): exit 1 with this message. */
+export class ApiError extends Error {}
+
+/** The secret key for the link API, or a UsageError that says where to get one. Never echoes the value. */
+export function secretKey(value) {
+  const k = String(value ?? '').trim().replace(/^['"]+|['"]+$/g, '').replace(/^Bearer\s+/i, '');
+  const where = 'Create one in Dashboard → Settings → Secret keys and set STRAIT_SECRET_KEY (or pass --secret-key).';
+  if (!k) throw new UsageError(`The link API needs a secret key (st_live_…). ${where}`);
+  if (k.startsWith('st_pub_')) throw new UsageError(`That is the publishable key (st_pub_…), which only works inside apps. The link API needs a secret key (st_live_…). ${where}`);
+  if (!SECRET.test(k)) throw new UsageError(`That is not a secret key (st_live_… or st_test_…). ${where}`);
+  return k;
+}
+
+/** Replaces every Strait secret key in text with its prefix. */
+export const redact = (text, key) => {
+  let s = String(text);
+  if (key) s = s.split(key).join(`${key.slice(0, key.indexOf('_', 3) + 1)}…`);
+  return s.replace(/\bst_(live|test)_[A-Za-z0-9]{8,}/g, 'st_$1_…');
+};
+
+export function apiClient({ apiUrl = DEFAULT_API_URL, key, fetch: fetchImpl = fetch, userAgent }) {
+  const base = String(apiUrl).replace(/\/+$/, '');
+  let parsed;
+  try {
+    parsed = new URL(base);
+  } catch {
+    throw new UsageError(`"${apiUrl}" is not a URL (--api-url / STRAIT_API_URL).`);
+  }
+  if (parsed.protocol !== 'https:' && !['localhost', '127.0.0.1'].includes(parsed.hostname)) {
+    throw new UsageError('--api-url must be https (the secret key travels with every request).');
+  }
+  return async function call(method, path, { query = {}, body, accept = 'application/json' } = {}) {
+    const url = new URL(base + path);
+    for (const [k, v] of Object.entries(query)) if (v !== undefined && v !== '') url.searchParams.set(k, String(v));
+    const headers = { accept, authorization: `Bearer ${key}` };
+    if (body !== undefined) headers['content-type'] = 'application/json';
+    if (userAgent) headers['user-agent'] = userAgent;
+    let res;
+    try {
+      res = await fetchImpl(url, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(30_000) });
+    } catch {
+      throw new ApiError(`Can't reach ${base}. Check your connection, or https://straitlink.in/platform-status/.`);
+    }
+    if (!res.ok) {
+      const text = await res.text();
+      let msg = text.trim().slice(0, 300) || res.statusText;
+      try {
+        const j = JSON.parse(text);
+        if (j && typeof j === 'object' && 'error' in j) msg = typeof j.error === 'string' ? j.error : JSON.stringify(j.error);
+      } catch {
+        // not JSON: keep the text
+      }
+      throw new ApiError(redact(`${method} ${path}: ${msg} (HTTP ${res.status})`, key).replace(/[\u0000-\u0009\u000b-\u001f\u007f]/g, ''));
+    }
+    return res;
+  };
+}
+
+const enc = encodeURIComponent;
+
+/** @returns {Promise<string>} what to print */
+export async function linksCommand(sub, positionals, v, { call, cwd }) {
+  if (sub === 'create') {
+    const [slug, longUrl] = positionals;
+    if (!slug || !longUrl) throw new UsageError('Usage: strait links create <slug> <url> [--title …] [--campaign …] [--tag …]');
+    const body = { slug, longUrl };
+    if (v.title) body.title = v.title;
+    if (v.campaign) body.campaign = v.campaign;
+    if (v.tag?.length) body.tags = v.tag;
+    const link = await (await call('POST', '/v1/links', { body })).json();
+    return v.json ? JSON.stringify(link, null, 2) : `Created ${link.shortUrl}\n  → ${link.longUrl}`;
+  }
+  if (sub === 'list') {
+    const page = await (await call('GET', '/v1/links', { query: { limit: v.limit, cursor: v.cursor, status: v.status } })).json();
+    if (v.json) return JSON.stringify(page, null, 2);
+    const rows = (page.links ?? []).map((l) => `${l.shortUrl}  ${l.longUrl}${l.isActive === false ? '  (paused)' : ''}`);
+    if (!rows.length) rows.push('No links yet. Create one: strait links create <slug> <url>');
+    if (page.nextCursor) rows.push('', `More: strait links list --cursor ${page.nextCursor}`);
+    return rows.join('\n');
+  }
+  if (sub === 'qr') {
+    const [slug] = positionals;
+    if (!slug) throw new UsageError('Usage: strait links qr <slug> [--format png|svg] [--size 512] [--out file]');
+    const format = v.format ?? 'png';
+    if (!['png', 'svg'].includes(format)) throw new UsageError('--format is png or svg.');
+    const out = resolve(cwd, v.out ?? `${slug.replace(/[^A-Za-z0-9._-]/g, '_')}.${format}`);
+    if (existsSync(out) && !v.force) throw new UsageError(`${out} already exists. Pass --force to replace it, or --out to pick another file.`);
+    const res = await call('GET', `/v1/links/${enc(slug)}/qr`, { query: { format: v.format, size: v.size }, accept: format === 'svg' ? 'image/svg+xml' : 'image/png' });
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    writeFileSync(out, bytes);
+    return `Saved the QR code for ${slug} to ${out} (${bytes.byteLength} bytes).`;
+  }
+  throw new UsageError(`strait links takes create, list or qr${sub ? `, not "${sub}"` : ''}.`);
+}

package/src/version.mjs

@@ -0,0 +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.0';