@hypersocial/decks-cli 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# @hypersocial/decks-cli
+
+Command-line client for Hypersocial Decks live analytics and share management.
+
+This package targets production by default:
+
+```bash
+pnpm dlx @hypersocial/decks-cli login
+pnpm dlx @hypersocial/decks-cli whoami
+pnpm dlx @hypersocial/decks-cli deck list
+pnpm dlx @hypersocial/decks-cli deck stats netflix
+pnpm dlx @hypersocial/decks-cli activity --limit 20
+```
+
+Global install:
+
+```bash
+pnpm add -g @hypersocial/decks-cli
+decks login
+decks activity
+```
+
+## Auth
+
+`decks login` opens the production broker at `https://decks.hypersocial.ai` and
+stores a refresh credential in:
+
+```text
+~/.config/hypersocial-decks/credentials.json
+```
+
+Headless usage:
+
+```bash
+decks login --token <refresh-or-pat>
+HSDECKS_TOKEN=<refresh-or-pat> decks whoami
+```
+
+## Commands
+
+```text
+login [--token <pat>] [--broker <url>]
+logout
+whoami [--json]
+
+deck list [--json]
+deck stats <slug> [--json]
+deck open <slug>
+
+share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n]
+share list <slug> [--json]
+share on|off <token>
+share rm <token>
+share url <token>
+
+recipient archive|unarchive <name>
+activity [--deck <slug>] [--limit <n>] [--json]
+```
+
+## Development Target
+
+Production is the default because this CLI is for real recipient activity and
+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
+```

package/bin/decks.mjs

@@ -0,0 +1,500 @@
+#!/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";
+
+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);
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@hypersocial/decks-cli",
+  "version": "0.1.0",
+  "description": "Command-line client for Hypersocial Decks live analytics and share management.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "bin": {
+    "decks": "bin/decks.mjs"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "convex": "^1.41.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}