toolaby 1.1.0 → 1.3.0

package/README.md

@@ -3,11 +3,13 @@
 The Toolaby command line. It puts the Wall — sign-in, a Free plan, paid plans, licences and subscriptions — into a Chrome extension you already have, or makes a new one for you.
 
 ```sh
-npm i -g toolaby            # once (or run every command through `npx -y toolaby …`)
-toolaby login               # once: a code to approve in your browser
-toolaby wire <tool-id>      # in your extension's folder; `toolaby tools` lists your ids
+npm i -g toolaby              # once (or run every command through `npx -y toolaby …`)
+toolaby wire <tool-id>        # in your extension's folder, on Test; signs you in first if it must
+toolaby wire <tool-id> --live # the same, on Live: the store build
 ```
 
+Every command acts on the test Wall (`test.toolaby.app`) unless told `--live` (`toolaby.app`), as Stripe's command line does. `toolaby tools` lists your ids on either side.
+
 ## What it does
 
 **`toolaby login`** signs you in. It shows a code and opens the Toolaby dashboard; you approve the code there — as the account the dashboard is signed in to — and the command is signed in as that account from then on. It works the way GitHub's and Stripe's command lines sign in, and only ever acts on that account's own tools.
@@ -27,6 +29,6 @@ If the extension is built with WXT, CRXJS or Plasmo, the command puts the same f
 ## Where things live
 
 - Your session: `~/.config/toolaby/credentials.json`, readable by you alone (mode 600). `toolaby logout` deletes it after revoking it.
-- `TOOLABY_TOKEN` stands in for the file where there is no home directory (CI). `TOOLABY_WALL` or `--wall <url>` names another Wall (the default is `https://toolaby.app`).
+- The session is per side. `TOOLABY_TOKEN` stands in for the file where there is no home directory (CI). `TOOLABY_WALL` or `--wall <url>` names any other Wall.
 
 The files the command writes into your extension contain nothing secret: your tool's id, your Wall's address and the *public* key your extension verifies licences with — the same things every copy of your extension carries once it is published.

package/bin.mjs

@@ -5,14 +5,20 @@
 //   toolaby wire <tool-id>            wire the extension in this folder to your tool — plain, WXT, CRXJS or Plasmo
 //   toolaby create <tool-id>          make a new, minimal extension for your tool in <tool-id>/
 //   toolaby tools                     your tools, with the ids the commands want
+//   toolaby webhooks events           the six events, with an example of each
+//   toolaby webhooks trigger <event>  send an example delivery: to your registered endpoints, or with --to straight to a local server
 //   toolaby whoami · logout · help
 //
+// Test and live, as Stripe's command line has them: every command acts on
+// the TEST Wall (test.toolaby.app) unless told `--live`, so the everyday
+// command is the safe one and going live is a word you type on purpose.
 // Signed in, the command acts as you and only on your tools, as Clerk's and
 // Stripe's do: nothing is fetched for a tool your workspaces do not own. The
 // session lives in ~/.config/toolaby/credentials.json (mode 600), one per
-// Wall; `logout` revokes it on the server before forgetting it. TOOLABY_TOKEN
-// stands in for the file where there is no home (CI); TOOLABY_WALL for the
-// Wall's address (https://toolaby.app unless told).
+// side; a command that needs one and has none signs you in on the spot.
+// `logout` revokes it on the server before forgetting it. TOOLABY_TOKEN
+// stands in for the file where there is no home (CI); TOOLABY_WALL or
+// `--wall <url>` names any other Wall (a laptop's, a self-hosted one).
 //
 // The wiring rules — what a folder is and what its manifest needs — are the
 // platform's own (wall/src/packages/wiring), carried here transpiled in lib/,
@@ -21,10 +27,11 @@ import { mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync, statSy
 import { join, resolve, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { spawn } from 'node:child_process';
+import { createHmac, randomBytes } from 'node:crypto';
 import { wireManifest, WORKER_LINES } from './lib/manifest.js';
 import { detectProject, CODE_FILES, filesToWrite, BUILD_COPY_NOTE } from './lib/project.js';
 
-const VERSION = '1.1.0';
+const VERSION = '1.3.0';
 const CLIENT_ID = 'toolaby-cli';
 const argv = process.argv.slice(2);
 // `--version` and `--help` are commands of their own; every other command is the first bare word.
@@ -33,7 +40,11 @@ const rest = argv.filter((a) => a !== command);
 const positional = rest.filter((a) => !a.startsWith('--'));
 const opt = (k, d = null) => { const i = rest.indexOf(k); return i >= 0 && rest[i + 1] && !rest[i + 1].startsWith('--') ? rest[i + 1] : d; };
 const flag = (k) => rest.includes(k);
-const wall = (opt('--wall') ?? process.env.TOOLABY_WALL ?? 'https://toolaby.app').replace(/\/$/, '');
+const WALLS = { test: 'https://test.toolaby.app', live: 'https://toolaby.app' };
+const live = flag('--live');
+const wall = (opt('--wall') ?? process.env.TOOLABY_WALL ?? (live ? WALLS.live : WALLS.test)).replace(/\/$/, '');
+/** The side, for every message: what a developer must never be unsure of. */
+const side = wall === WALLS.live ? 'Live' : wall === WALLS.test ? 'Test' : wall;
 const out = (s = '') => console.log(s);
 const fail = (s) => { console.error(`\n  ${s}\n`); process.exit(1); };
 
@@ -72,7 +83,7 @@ async function login() {
   const { device_code, user_code, verification_uri, verification_uri_complete, interval = 5, expires_in = 600 } = start.json;
   const link = verification_uri_complete || `${verification_uri}?user_code=${encodeURIComponent(user_code)}`;
   const page = link.startsWith('http') ? link : `${wall}${link}`;
-  out(`\n  Sign in to the Wall to continue.\n\n    Open   ${page}\n    Code   ${user_code}   (approve it there — it expires in ${Math.round(expires_in / 60)} minutes)\n`);
+  out(`\n  Sign in to the ${side} Wall to continue.\n\n    Open   ${page}\n    Code   ${user_code}   (approve it there — it expires in ${Math.round(expires_in / 60)} minutes)\n`);
   openBrowser(page);
   let every = Math.max(1, Number(interval) || 5) * 1000;
   const until = Date.now() + Number(expires_in) * 1000;
@@ -88,7 +99,7 @@ async function login() {
       const all = readCredentials();
       all[wall] = { token, email, at: new Date().toISOString() };
       writeCredentials(all);
-      out(`\n\n  Signed in${email ? ` as ${email}` : ''}.\n`);
+      out(`\n\n  Signed in${email ? ` as ${email}` : ''} · ${side}.\n`);
       return token;
     }
     const why = poll.json.error;
@@ -107,11 +118,11 @@ async function tokenOrLogin() {
 
 async function whoami() {
   const token = storedToken();
-  if (!token) fail(`Not signed in to ${wall}. Run \`toolaby login\`.`);
+  if (!token) fail(`Not signed in to ${side} (${wall}). Run \`toolaby login${live ? ' --live' : ''}\`.`);
   const me = await api('/api/cli/me', { token });
   if (me.status === 401) fail(`The session for ${wall} is no longer valid. Run \`toolaby login\`.`);
   if (!me.ok) fail(`The Wall answered HTTP ${me.status}.`);
-  out(`\n  ${me.json.email}  ·  ${wall}\n`);
+  out(`\n  ${me.json.email}  ·  ${side}  ·  ${wall}\n`);
   for (const w of me.json.workspaces) out(`    ${w.name}  (${w.slug}, ${w.role})  ${w.site}`);
   out();
 }
@@ -119,22 +130,22 @@ async function whoami() {
 async function logout() {
   const all = readCredentials();
   const entry = all[wall];
-  if (!entry && !process.env.TOOLABY_TOKEN) { out(`\n  Not signed in to ${wall}.\n`); return; }
+  if (!entry && !process.env.TOOLABY_TOKEN) { out(`\n  Not signed in to ${side} (${wall}).\n`); return; }
   // Revoked on the server first; forgotten here whatever the server said — but the difference is reported.
   const res = await api('/api/dev-auth/sign-out', { method: 'POST', body: {}, token: entry?.token ?? process.env.TOOLABY_TOKEN }).catch(() => ({ ok: false, status: 0 }));
   delete all[wall];
   writeCredentials(all);
-  out(res.ok ? `\n  Signed out of ${wall}: the session was revoked and forgotten.\n` : `\n  The session was forgotten here, but the Wall could not be reached to revoke it (HTTP ${res.status}); it expires on its own, or sign it out from the dashboard.\n`);
+  out(res.ok ? `\n  Signed out of ${side} (${wall}): the session was revoked and forgotten.\n` : `\n  The session was forgotten here, but the Wall could not be reached to revoke it (HTTP ${res.status}); it expires on its own, or sign it out from the dashboard.\n`);
   if (process.env.TOOLABY_TOKEN) out('  TOOLABY_TOKEN is set in this shell and still authenticates.\n');
 }
 
 async function tools() {
   const token = await tokenOrLogin();
   const res = await api('/api/cli/tools', { token });
-  if (res.status === 401) fail(`The session for ${wall} is no longer valid. Run \`toolaby login\`.`);
+  if (res.status === 401) fail(`The session for ${side} is no longer valid. Run \`toolaby login${live ? ' --live' : ''}\`.`);
   if (!res.ok) fail(`The Wall answered HTTP ${res.status}.`);
-  if (!res.json.tools.length) { out('\n  No tools yet. Make one in the dashboard, then `toolaby wire <tool-id>` in your extension\'s folder.\n'); return; }
-  out();
+  if (!res.json.tools.length) { out(`\n  No tools on ${side} yet. Make one in the dashboard, then \`toolaby wire <tool-id>${live ? ' --live' : ''}\` in your extension's folder.\n`); return; }
+  out(`\n  ${side}\n`);
   for (const t of res.json.tools) out(`    ${t.slug.padEnd(40)} ${t.name}${t.bundle ? '  (bundle)' : ''}   ${t.site}`);
   out();
 }
@@ -212,7 +223,7 @@ async function wire() {
     ownWorker = { file: project.worker, classic: false };
   }
 
-  out(`\n  ${plan.name} → ${dir}${project.kind === 'plain' ? '' : `  (${project.label})`}\n`);
+  out(`\n  ${plan.name} → ${dir}${project.kind === 'plain' ? '' : `  (${project.label})`}  ·  ${side}${side === 'Test' ? ' (the tk_test_ key; `--live` for the store build)' : ''}\n`);
   out(`  Written: ${targets.join(', ')}${did.length ? `,\n           ${did.join(',\n           ')}` : ''}.\n`);
   for (const sn of project.snippets) out(`  Add to ${sn.file} — yours to paste, the manifest being generated:\n\n${sn.code.split('\n').map((l) => `     ${l}`).join('\n')}\n`);
   if (ownWorker) out(`  Your background, ${ownWorker.file}: add${ownWorker.classic ? ' — after giving "background" a "type": "module" in manifest.json (importScripts() is not available in a module worker)' : ''}:\n\n${project.workerLines.trimEnd().split('\n').map((l) => `     ${l}`).join('\n')}\n`);
@@ -238,22 +249,82 @@ async function create() {
   out(`\n  ${plan.name} → ${dir}\n\n    1. chrome://extensions → Developer mode → Load unpacked → ${dir}\n    2. Click the icon: the popup shows what the Free plan holds; Buy opens ${plan.site}/tools/${slug}\n\n  Edit background.js: your work goes behind toolaby.gate().\n`);
 }
 
+// ── webhooks: the catalogue, and a delivery on demand ───────────────────────────────────────────────────────────────
+//
+// `trigger <event>` sends the catalogue's example of the event through the
+// Wall to every endpoint the workspace registered — signed, logged, retried,
+// as a real one. `trigger <event> --to <url>` skips the Wall: the command
+// signs the example itself, Standard Webhooks style, with a secret you name
+// (or one it prints) and POSTs it to the URL — a server on localhost, no
+// tunnel, no deploy — so a handler can be written and run before anything
+// is registered.
+const DEV_SECRET = 'whsec_dG9vbGFieS1kZXYtd2ViaG9vay1zZWNyZXQtMDAwMQ==';
+async function catalogue() {
+  const res = await api('/api/cli/webhooks/events', { token: await tokenOrLogin() });
+  if (res.status === 401) fail(`The session for ${side} is no longer valid. Run \`toolaby login${live ? ' --live' : ''}\`.`);
+  if (!res.ok) fail(`The Wall answered HTTP ${res.status}.`);
+  return res.json.events;
+}
+async function webhooks() {
+  const sub = positional[0];
+  if (sub === 'events') {
+    const events = await catalogue();
+    out(`\n  ${side}\n`);
+    for (const e of events) out(`    ${e.type.padEnd(26)} ${e.description}`);
+    out(`\n  toolaby webhooks trigger <event>            → your registered endpoints\n  toolaby webhooks trigger <event> --to <url>  → a local server, signed with a secret you name\n`);
+    return;
+  }
+  if (sub === 'trigger') {
+    const type = positional[1];
+    if (!type) fail('usage: toolaby webhooks trigger <event> [--to <url>] [--secret <whsec_…>]   — `toolaby webhooks events` lists them');
+    const to = opt('--to');
+    if (!to) {
+      const res = await api('/api/cli/webhooks/trigger', { method: 'POST', body: { type }, token: await tokenOrLogin() });
+      if (!res.ok) fail(res.json.message ?? `The Wall answered HTTP ${res.status}.`);
+      out(`\n  Sent ${res.json.sent} to every endpoint of ${res.json.workspace} · ${side}. Its id is ${res.json.id}; the delivery log is under Configure → API.\n`);
+      return;
+    }
+    const events = await catalogue();
+    const event = events.find((e) => e.type === type);
+    if (!event) fail(`No event "${type}". \`toolaby webhooks events\` lists them.`);
+    const secret = opt('--secret') ?? DEV_SECRET;
+    if (!/^whsec_[A-Za-z0-9+/=]+$/.test(secret)) fail('--secret must be a Standard Webhooks secret: whsec_ followed by base64.');
+    const id = `msg_${randomBytes(12).toString('base64url')}`;
+    const timestamp = Math.floor(Date.now() / 1000);
+    const body = JSON.stringify({ id: `evt_${type.replace('.', '_')}_${Date.now().toString(36)}`, type, created: timestamp, livemode: false, data: event.example });
+    const signature = 'v1,' + createHmac('sha256', Buffer.from(secret.slice(6), 'base64')).update(`${id}.${timestamp}.${body}`).digest('base64');
+    let res;
+    try {
+      res = await fetch(to, { method: 'POST', headers: { 'Content-Type': 'application/json', 'webhook-id': id, 'webhook-timestamp': String(timestamp), 'webhook-signature': signature, 'User-Agent': `toolaby-cli/${VERSION}` }, body });
+    } catch (e) { fail(`Could not reach ${to}: ${e.message}`); }
+    const text = (await res.text()).slice(0, 200);
+    out(`\n  POST ${to}  →  ${res.status}${text ? `  ${text.replace(/\s+/g, ' ')}` : ''}`);
+    out(`  ${type}, signed with ${opt('--secret') ? 'your secret' : `${DEV_SECRET} — set WALL_WEBHOOK_SECRET to it to verify`}.\n`);
+    if (res.status >= 300) out('  A real delivery would be retried until your server answers 2xx.\n');
+    return;
+  }
+  fail('usage: toolaby webhooks events | trigger <event> [--to <url>] [--secret <whsec_…>]');
+}
+
 function help() {
   out(`
   toolaby — the Toolaby command line (${VERSION})
 
-    toolaby login                      sign in: a code to approve in the browser
-    toolaby wire <tool-id>             wire the extension in this folder to your tool
+    toolaby wire <tool-id>             wire the extension in this folder to your tool, on Test
+    toolaby wire <tool-id> --live      the same, on Live: the store build
                                        --into <folder>   another folder     --force   replace the platform's files
     toolaby create <tool-id>           a new, minimal extension for your tool, in <tool-id>/   --dir <folder>
     toolaby tools                      your tools, with their ids
-    toolaby whoami · logout
+    toolaby webhooks events            the six events, with an example of each
+    toolaby webhooks trigger <event>   an example delivery to your endpoints; --to <url> sends it to a local server instead
+    toolaby login · whoami · logout    the session, per side; a command that needs one signs you in itself
 
-    --wall <url>   the Wall to talk to (https://toolaby.app; TOOLABY_WALL)      TOOLABY_TOKEN   a session, for CI
+    Every command acts on Test (test.toolaby.app) unless told --live (toolaby.app).
+    --wall <url> or TOOLABY_WALL names any other Wall; TOOLABY_TOKEN a session, for CI.
 `);
 }
 
-const commands = { login: async () => { await login(); }, logout, whoami, tools, wire, create, help, '--help': help, '-h': help, '--version': () => out(VERSION), '-v': () => out(VERSION) };
+const commands = { login: async () => { await login(); }, logout, whoami, tools, wire, create, webhooks, help, '--help': help, '-h': help, '--version': () => out(VERSION), '-v': () => out(VERSION) };
 const run = commands[command];
 if (!run) { console.error(`\n  Unknown command "${command}".`); help(); process.exit(1); }
 Promise.resolve().then(run).catch((e) => fail(e.message));

package/lib/manifest.js

@@ -22,7 +22,7 @@ export function wireManifest(input, o) {
     const own = typeof manifest.key === 'string' && manifest.key.trim() ? manifest.key.trim() : null;
     if (!own && o.manifestKey) {
         manifest.key = o.manifestKey;
-        did.push('a "key", so the extension keeps one id and the platform knows it');
+        did.push('a "key", so the extension keeps one id across reloads and machines');
     }
     const manifestKey = own ?? o.manifestKey ?? null;
     const add = (list, value) => { const arr = Array.isArray(list) ? [...list] : []; if (!arr.includes(value))

package/lib/project.js

@@ -3,12 +3,15 @@
 export const BUILD_COPY_NOTE = 'A build ships this extension: make sure it copies the platform\'s files to its output — toolaby.js, toolaby.config.js, toolaby-client.module.js, paywall.js, paywall.css and toolaby-popup.* — the way it copies your popup.html.';
 /** Always written, where the build imports from: the client, its config and types, and the panel a popup of the developer's own can draw. */
 export const CODE_FILES = ['toolaby.config.js', 'toolaby.js', 'toolaby-client.module.js', 'toolaby.d.ts', 'paywall.js', 'paywall.css'];
+/** Beside the client when the build generates the manifest: the fragment it spreads in, derived from the key (boilerplate/toolaby.manifest.js). */
+export const MANIFEST_HELPER = ['toolaby.manifest.js', 'toolaby.manifest.d.ts'];
 /** The Wall's popup, where the build copies files as they are; it imports the panel beside it, so the panel goes there too when that is elsewhere. */
 export const POPUP_FILES = ['toolaby-popup.html', 'toolaby-popup.js', 'toolaby-popup.css'];
 export const PANEL_FILES = ['paywall.js', 'paywall.css'];
 /** Every file a wiring writes, with its path: the code files, and — with a popup to stand in front of — the Wall's popup and, beside it, the panel. */
 export const filesToWrite = (p, appPopup) => [
     ...CODE_FILES.map((f) => `${p.codeDir}${f}`),
+    ...(p.manifestFile ? [] : MANIFEST_HELPER.map((f) => `${p.codeDir}${f}`)),
     ...(appPopup ? [...POPUP_FILES, ...(p.popupDir !== p.codeDir ? PANEL_FILES : [])].map((f) => `${p.popupDir}${f}`) : []),
 ];
 /** The import of toolaby.js from a file at `from`, both relative to the root. */
@@ -21,7 +24,6 @@ const dep = (pkg, name) => !!(pkg?.dependencies?.[name] || pkg?.devDependencies?
 const first = (has, candidates) => candidates.find(has) ?? null;
 export function detectProject(o) {
     const { has, packageJson: pkg, manifest, site } = o;
-    const keyLine = o.manifestKey ? `key: '${o.manifestKey}',` : null;
     const scripts = pkg?.scripts ?? {};
     const built = !!scripts.build || has('dist') || has('build');
     const wxt = dep(pkg, 'wxt') || !!first(has, ['wxt.config.ts', 'wxt.config.js', 'wxt.config.mts', 'wxt.config.mjs']);
@@ -36,14 +38,11 @@ export function detectProject(o) {
         const workerFile = worker ?? `${src}entrypoints/background.ts`;
         const workerLines = `import { toolaby } from '${importPath(workerFile)}';\n\nexport default defineBackground(() => {\n  toolaby.startBackground();\n});\n`;
         const code = [
-            `// wxt.config.ts — what the Wall needs in the manifest${appPopup ? ', and its popup in front of yours' : ''}`,
+            `// wxt.config.ts — the Wall's needs in the manifest come from toolaby.config.js${appPopup ? ', and its popup goes in front of yours' : ''}`,
+            `import { manifest as toolaby } from './toolaby.manifest.js';`,
+            ``,
             `export default defineConfig({`,
-            `  manifest: {`,
-            ...(keyLine ? [`    ${keyLine} // the extension's id, known to the platform`] : []),
-            `    permissions: ['storage'],`,
-            `    host_permissions: ['${site}/*'],`,
-            `    externally_connectable: { matches: ['${site}/*'] },`,
-            `  },`,
+            `  manifest: { ...toolaby }, // the extension's id, the storage permission, the Wall's address`,
             ...(appPopup ? [
                 `  hooks: {`,
                 `    // WXT names your popup entrypoint after merging the manifest above; the hook runs after that.`,
@@ -85,11 +84,10 @@ export function detectProject(o) {
         const workerFile = worker ?? 'src/background.ts';
         const workerLines = `import { toolaby } from '${importPath(workerFile)}';\n\ntoolaby.startBackground();\n`;
         const code = [
-            `// ${configFile ?? 'manifest.config.ts'} — add inside defineManifest({ … })`,
-            ...(keyLine && !/\bkey:/.test(source) ? [`${keyLine} // the extension's id, known to the platform`] : []),
-            `permissions: ['storage'],`,
-            `host_permissions: ['${site}/*'],`,
-            `externally_connectable: { matches: ['${site}/*'] },`,
+            `// ${configFile ?? 'manifest.config.ts'} — the Wall's needs come from toolaby.config.js: import once, spread inside defineManifest({ … })`,
+            `import { manifest as toolaby } from '${importPath(configFile ?? 'manifest.config.ts').replace(/toolaby\.js$/, 'toolaby.manifest.js')}';`,
+            ``,
+            `...toolaby, // the extension's id, the storage permission, the Wall's address`,
             ...(appPopup ? [`action: { default_popup: 'toolaby-popup.html' },`] : []),
             ...(worker ? [] : [`background: { service_worker: '${workerFile}', type: 'module' },`]),
         ].join('\n');

package/package.json

@@ -1,13 +1,30 @@
 {
   "name": "toolaby",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "The Toolaby command line: sign in once, then wire any Chrome extension to your tool on the Wall — sign-in, the Free plan, licences and subscriptions — or start a new one.",
   "type": "module",
-  "bin": { "toolaby": "./bin.mjs" },
-  "files": ["bin.mjs", "lib", "README.md"],
-  "engines": { "node": ">=18" },
-  "keywords": ["chrome-extension", "toolaby", "licensing", "cli"],
+  "bin": {
+    "toolaby": "bin.mjs"
+  },
+  "files": [
+    "bin.mjs",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "chrome-extension",
+    "toolaby",
+    "licensing",
+    "cli"
+  ],
   "homepage": "https://toolaby.app",
-  "repository": { "type": "git", "url": "https://github.com/miltostave/Toolaby.git", "directory": "packages/toolaby-cli" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/miltostave/Toolaby.git",
+    "directory": "packages/toolaby-cli"
+  },
   "license": "MIT"
 }