@hypersocial/decks-cli 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersocial/decks-cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Command-line client for Hypersocial Decks live analytics and share management.",
   "type": "module",
   "main": "./src/commands.mjs",

package/skills/hyperdecks/SKILL.md

@@ -95,6 +95,7 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 | One more link | `hyperdecks share new <slug> "<name>"` | `create_share` |
 | Who watched | `hyperdecks deck stats <slug>` | `deck_stats` |
 | All activity | `hyperdecks activity --deck <slug>` | `activity_overview` |
+| What one person watched | `hyperdecks engagement "<name>" --deck <slug> --json` | `recipient_engagement` |
 
 ### 1. Ground it in the user's own material
 
@@ -471,6 +472,32 @@ hyperdecks activity --deck <slug> --limit 10
 Tell the user who opened it, how far they got and whether the narration
 finished. QA links never count.
 
+### 9. Follow up with a recipient
+
+When the user wants to follow up with someone, read what that person watched:
+
+```bash
+hyperdecks engagement "<name>" --deck <slug> --json   # MCP: recipient_engagement
+```
+
+Then draft the email:
+
+1. Lead with the slide they spent most time on (`summary.mostTime`) or
+   replayed (`replayedSlides`), and answer what that slide raises. Each
+   slide's `title` says what it is about.
+2. If they dropped off (`droppedOffOn`), offer the rest briefly, or a
+   2-minute call, rather than asking them to rewatch.
+3. If they never opened it (`summary.visits` is 0), write a short nudge
+   instead.
+
+Use what you know beyond the data: the email thread, who the person is, what
+was promised, and the user's voice. Never tell the recipient they were
+tracked: no "I saw you watched slide 7 three times", no percentages. The
+signal decides what to talk about; it is never something to quote. Put the
+draft in the user's mail tool (or show the text) and never send it without the
+user's go-ahead. `null` means a field was not recorded for that visit (older
+links), not zero.
+
 ### Hosted source (chat agents and the connector)
 
 A deck can also live on Hyperdecks with no folder: chat agents build it through

package/src/commands.mjs

@@ -12,7 +12,7 @@ import * as ops from "./ops.mjs";
 
 export const playbackLabel = (p) => p.narrationFinished ? "narration finished"
   : p.narrationStarted ? "narration started"
-    : p.telemetryVersion === 2 ? "narration not started" : "playback unknown (legacy)";
+    : (p.telemetryVersion ?? 0) >= 2 ? "narration not started" : "playback unknown (legacy)";
 
 const fmtMs = (ms) => (ms >= 60000 ? `${(ms / 60000).toFixed(1)}m` : `${Math.round(ms / 1000)}s`);
 
@@ -167,6 +167,41 @@ async function activity(pos, opts) {
   }
 }
 
+const pct = (n) => (n === null || n === undefined ? "n/a" : `${n}%`);
+const slideName = (s) => (s.title ? `${s.index} ${s.title}` : `slide ${s.index}`);
+
+async function engagement(pos, opts) {
+  const who = pos.join(" ");
+  if (!who) throw new Error("usage: engagement <recipient|token> [--deck <slug>] [--json]");
+  const entries = await ops.recipientEngagement(opts, who, opts.deck);
+  if (opts.json) {
+    console.log(JSON.stringify(entries, null, 2));
+    return;
+  }
+  if (!entries.length) {
+    console.log(`(no links for "${who}"${opts.deck ? ` on ${opts.deck}` : ""})`);
+    return;
+  }
+  for (const e of entries) {
+    const s = e.summary;
+    console.log(`${e.recipient} — ${e.deck.title} (${e.deck.slug}, link ${e.link.token}${e.link.enabled ? "" : ", off"})`);
+    if (!s.visits) {
+      console.log("  never opened");
+      continue;
+    }
+    const titles = new Map(e.slides.map((r) => [r.index, r]));
+    const list = (xs) => (xs === null ? "n/a" : xs.length ? xs.map((i) => slideName(titles.get(i) ?? { index: i })).join(", ") : "none");
+    console.log(`  visits:      ${s.visits} (last ${new Date(s.lastSeenAt).toISOString().slice(0, 16).replace("T", " ")}) · ${fmtMs(s.totalMs)} engaged`);
+    console.log(`  narration:   ${s.narration.finished ? "finished" : s.narration.started ? "started" : "not started"} · heard ${pct(s.narration.heardPct)}${s.narration.telemetry === "v3" ? "" : " (playback detail unavailable)"}`);
+    console.log(`  reached:     slide ${s.furthestSlide}${e.deck.slides ? ` of ${e.deck.slides}` : ""}${s.droppedOffOn ? ` · dropped off on ${slideName(s.droppedOffOn)}` : ""}`);
+    console.log(`  replayed:    ${list(s.replayedSlides)}`);
+    console.log(`  skipped:     ${list(s.skippedSlides)}`);
+    console.log(`  most time:   ${s.mostTime.map((m) => `${slideName(m)} (${fmtMs(m.ms)})`).join(", ") || "none"}`);
+    if (!s.slideData) console.log("  slide data unavailable (this deck reports time only)");
+    if (s.deckChangedSinceView) console.log("  the deck changed since their last visit");
+  }
+}
+
 async function credits(pos, opts) {
   const bal = await ops.creditsBalance(opts);
   const ledger = await ops.creditsLedger(opts, opts.limit || 10);
@@ -272,6 +307,8 @@ commands:
   skills install [--agent codex,claude-code] [--all-agents]
                    default: every agent found in your home directory (else codex, claude-code)
   activity [--deck <slug>] [--limit <n>] [--json]
+  engagement <recipient|token> [--deck <slug>] [--json]
+                   what one recipient watched per deck: narration heard, replays, drop-off, visits
   gen-image "<prompt>" [--model gpt-image-2.5|nano-banana-2.1|gpt-image-2] [--transparent] [--image <url>] [--size <s>]
             [--quality <q>] [--count <n>] [--seed <n>] [--slug <deck>] [--download <file>]
                    default model gpt-image-2.5; --seed applies to nano-banana-2.1
@@ -653,6 +690,7 @@ function commandTable(pos, rest, opts) {
     "skill install": () => installHyperdecksSkill(opts, rest),
     "skills install": () => installHyperdecksSkill(opts, rest),
     activity: () => activity(pos.slice(1), opts),
+    engagement: () => engagement(pos.slice(1), opts),
     "gen-image": () => genImage(pos.slice(1), opts),
     "image-job": () => imageJob(pos.slice(1), opts),
     "gen-video": () => genVideo(pos.slice(1), opts),

package/src/ops.mjs

@@ -36,6 +36,21 @@ export async function activityOverview(opts = {}) {
   return (await client(opts)).query(api.activity.overview, {});
 }
 
+// What one recipient watched, per deck link (or one link by token): the data
+// the owner's agent drafts a follow-up from. A 16-character link token is
+// looked up as a token; anything else is a recipient name.
+export const RECIPIENT_ENGAGEMENT_DESCRIPTION =
+  "What one recipient watched, per deck link: visits, narration heard (%), replayed / skipped slides, " +
+  "where they dropped off, time per slide, each visit, and forwards. Use it to draft a follow-up: lead " +
+  "with what they spent time on, and never tell the recipient they were tracked.";
+export const SHARE_TOKEN = /^[a-f0-9]{16}$/;
+export async function recipientEngagement(opts, who, deck) {
+  const value = String(who ?? "").trim();
+  if (!value) throw new Error("a recipient name or share token is required");
+  const args = SHARE_TOKEN.test(value) ? { token: value } : { recipient: value, ...(deck ? { deckSlug: String(deck) } : {}) };
+  return (await client(opts)).query(api.engagement.recipientEngagement, args);
+}
+
 // Generate an image via fal (GPT Image 2.5 by default, or Nano Banana 2.1 / GPT
 // Image 2 with `model`; t2i/i2i, optional BiRefNet transparency),
 // store it in Convex, and return the hosted URL. Runs the imagegen action as the

package/src/runtime.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url";
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 
-export const VERSION = "0.3.0";
+export const VERSION = "0.3.1";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {
@@ -38,6 +38,9 @@ export const api = {
     overview: makeFunctionReference("activity:overview"),
     setArchived: makeFunctionReference("activity:setArchived"),
   },
+  engagement: {
+    recipientEngagement: makeFunctionReference("engagement:recipientEngagement"),
+  },
   cliCredentials: {
     revokeByHash: makeFunctionReference("cliCredentials:revokeByHash"),
   },