@hypersocial/decks-cli 0.1.0 → 0.1.1

package/README.md

@@ -65,6 +65,6 @@ customer-facing share management.
 Use dev only for local implementation/testing:
 
 ```bash
-decks --dev --broker https://decks.localhost whoami
-HSDECKS_PROD=0 HSDECKS_BROKER_BASE=https://decks.localhost decks whoami
+decks --dev --convex https://your-dev.convex.cloud --broker https://decks.localhost whoami
+HSDECKS_PROD=0 HSDECKS_CONVEX_URL=https://your-dev.convex.cloud HSDECKS_BROKER_BASE=https://decks.localhost decks whoami
 ```

package/bin/decks.mjs

@@ -1,500 +1,4 @@
 #!/usr/bin/env node
-import { execFile } from "node:child_process";
-import { createHash, randomBytes } from "node:crypto";
-import { createServer } from "node:http";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { ConvexHttpClient } from "convex/browser";
-import { makeFunctionReference } from "convex/server";
+import { runCli } from "../src/commands.mjs";
 
-const VERSION = "0.1.0";
-
-const PROD = {
-  name: "prod",
-  convexUrl: "https://dashing-snail-874.convex.cloud",
-  brokerBase: "https://decks.hypersocial.ai",
-  shareBase: "https://decks.hypersocial.ai",
-};
-
-const BOOL = new Set(["prod", "dev", "json", "require-email", "help", "version"]);
-
-const api = {
-  activity: {
-    overview: makeFunctionReference("activity:overview"),
-    setArchived: makeFunctionReference("activity:setArchived"),
-  },
-  cliCredentials: {
-    revokeByHash: makeFunctionReference("cliCredentials:revokeByHash"),
-  },
-  decks: {
-    listForViewer: makeFunctionReference("decks:listForViewer"),
-    whoami: makeFunctionReference("decks:whoami"),
-  },
-  shares: {
-    create: makeFunctionReference("shares:create"),
-    deckAnalytics: makeFunctionReference("shares:deckAnalytics"),
-    listForDeck: makeFunctionReference("shares:listForDeck"),
-    remove: makeFunctionReference("shares:remove"),
-    setEnabled: makeFunctionReference("shares:setEnabled"),
-  },
-};
-
-const CRED_DIR = join(homedir(), ".config", "hypersocial-decks");
-const CRED_FILE = join(CRED_DIR, "credentials.json");
-
-function parse(args) {
-  const opts = {};
-  const pos = [];
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a.startsWith("--")) {
-      const k = a.slice(2);
-      if (BOOL.has(k)) opts[k] = true;
-      else opts[k] = args[++i];
-    } else {
-      pos.push(a);
-    }
-  }
-  return { pos, opts };
-}
-
-function normalizeBase(url) {
-  return String(url || "").replace(/\/$/, "");
-}
-
-function target(opts = {}) {
-  const envWantsDev = process.env.HSDECKS_PROD === "0";
-  const wantDev = opts.dev || (envWantsDev && !opts.prod);
-  if (!wantDev) {
-    return {
-      ...PROD,
-      brokerBase: normalizeBase(opts.broker || PROD.brokerBase),
-    };
-  }
-
-  const convexUrl = opts.convex || process.env.HSDECKS_CONVEX_URL || process.env.CONVEX_URL;
-  if (!convexUrl) {
-    throw new Error("dev target needs --convex <url>, HSDECKS_CONVEX_URL, or CONVEX_URL");
-  }
-  return {
-    name: "dev",
-    convexUrl,
-    brokerBase: normalizeBase(opts.broker || process.env.HSDECKS_BROKER_BASE || "http://localhost:3000"),
-    shareBase: normalizeBase(process.env.HSDECKS_SHARE_BASE || "https://decks.localhost"),
-  };
-}
-
-function loadCreds() {
-  if (!existsSync(CRED_FILE)) return {};
-  try {
-    return JSON.parse(readFileSync(CRED_FILE, "utf8"));
-  } catch {
-    return {};
-  }
-}
-
-function saveCred(name, cred) {
-  const all = loadCreds();
-  all[name] = cred;
-  mkdirSync(CRED_DIR, { recursive: true, mode: 0o700 });
-  writeFileSync(CRED_FILE, JSON.stringify(all, null, 2), { mode: 0o600 });
-}
-
-function clearCred(name) {
-  const all = loadCreds();
-  const removed = all[name];
-  delete all[name];
-  mkdirSync(CRED_DIR, { recursive: true, mode: 0o700 });
-  writeFileSync(CRED_FILE, JSON.stringify(all, null, 2), { mode: 0o600 });
-  return removed;
-}
-
-const sha256Hex = (s) => createHash("sha256").update(s, "utf8").digest("hex");
-
-function resolveRefreshToken(t, opts) {
-  if (opts.token) return opts.token;
-  if (process.env.HSDECKS_TOKEN) return process.env.HSDECKS_TOKEN;
-  return loadCreds()[t.name]?.refreshToken || null;
-}
-
-async function mintJwt(brokerBase, refreshToken) {
-  let res;
-  try {
-    res = await fetch(`${brokerBase}/api/cli/token`, {
-      method: "POST",
-      headers: { authorization: `Bearer ${refreshToken}` },
-      signal: AbortSignal.timeout(15000),
-    });
-  } catch (e) {
-    const msg = String(e?.message || e);
-    if (e?.name === "TimeoutError" || /timeout/i.test(msg)) {
-      throw new Error(`broker at ${brokerBase} did not respond within 15s`);
-    }
-    throw new Error(`could not reach broker at ${brokerBase} (${msg})`);
-  }
-
-  if (!res.ok) {
-    const body = await res.text().catch(() => "");
-    throw new Error(`auth exchange failed (${res.status}) ${body.slice(0, 200)}`);
-  }
-  return res.json();
-}
-
-const jwtCache = new Map();
-async function jwtFor(brokerBase, refreshToken) {
-  const hit = jwtCache.get(refreshToken);
-  if (hit && hit.expiresAt - Date.now() > 60000) return hit.token;
-  const { token, expiresAt } = await mintJwt(brokerBase, refreshToken);
-  jwtCache.set(refreshToken, { token, expiresAt });
-  return token;
-}
-
-async function client(opts = {}) {
-  const t = target(opts);
-  const c = new ConvexHttpClient(t.convexUrl);
-  const refreshToken = resolveRefreshToken(t, opts);
-  if (!refreshToken) {
-    throw new Error(`not authenticated for ${t.name} - run \`decks login${t.name === "dev" ? " --dev" : ""}\``);
-  }
-  c.setAuth(await jwtFor(t.brokerBase, refreshToken));
-  return c;
-}
-
-function openBrowser(url) {
-  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
-  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
-  execFile(cmd, args, () => {});
-}
-
-async function verifyAndStampEmail(t, opts) {
-  const c = await client(opts);
-  const who = await c.query(api.decks.whoami, {});
-  if (!who) throw new Error("credential was rejected by Convex");
-  const cur = loadCreds()[t.name] || {};
-  saveCred(t.name, { ...cur, email: who.email });
-  return who;
-}
-
-async function login(opts) {
-  const t = target(opts);
-
-  if (opts.token) {
-    saveCred(t.name, { refreshToken: opts.token, convexUrl: t.convexUrl, brokerBase: t.brokerBase });
-    try {
-      const who = await verifyAndStampEmail(t, opts);
-      console.log(`OK logged in to ${t.name}${who.email ? ` as ${who.email}` : ""}`);
-    } catch (e) {
-      clearCred(t.name);
-      throw e;
-    }
-    return;
-  }
-
-  const state = randomBytes(16).toString("hex");
-  await new Promise((resolve, reject) => {
-    let timer;
-    let done = false;
-    let server;
-    const finish = (err) => {
-      if (done) return;
-      done = true;
-      clearTimeout(timer);
-      server.close();
-      err ? reject(err) : resolve();
-    };
-
-    server = createServer((req, res) => {
-      res.setHeader("Access-Control-Allow-Origin", t.brokerBase);
-      res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
-      res.setHeader("Access-Control-Allow-Headers", "content-type");
-      if (req.method === "OPTIONS") {
-        res.writeHead(204);
-        res.end();
-        return;
-      }
-      if (req.method === "POST" && (req.url || "").startsWith("/callback")) {
-        let body = "";
-        req.on("data", (d) => (body += d));
-        req.on("end", () => {
-          try {
-            const { refreshToken, state: got } = JSON.parse(body || "{}");
-            if (got !== state) throw new Error("state mismatch");
-            if (!refreshToken) throw new Error("no token returned");
-            saveCred(t.name, { refreshToken, convexUrl: t.convexUrl, brokerBase: t.brokerBase });
-            res.writeHead(200, { "content-type": "application/json" });
-            res.end(JSON.stringify({ ok: true }));
-            finish();
-          } catch (e) {
-            res.writeHead(400);
-            res.end(String(e?.message || e));
-            finish(e);
-          }
-        });
-        return;
-      }
-      res.writeHead(404);
-      res.end();
-    });
-
-    server.listen(0, "127.0.0.1", () => {
-      const { port } = server.address();
-      const url = `${t.brokerBase}/cli/authorize?port=${port}&state=${state}`;
-      console.log(`Opening your browser to sign in (${t.name})...\n  ${url}\nIf it does not open, paste that URL into your browser.`);
-      openBrowser(url);
-    });
-    timer = setTimeout(() => finish(new Error("login timed out after 3 min")), 180000);
-  });
-
-  const who = await verifyAndStampEmail(t, opts);
-  console.log(`OK logged in to ${t.name}${who.email ? ` as ${who.email}` : ""}`);
-}
-
-async function logout(opts) {
-  const t = target(opts);
-  const cur = loadCreds()[t.name];
-  if (!cur?.refreshToken) {
-    console.log(`not logged in to ${t.name}`);
-    return;
-  }
-  try {
-    const anon = new ConvexHttpClient(t.convexUrl);
-    await anon.mutation(api.cliCredentials.revokeByHash, { tokenHash: sha256Hex(cur.refreshToken) });
-  } catch {
-    // Still clear local credential if the network is unavailable.
-  }
-  clearCred(t.name);
-  console.log(`OK logged out of ${t.name}`);
-}
-
-async function whoami(opts) {
-  const t = target(opts);
-  const who = await (await client(opts)).query(api.decks.whoami, {});
-  if (opts.json) {
-    console.log(JSON.stringify({ ...(who || {}), deployment: t.name, convexUrl: t.convexUrl }, null, 2));
-    return;
-  }
-  if (!who) {
-    console.log(`not authenticated (${t.name})`);
-    return;
-  }
-  console.log(`email:      ${who.email}`);
-  console.log(`subject:    ${who.subject}`);
-  console.log(`isAdmin:    ${who.isAdmin}`);
-  console.log(`deployment: ${t.name} (${t.convexUrl})`);
-}
-
-const fmtMs = (ms) => (ms >= 60000 ? `${(ms / 60000).toFixed(1)}m` : `${Math.round(ms / 1000)}s`);
-
-async function deckList(opts) {
-  const rows = await (await client(opts)).query(api.decks.listForViewer, {});
-  const slim = rows.map((d) => ({
-    slug: d.slug,
-    title: d.title,
-    status: d.status,
-    ownerEmail: d.ownerEmail ?? null,
-    hasHtml: !!d.html,
-  }));
-  if (opts.json) {
-    console.log(JSON.stringify(slim, null, 2));
-    return;
-  }
-  for (const d of slim) console.log(`${d.slug}\t${d.status}\t${d.title}`);
-  if (!slim.length) console.log("(no decks)");
-}
-
-async function deckStats(pos, opts) {
-  const [slug] = pos;
-  if (!slug) throw new Error("usage: deck stats <slug>");
-  const s = await (await client(opts)).query(api.shares.deckAnalytics, { deckSlug: slug });
-  if (opts.json) {
-    console.log(JSON.stringify(s, null, 2));
-    return;
-  }
-  console.log(`deck "${slug}"`);
-  console.log(`  views:          ${s.views}`);
-  console.log(`  visits:         ${s.visits}`);
-  console.log(`  unique viewers: ${s.viewers}`);
-  console.log(`  avg engaged:    ${fmtMs(s.avgMs)}`);
-  console.log(`  total engaged:  ${fmtMs(s.totalMs)}`);
-  if (s.recent?.length) {
-    console.log("  recent:");
-    for (const r of s.recent) {
-      const where = [r.city, r.country].filter(Boolean).join(", ");
-      console.log(`    ${new Date(r.lastSeenAt).toISOString()}\t${r.recipient}\t${fmtMs(r.totalMs)}\tslide ${r.maxSlide}${r.completed ? " complete" : ""}\t${where}`);
-    }
-  }
-}
-
-function deckOpen(pos, opts) {
-  const [slug] = pos;
-  if (!slug) throw new Error("usage: deck open <slug>");
-  const url = `${target(opts).brokerBase}/d/${slug}`;
-  console.log(url);
-  openBrowser(url);
-}
-
-function shareBase(opts) {
-  return target(opts).shareBase;
-}
-
-async function shareNew(pos, opts) {
-  const [slug, recipient] = pos;
-  if (!slug || !recipient) throw new Error("usage: share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n]");
-  const args = { deckSlug: slug, recipient };
-  if (opts.email) args.recipientEmail = opts.email;
-  if (opts.note) args.note = opts.note;
-  if (opts["require-email"]) args.requireEmail = true;
-  if (opts.expires) {
-    const t = Date.parse(opts.expires);
-    if (Number.isNaN(t)) throw new Error(`expires must be an ISO date; got ${opts.expires}`);
-    args.expiresAt = t;
-  }
-  if (opts.limit != null) {
-    const n = Number(opts.limit);
-    if (!Number.isFinite(n)) throw new Error(`limit must be a number; got ${opts.limit}`);
-    args.viewLimit = n;
-  }
-  const { token } = await (await client(opts)).mutation(api.shares.create, args);
-  const url = `${shareBase(opts)}/v/${token}`;
-  if (opts.json) console.log(JSON.stringify({ token, url }, null, 2));
-  else console.log(`OK share for "${recipient}" -> ${url}`);
-}
-
-async function shareList(pos, opts) {
-  const [slug] = pos;
-  if (!slug) throw new Error("usage: share list <slug>");
-  const rows = await (await client(opts)).query(api.shares.listForDeck, { deckSlug: slug });
-  const slim = rows.map((r) => ({
-    token: r.token,
-    recipient: r.recipient,
-    enabled: r.enabled,
-    opens: r.opens,
-    archived: !!r.archived,
-    lastOpenedAt: r.lastOpenedAt ?? null,
-    requireEmail: r.requireEmail,
-    recipientEmail: r.recipientEmail ?? null,
-    expiresAt: r.expiresAt ?? null,
-    viewLimit: r.viewLimit ?? null,
-  }));
-  if (opts.json) {
-    console.log(JSON.stringify(slim, null, 2));
-    return;
-  }
-  for (const r of slim) console.log(`${r.enabled ? "on " : "off"}\t${r.token}\t${r.recipient}\topens:${r.opens}${r.archived ? "\t(archived)" : ""}`);
-  if (!slim.length) console.log("(no shares)");
-}
-
-async function shareToggle(pos, opts, enabled) {
-  const [token] = pos;
-  if (!token) throw new Error(`usage: share ${enabled ? "on" : "off"} <token>`);
-  await (await client(opts)).mutation(api.shares.setEnabled, { token, enabled });
-  console.log(`OK ${enabled ? "enabled" : "disabled"} ${token}`);
-}
-
-async function shareRm(pos, opts) {
-  const [token] = pos;
-  if (!token) throw new Error("usage: share rm <token>");
-  await (await client(opts)).mutation(api.shares.remove, { token });
-  console.log(`OK removed ${token}`);
-}
-
-function shareUrl(pos, opts) {
-  const [token] = pos;
-  if (!token) throw new Error("usage: share url <token>");
-  console.log(`${shareBase(opts)}/v/${token}`);
-}
-
-async function recipientArchive(pos, opts, archived) {
-  const [recipient] = pos;
-  if (!recipient) throw new Error(`usage: recipient ${archived ? "archive" : "unarchive"} <name>`);
-  await (await client(opts)).mutation(api.activity.setArchived, { recipient, archived });
-  console.log(`OK ${archived ? "archived" : "unarchived"} "${recipient}"`);
-}
-
-async function activity(pos, opts) {
-  const o = await (await client(opts)).query(api.activity.overview, {});
-  let feed = o.feed || [];
-  if (opts.deck) feed = feed.filter((f) => f.deckSlug === opts.deck);
-  if (opts.limit) feed = feed.slice(0, Number(opts.limit));
-  if (opts.json) {
-    console.log(JSON.stringify({ ...o, feed }, null, 2));
-    return;
-  }
-  if (!feed.length) {
-    console.log(opts.deck ? `(no activity for ${opts.deck})` : "(no activity)");
-    return;
-  }
-  for (const f of feed) {
-    const when = new Date(f.lastSeenAt).toISOString().replace("T", " ").slice(0, 16);
-    if (f.kind === "sent") {
-      console.log(`${when}\tsent\t${f.recipient}\t${f.deckTitle}`);
-    } else {
-      const where = [f.city, f.country].filter(Boolean).join(", ");
-      console.log(`${when}\topened\t${f.recipient}\t${f.deckTitle}\tslide ${f.maxSlide}\t${fmtMs(f.totalMs)}${f.completed ? " complete" : ""}\t${where}`);
-    }
-  }
-}
-
-function help() {
-  console.log(`decks ${VERSION}
-
-commands:
-  login [--token <pat>] [--broker <url>] [--dev]
-  logout [--dev]
-  whoami [--json] [--dev]
-  deck list|stats|open
-  share new|list|on|off|rm|url
-  recipient archive|unarchive
-  activity [--deck <slug>] [--limit <n>] [--json]
-
-global:
-  --json
-  --prod        production target (default)
-  --dev         development target (requires Convex URL)
-  --broker URL  override auth broker URL
-`);
-}
-
-const { pos, opts } = parse(process.argv.slice(2));
-if (opts.version) {
-  console.log(VERSION);
-  process.exit(0);
-}
-if (opts.help || pos.length === 0) {
-  help();
-  process.exit(0);
-}
-
-const [group, cmd] = pos;
-const rest = pos.slice(2);
-const handlers = {
-  login: () => login(opts),
-  logout: () => logout(opts),
-  whoami: () => whoami(opts),
-  "deck list": () => deckList(opts),
-  "deck stats": () => deckStats(rest, opts),
-  "deck open": () => deckOpen(rest, opts),
-  "share new": () => shareNew(rest, opts),
-  "share list": () => shareList(rest, opts),
-  "share on": () => shareToggle(rest, opts, true),
-  "share off": () => shareToggle(rest, opts, false),
-  "share rm": () => shareRm(rest, opts),
-  "share url": () => shareUrl(rest, opts),
-  "recipient archive": () => recipientArchive(rest, opts, true),
-  "recipient unarchive": () => recipientArchive(rest, opts, false),
-  activity: () => activity(pos.slice(1), opts),
-};
-
-const handler = handlers[`${group} ${cmd}`] || handlers[group];
-if (!handler) {
-  help();
-  process.exit(1);
-}
-
-try {
-  await handler();
-} catch (e) {
-  console.error("Error:", e?.message || e);
-  process.exit(1);
-}
+process.exitCode = await runCli(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersocial/decks-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Command-line client for Hypersocial Decks live analytics and share management.",
   "type": "module",
   "license": "UNLICENSED",
@@ -9,6 +9,7 @@
   },
   "files": [
     "bin/",
+    "src/",
     "README.md"
   ],
   "engines": {

package/src/commands.mjs

@@ -0,0 +1,212 @@
+import { login, logout, openBrowser, parse, target, VERSION } from "./runtime.mjs";
+import * as ops from "./ops.mjs";
+
+const fmtMs = (ms) => (ms >= 60000 ? `${(ms / 60000).toFixed(1)}m` : `${Math.round(ms / 1000)}s`);
+
+async function whoamiCmd(opts) {
+  const t = target(opts);
+  const who = await ops.whoami(opts);
+  if (opts.json) {
+    console.log(JSON.stringify({ ...(who || {}), deployment: t.name, convexUrl: t.convexUrl }, null, 2));
+    return;
+  }
+  if (!who) {
+    console.log(`not authenticated (${t.name})`);
+    return;
+  }
+  console.log(`email:      ${who.email}`);
+  console.log(`subject:    ${who.subject}`);
+  console.log(`isAdmin:    ${who.isAdmin}`);
+  console.log(`deployment: ${t.name} (${t.convexUrl})`);
+}
+
+async function deckList(opts) {
+  const rows = await ops.listDecks(opts);
+  if (opts.json) {
+    console.log(JSON.stringify(rows, null, 2));
+    return;
+  }
+  for (const d of rows) console.log(`${d.slug}\t${d.status}\t${d.title}`);
+  if (!rows.length) console.log("(no decks)");
+}
+
+async function deckStats(pos, opts) {
+  const [slug] = pos;
+  if (!slug) throw new Error("usage: deck stats <slug>");
+  const s = await ops.deckStats(opts, slug);
+  if (opts.json) {
+    console.log(JSON.stringify(s, null, 2));
+    return;
+  }
+  console.log(`deck "${slug}"`);
+  console.log(`  views:          ${s.views}`);
+  console.log(`  visits:         ${s.visits}`);
+  console.log(`  unique viewers: ${s.viewers}`);
+  console.log(`  avg engaged:    ${fmtMs(s.avgMs)}`);
+  console.log(`  total engaged:  ${fmtMs(s.totalMs)}`);
+  if (s.recent?.length) {
+    console.log("  recent:");
+    for (const r of s.recent) {
+      const where = [r.city, r.country].filter(Boolean).join(", ");
+      console.log(`    ${new Date(r.lastSeenAt).toISOString()}\t${r.recipient}\t${fmtMs(r.totalMs)}\tslide ${r.maxSlide}${r.completed ? " complete" : ""}\t${where}`);
+    }
+  }
+}
+
+function deckOpen(pos, opts) {
+  const [slug] = pos;
+  if (!slug) throw new Error("usage: deck open <slug>");
+  const url = `${target(opts).brokerBase}/d/${slug}`;
+  console.log(url);
+  openBrowser(url);
+}
+
+function shareBase(opts) {
+  return target(opts).shareBase;
+}
+
+async function shareNew(pos, opts) {
+  const [slug, recipient] = pos;
+  if (!slug || !recipient) throw new Error("usage: share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n]");
+  const { token } = await ops.createShare(opts, {
+    slug,
+    recipient,
+    email: opts.email,
+    note: opts.note,
+    requireEmail: opts["require-email"],
+    expires: opts.expires,
+    limit: opts.limit,
+  });
+  const url = `${shareBase(opts)}/v/${token}`;
+  if (opts.json) console.log(JSON.stringify({ token, url }, null, 2));
+  else console.log(`OK share for "${recipient}" -> ${url}`);
+}
+
+async function shareList(pos, opts) {
+  const [slug] = pos;
+  if (!slug) throw new Error("usage: share list <slug>");
+  const rows = await ops.listShares(opts, slug);
+  if (opts.json) {
+    console.log(JSON.stringify(rows, null, 2));
+    return;
+  }
+  for (const r of rows) console.log(`${r.enabled ? "on " : "off"}\t${r.token}\t${r.recipient}\topens:${r.opens}${r.archived ? "\t(archived)" : ""}`);
+  if (!rows.length) console.log("(no shares)");
+}
+
+async function shareToggle(pos, opts, enabled) {
+  const [token] = pos;
+  if (!token) throw new Error(`usage: share ${enabled ? "on" : "off"} <token>`);
+  await ops.setShareEnabled(opts, token, enabled);
+  console.log(`OK ${enabled ? "enabled" : "disabled"} ${token}`);
+}
+
+async function shareRm(pos, opts) {
+  const [token] = pos;
+  if (!token) throw new Error("usage: share rm <token>");
+  await ops.removeShare(opts, token);
+  console.log(`OK removed ${token}`);
+}
+
+function shareUrl(pos, opts) {
+  const [token] = pos;
+  if (!token) throw new Error("usage: share url <token>");
+  console.log(`${shareBase(opts)}/v/${token}`);
+}
+
+async function recipientArchive(pos, opts, archived) {
+  const [recipient] = pos;
+  if (!recipient) throw new Error(`usage: recipient ${archived ? "archive" : "unarchive"} <name>`);
+  await ops.setRecipientArchived(opts, recipient, archived);
+  console.log(`OK ${archived ? "archived" : "unarchived"} "${recipient}"`);
+}
+
+async function activity(pos, opts) {
+  const o = await ops.activityOverview(opts);
+  let feed = o.feed || [];
+  if (opts.deck) feed = feed.filter((f) => f.deckSlug === opts.deck);
+  if (opts.limit) feed = feed.slice(0, Number(opts.limit));
+  if (opts.json) {
+    console.log(JSON.stringify({ ...o, feed }, null, 2));
+    return;
+  }
+  if (!feed.length) {
+    console.log(opts.deck ? `(no activity for ${opts.deck})` : "(no activity)");
+    return;
+  }
+  for (const f of feed) {
+    const when = new Date(f.lastSeenAt).toISOString().replace("T", " ").slice(0, 16);
+    if (f.kind === "sent") {
+      console.log(`${when}\tsent\t${f.recipient}\t${f.deckTitle}`);
+    } else {
+      const where = [f.city, f.country].filter(Boolean).join(", ");
+      console.log(`${when}\topened\t${f.recipient}\t${f.deckTitle}\tslide ${f.maxSlide}\t${fmtMs(f.totalMs)}${f.completed ? " complete" : ""}\t${where}`);
+    }
+  }
+}
+
+export function help() {
+  console.log(`decks ${VERSION}
+
+commands:
+  login [--token <pat>] [--broker <url>] [--dev]
+  logout [--dev]
+  whoami [--json] [--dev]
+  deck list|stats|open
+  share new|list|on|off|rm|url
+  recipient archive|unarchive
+  activity [--deck <slug>] [--limit <n>] [--json]
+
+global:
+  --json
+  --prod        production target (default)
+  --dev         development target (requires Convex URL)
+  --broker URL  override auth broker URL
+`);
+}
+
+export async function runCli(argv = process.argv.slice(2)) {
+  const { pos, opts } = parse(argv);
+  if (opts.version) {
+    console.log(VERSION);
+    return 0;
+  }
+  if (opts.help || pos.length === 0) {
+    help();
+    return opts.help || pos.length === 0 ? 0 : 1;
+  }
+
+  const [group, cmd] = pos;
+  const rest = pos.slice(2);
+  const handlers = {
+    login: () => login(opts),
+    logout: () => logout(opts),
+    whoami: () => whoamiCmd(opts),
+    "deck list": () => deckList(opts),
+    "deck stats": () => deckStats(rest, opts),
+    "deck open": () => deckOpen(rest, opts),
+    "share new": () => shareNew(rest, opts),
+    "share list": () => shareList(rest, opts),
+    "share on": () => shareToggle(rest, opts, true),
+    "share off": () => shareToggle(rest, opts, false),
+    "share rm": () => shareRm(rest, opts),
+    "share url": () => shareUrl(rest, opts),
+    "recipient archive": () => recipientArchive(rest, opts, true),
+    "recipient unarchive": () => recipientArchive(rest, opts, false),
+    activity: () => activity(pos.slice(1), opts),
+  };
+
+  const handler = handlers[`${group} ${cmd}`] || handlers[group];
+  if (!handler) {
+    help();
+    return 1;
+  }
+
+  try {
+    await handler();
+    return 0;
+  } catch (e) {
+    console.error("Error:", e?.message || e);
+    return 1;
+  }
+}

package/src/ops.mjs

@@ -0,0 +1,80 @@
+import { api, client } from "./runtime.mjs";
+
+export async function whoami(opts = {}) {
+  return (await client(opts)).query(api.decks.whoami, {});
+}
+
+export async function listDecks(opts = {}) {
+  const rows = await (await client(opts)).query(api.decks.listForViewer, {});
+  return rows.map((d) => ({
+    slug: d.slug,
+    title: d.title,
+    status: d.status,
+    ownerEmail: d.ownerEmail ?? null,
+    hasHtml: !!d.html,
+  }));
+}
+
+export async function deckStats(opts, slug) {
+  if (!slug) throw new Error("slug is required");
+  return (await client(opts)).query(api.shares.deckAnalytics, { deckSlug: slug });
+}
+
+export async function activityOverview(opts = {}) {
+  return (await client(opts)).query(api.activity.overview, {});
+}
+
+export async function listShares(opts, slug) {
+  if (!slug) throw new Error("slug is required");
+  const rows = await (await client(opts)).query(api.shares.listForDeck, { deckSlug: slug });
+  return rows.map((r) => ({
+    token: r.token,
+    recipient: r.recipient,
+    enabled: r.enabled,
+    opens: r.opens,
+    archived: !!r.archived,
+    lastOpenedAt: r.lastOpenedAt ?? null,
+    requireEmail: r.requireEmail,
+    recipientEmail: r.recipientEmail ?? null,
+    expiresAt: r.expiresAt ?? null,
+    viewLimit: r.viewLimit ?? null,
+  }));
+}
+
+export async function createShare(opts, fields) {
+  const { slug, recipient } = fields;
+  if (!slug || !recipient) throw new Error("slug and recipient are required");
+  const args = { deckSlug: slug, recipient };
+  if (fields.email) args.recipientEmail = fields.email;
+  if (fields.note) args.note = fields.note;
+  if (fields.requireEmail) args.requireEmail = true;
+  if (fields.expires) {
+    const t = Date.parse(fields.expires);
+    if (Number.isNaN(t)) throw new Error(`expires must be an ISO date; got ${fields.expires}`);
+    args.expiresAt = t;
+  }
+  if (fields.limit != null) {
+    const n = Number(fields.limit);
+    if (!Number.isFinite(n)) throw new Error(`limit must be a number; got ${fields.limit}`);
+    args.viewLimit = n;
+  }
+  return (await client(opts)).mutation(api.shares.create, args);
+}
+
+export async function setShareEnabled(opts, token, enabled) {
+  if (!token) throw new Error("token is required");
+  await (await client(opts)).mutation(api.shares.setEnabled, { token, enabled: !!enabled });
+  return { token, enabled: !!enabled };
+}
+
+export async function removeShare(opts, token) {
+  if (!token) throw new Error("token is required");
+  await (await client(opts)).mutation(api.shares.remove, { token });
+  return { token, removed: true };
+}
+
+export async function setRecipientArchived(opts, recipient, archived) {
+  if (!recipient) throw new Error("recipient is required");
+  await (await client(opts)).mutation(api.activity.setArchived, { recipient, archived });
+  return { recipient, archived: !!archived };
+}

package/src/runtime.mjs

@@ -0,0 +1,268 @@
+import { execFile } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+
+export const VERSION = "0.1.1";
+
+export const PROD = {
+  name: "prod",
+  convexUrl: "https://dashing-snail-874.convex.cloud",
+  brokerBase: "https://decks.hypersocial.ai",
+  shareBase: "https://decks.hypersocial.ai",
+};
+
+export const api = {
+  activity: {
+    overview: makeFunctionReference("activity:overview"),
+    setArchived: makeFunctionReference("activity:setArchived"),
+  },
+  cliCredentials: {
+    revokeByHash: makeFunctionReference("cliCredentials:revokeByHash"),
+  },
+  decks: {
+    listForViewer: makeFunctionReference("decks:listForViewer"),
+    whoami: makeFunctionReference("decks:whoami"),
+  },
+  shares: {
+    create: makeFunctionReference("shares:create"),
+    deckAnalytics: makeFunctionReference("shares:deckAnalytics"),
+    listForDeck: makeFunctionReference("shares:listForDeck"),
+    remove: makeFunctionReference("shares:remove"),
+    setEnabled: makeFunctionReference("shares:setEnabled"),
+  },
+};
+
+const BOOL = new Set(["prod", "dev", "json", "require-email", "help", "version"]);
+
+export const CRED_DIR = join(homedir(), ".config", "hypersocial-decks");
+export const CRED_FILE = join(CRED_DIR, "credentials.json");
+
+export function parse(args) {
+  const opts = {};
+  const pos = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const k = a.slice(2);
+      if (BOOL.has(k)) opts[k] = true;
+      else opts[k] = args[++i];
+    } else {
+      pos.push(a);
+    }
+  }
+  return { pos, opts };
+}
+
+export function normalizeBase(url) {
+  return String(url || "").replace(/\/$/, "");
+}
+
+export function target(opts = {}) {
+  const envWantsDev = process.env.HSDECKS_PROD === "0";
+  const wantDev = opts.dev || (envWantsDev && !opts.prod);
+  if (!wantDev) {
+    return {
+      ...PROD,
+      brokerBase: normalizeBase(opts.broker || PROD.brokerBase),
+    };
+  }
+
+  const convexUrl = opts.convex || process.env.HSDECKS_CONVEX_URL || process.env.CONVEX_URL;
+  if (!convexUrl) {
+    throw new Error("dev target needs --convex <url>, HSDECKS_CONVEX_URL, or CONVEX_URL");
+  }
+  return {
+    name: "dev",
+    convexUrl,
+    brokerBase: normalizeBase(opts.broker || process.env.HSDECKS_BROKER_BASE || "http://localhost:3000"),
+    shareBase: normalizeBase(process.env.HSDECKS_SHARE_BASE || "https://decks.localhost"),
+  };
+}
+
+export function loadCreds() {
+  if (!existsSync(CRED_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(CRED_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export function saveCred(name, cred) {
+  const all = loadCreds();
+  all[name] = cred;
+  mkdirSync(CRED_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(CRED_FILE, JSON.stringify(all, null, 2), { mode: 0o600 });
+}
+
+export function clearCred(name) {
+  const all = loadCreds();
+  const removed = all[name];
+  delete all[name];
+  mkdirSync(CRED_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(CRED_FILE, JSON.stringify(all, null, 2), { mode: 0o600 });
+  return removed;
+}
+
+export const sha256Hex = (s) => createHash("sha256").update(s, "utf8").digest("hex");
+
+function resolveRefreshToken(t, opts) {
+  if (opts.token) return opts.token;
+  if (process.env.HSDECKS_TOKEN) return process.env.HSDECKS_TOKEN;
+  return loadCreds()[t.name]?.refreshToken || null;
+}
+
+async function mintJwt(brokerBase, refreshToken) {
+  let res;
+  try {
+    res = await fetch(`${brokerBase}/api/cli/token`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${refreshToken}` },
+      signal: AbortSignal.timeout(15000),
+    });
+  } catch (e) {
+    const msg = String(e?.message || e);
+    if (e?.name === "TimeoutError" || /timeout/i.test(msg)) {
+      throw new Error(`broker at ${brokerBase} did not respond within 15s`);
+    }
+    throw new Error(`could not reach broker at ${brokerBase} (${msg})`);
+  }
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`auth exchange failed (${res.status}) ${body.slice(0, 200)}`);
+  }
+  return res.json();
+}
+
+const jwtCache = new Map();
+
+async function jwtFor(brokerBase, refreshToken) {
+  const hit = jwtCache.get(refreshToken);
+  if (hit && hit.expiresAt - Date.now() > 60000) return hit.token;
+  const { token, expiresAt } = await mintJwt(brokerBase, refreshToken);
+  jwtCache.set(refreshToken, { token, expiresAt });
+  return token;
+}
+
+export async function client(opts = {}) {
+  const t = target(opts);
+  const c = new ConvexHttpClient(t.convexUrl);
+  const refreshToken = resolveRefreshToken(t, opts);
+  if (!refreshToken) {
+    throw new Error(`not authenticated for ${t.name} - run \`decks login${t.name === "dev" ? " --dev" : ""}\``);
+  }
+  c.setAuth(await jwtFor(t.brokerBase, refreshToken));
+  return c;
+}
+
+export function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  execFile(cmd, args, () => {});
+}
+
+async function verifyAndStampEmail(t, opts) {
+  const c = await client(opts);
+  const who = await c.query(api.decks.whoami, {});
+  if (!who) throw new Error("credential was rejected by Convex");
+  const cur = loadCreds()[t.name] || {};
+  saveCred(t.name, { ...cur, email: who.email });
+  return who;
+}
+
+export async function login(opts) {
+  const t = target(opts);
+
+  if (opts.token) {
+    saveCred(t.name, { refreshToken: opts.token, convexUrl: t.convexUrl, brokerBase: t.brokerBase });
+    try {
+      const who = await verifyAndStampEmail(t, opts);
+      console.log(`OK logged in to ${t.name}${who.email ? ` as ${who.email}` : ""}`);
+    } catch (e) {
+      clearCred(t.name);
+      throw e;
+    }
+    return;
+  }
+
+  const state = randomBytes(16).toString("hex");
+  await new Promise((resolve, reject) => {
+    let timer;
+    let done = false;
+    let server;
+    const finish = (err) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      server.close();
+      err ? reject(err) : resolve();
+    };
+
+    server = createServer((req, res) => {
+      res.setHeader("Access-Control-Allow-Origin", t.brokerBase);
+      res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "content-type");
+      if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+      if (req.method === "POST" && (req.url || "").startsWith("/callback")) {
+        let body = "";
+        req.on("data", (d) => (body += d));
+        req.on("end", () => {
+          try {
+            const { refreshToken, state: got } = JSON.parse(body || "{}");
+            if (got !== state) throw new Error("state mismatch");
+            if (!refreshToken) throw new Error("no token returned");
+            saveCred(t.name, { refreshToken, convexUrl: t.convexUrl, brokerBase: t.brokerBase });
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(JSON.stringify({ ok: true }));
+            finish();
+          } catch (e) {
+            res.writeHead(400);
+            res.end(String(e?.message || e));
+            finish(e);
+          }
+        });
+        return;
+      }
+      res.writeHead(404);
+      res.end();
+    });
+
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address();
+      const url = `${t.brokerBase}/cli/authorize?port=${port}&state=${state}`;
+      console.log(`Opening your browser to sign in (${t.name})...\n  ${url}\nIf it does not open, paste that URL into your browser.`);
+      openBrowser(url);
+    });
+    timer = setTimeout(() => finish(new Error("login timed out after 3 min")), 180000);
+  });
+
+  const who = await verifyAndStampEmail(t, opts);
+  console.log(`OK logged in to ${t.name}${who.email ? ` as ${who.email}` : ""}`);
+}
+
+export async function logout(opts) {
+  const t = target(opts);
+  const cur = loadCreds()[t.name];
+  if (!cur?.refreshToken) {
+    console.log(`not logged in to ${t.name}`);
+    return;
+  }
+  try {
+    const anon = new ConvexHttpClient(t.convexUrl);
+    await anon.mutation(api.cliCredentials.revokeByHash, { tokenHash: sha256Hex(cur.refreshToken) });
+  } catch {
+    // Still clear local credential if the network is unavailable.
+  }
+  clearCred(t.name);
+  console.log(`OK logged out of ${t.name}`);
+}