@sightspool/sdk 0.1.1 → 0.2.0

package/README.md

@@ -14,8 +14,8 @@ them).
 > **not** act on your surface (surveys/nudges/experiments are Wave 0005, and every one
 > is human-gated). Trigger sensitivity and intent inference calibrate with live traffic.
 
-**Docs:** [full reference + CSP & framework guides](https://sightspool.github.io/sdk/) ·
-[llms.txt](https://sightspool.github.io/sdk/llms.txt) (the machine-readable install/CSP/config
+**Docs:** [full reference + CSP & framework guides](https://sdk.sightspool.com/) ·
+[llms.txt](https://sdk.sightspool.com/llms.txt) (the machine-readable install/CSP/config
 doc for agents) · [npm](https://www.npmjs.com/package/@sightspool/sdk)
 
 ---
@@ -90,6 +90,7 @@ The script tag also reads these optional attributes (the no-build equivalent of
 | `key` | `string` | — | **required.** Your publishable key (`pk_test_…` / `pk_live_…`), from the Connections → In-product SDK card. Publishable — safe to ship in client JS. See [Keys & environments](#keys--environments). |
 | `endpoint` | `string` | the bundle's origin (script tag) / `https://app.sightspool.com` (npm) | Ingest base URL. The `<script>` install auto-resolves it to wherever `sdk.global.js` was served from (your app), so the key alone is enough; override for a CDN-hosted bundle or dev. |
 | `boundaryAsk` | `boolean` | `true` | Show the one-tap "did you do what you came to do?" ask at session boundaries. |
+| `interventions` | `boolean` | `true` | Show human-approved **surveys** served by your Sightspool workspace (see [Interventions](#interventions-surveys)). Set `false` to capture only. |
 | `consent` | `boolean` | `true` | Start capturing immediately. Set `false` to stay paused until you call `Sightspool.consent(true)` (or `start()`) after obtaining consent. |
 | `redact` | `string[]` | `[]` | CSS selectors whose captured text is **masked** (replaced with `‹redacted›`) before anything leaves the page. The event is still recorded — only its label is masked. |
 | `block` | `string[]` | `[]` | CSS selectors whose events are **dropped entirely** (the hard opt-out). Equivalent to putting `data-sightspool-ignore` on the element. |
@@ -186,29 +187,44 @@ useEffect(() => {
 > in the environment Next builds in. `strategy="afterInteractive"` keeps it off the critical
 > path.
 
-### React (bundler install)
+### React / Next.js — `@sightspool/react`
 
-Install the package and call `init` once at app start (a top-level effect or your entry
-module):
+For React apps, use the official bindings — a declarative provider over the core SDK:
+
+```bash
+npm install @sightspool/react @sightspool/sdk react
+```
+
+```tsx
+import { SightspoolProvider } from '@sightspool/react'
+
+<SightspoolProvider
+  apiKey={process.env.NEXT_PUBLIC_SIGHTSPOOL_KEY!}
+  identity={user && { userId: user.id, account: user.account, plan: user.plan }}
+>
+  <App />
+</SightspoolProvider>
+```
+
+It ships a `"use client"` banner (drops straight into a Next.js App Router **server**
+layout), re-fires `identify` whenever `identity` changes, and takes a reactive `consent`
+prop for cookie banners. Full API:
+[@sightspool/react](https://www.npmjs.com/package/@sightspool/react) ·
+[packages/react](https://github.com/sightspool/sdk/tree/main/packages/react).
+
+<details><summary>Or wire the core SDK by hand (no wrapper)</summary>
 
 ```tsx
 import { useEffect } from 'react'
 import Sightspool from '@sightspool/sdk'
 
 export function SightspoolBoot({ userId, account, plan }) {
-  useEffect(() => {
-    Sightspool.init({ key: import.meta.env.VITE_SIGHTSPOOL_KEY })
-  }, [])
-  useEffect(() => {
-    if (userId) Sightspool.identify(userId, { account, plan })
-  }, [userId, account, plan])
+  useEffect(() => { Sightspool.init({ key: import.meta.env.VITE_SIGHTSPOOL_KEY }) }, [])
+  useEffect(() => { if (userId) Sightspool.identify(userId, { account, plan }) }, [userId, account, plan])
   return null
 }
 ```
-
-> A first-class **`@sightspool/react`** wrapper (a `<SightspoolProvider>` + a `useSightspool`
-> hook over `init`/`identify`) is planned —
-> [issue #3](https://github.com/sightspool/sdk/issues/3).
+</details>
 
 ---
 
@@ -245,6 +261,44 @@ If you pass a custom `endpoint`, use *that* origin in `connect-src`. The beacon
 
 ---
 
+## Interventions (surveys)
+
+The SDK is two-way. Besides *capturing*, it can show a **human-approved survey** at the
+moment of friction — the "ask" side of Sightspool. You don't author these in code: your
+team proposes a survey off a proven finding in the app, **a human approves it**, sets who
+sees it (route / account / plan), and the SDK serves it. Nothing reaches a user without
+that approval ("no proof **and** no approval, no act").
+
+It's on by default — the same one or two install lines that capture also serve. When the
+SDK loads (and on each route change) it asks your workspace *"anything to show this user
+here?"*; if there's a matching approved survey, it renders a small card in a shadow root
+(your CSS can't reach it; it leaks no styles), and posts the answer back.
+
+```js
+Sightspool.init({ key: "pk_live_…" });          // serving is on by default
+Sightspool.init({ key: "pk_live_…", interventions: false }); // capture only
+```
+
+```html
+<!-- script-tag install: opt out with one attribute -->
+<script src="https://app.sightspool.com/sdk.global.js"
+        data-sightspool-key="pk_live_…"
+        data-sightspool-no-interventions></script>
+```
+
+**What shows, and how often** — all server-gated, so you stay in control:
+
+- **Targeting** — only to the route / account / plan the approver chose.
+- **De-dup** — a survey a user has answered never reappears (a per-user key is kept
+  locally; it's anonymous unless you've called `identify()`).
+- **Won't pester** — at most one survey on screen, one per session, and it shares a
+  cooldown with the boundary ask so the two never stack back-to-back. The run also stops
+  itself once it hits the approver's response target.
+
+The survey widget is **lazily loaded** — it splits into its own chunk and adds nothing to
+your bundle until a survey is actually served. Today the SDK renders one-tap / short-text
+surveys; richer types (incl. voice micro-research) render as they ship.
+
 ## What it captures
 
 - **Passively, no wiring** — route/screen sequence, clicks, **dead-clicks** and

package/dist/index.cjs

@@ -199,6 +199,157 @@ input { font: inherit; font-size: 13px; width: 100%; box-sizing: border-box; pad
   }
 });
 
+// src/survey.ts
+var survey_exports = {};
+__export(survey_exports, {
+  showSurvey: () => showSurvey
+});
+function showSurvey(config) {
+  return new Promise((resolve) => {
+    if (typeof document === "undefined") {
+      resolve({ dismissed: true });
+      return;
+    }
+    let settled = false;
+    const host = document.createElement("div");
+    const shadow = host.attachShadow({ mode: "open" });
+    function teardown() {
+      try {
+        host.remove();
+      } catch (e) {
+      }
+    }
+    function finish(result, thank) {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+      if (thank) {
+        thankYou();
+        setTimeout(teardown, THANKS_MS);
+      } else {
+        teardown();
+      }
+    }
+    const style = document.createElement("style");
+    style.textContent = STYLE2;
+    shadow.appendChild(style);
+    const wrap = document.createElement("div");
+    wrap.className = "wrap";
+    shadow.appendChild(wrap);
+    function card() {
+      wrap.innerHTML = "";
+      const c = document.createElement("div");
+      c.className = "card";
+      wrap.appendChild(c);
+      return c;
+    }
+    function withClose(c) {
+      const x = document.createElement("button");
+      x.className = "x";
+      x.textContent = "\xD7";
+      x.setAttribute("aria-label", "Dismiss");
+      x.onclick = () => finish({ dismissed: true }, false);
+      c.appendChild(x);
+    }
+    function question() {
+      var _a2, _b, _c;
+      const c = card();
+      withClose(c);
+      const q = document.createElement("p");
+      q.className = "q";
+      q.textContent = config.question;
+      c.appendChild(q);
+      for (const opt of ((_a2 = config.options) != null ? _a2 : []).slice(0, 6)) {
+        const b = document.createElement("button");
+        b.className = "opt";
+        b.textContent = opt;
+        b.onclick = () => finish({ choice: opt }, true);
+        c.appendChild(b);
+      }
+      if (config.allow_text) {
+        const se = document.createElement("button");
+        se.className = "opt";
+        se.textContent = ((_c = (_b = config.options) == null ? void 0 : _b.length) != null ? _c : 0) > 0 ? "Something else\u2026" : "Answer\u2026";
+        se.onclick = freeText;
+        c.appendChild(se);
+      }
+    }
+    function freeText() {
+      const c = card();
+      withClose(c);
+      const q = document.createElement("p");
+      q.className = "q";
+      q.textContent = config.question;
+      c.appendChild(q);
+      const input = document.createElement("input");
+      input.type = "text";
+      input.placeholder = "In your own words\u2026";
+      c.appendChild(input);
+      const row = document.createElement("div");
+      row.className = "row";
+      const send = document.createElement("button");
+      send.className = "primary";
+      send.textContent = "Send";
+      const submit = () => {
+        const text = input.value.trim();
+        if (!text) {
+          finish({ dismissed: true }, false);
+          return;
+        }
+        finish({ text }, true);
+      };
+      send.onclick = submit;
+      input.onkeydown = (e) => {
+        if (e.key === "Enter") submit();
+      };
+      row.appendChild(send);
+      c.appendChild(row);
+      try {
+        input.focus();
+      } catch (e) {
+      }
+    }
+    function thankYou() {
+      const c = card();
+      const p = document.createElement("p");
+      p.className = "done";
+      p.textContent = "Thanks \u2014 that helps.";
+      c.appendChild(p);
+    }
+    try {
+      document.body.appendChild(host);
+      question();
+    } catch (e) {
+      finish({ dismissed: true }, false);
+    }
+  });
+}
+var STYLE2, THANKS_MS;
+var init_survey = __esm({
+  "src/survey.ts"() {
+    STYLE2 = `
+:host { all: initial; }
+.wrap { position: fixed; bottom: 20px; right: 20px; z-index: 2147483000;
+  width: 340px; max-width: calc(100vw - 32px); font-family: system-ui, -apple-system, sans-serif; }
+.card { position: relative; background: #fff; color: #18181b; border: 1px solid #e4e4e7;
+  border-radius: 12px; box-shadow: 0 10px 30px rgba(0,0,0,.12); padding: 16px; }
+.q { font-size: 14px; font-weight: 600; margin: 0 0 12px; line-height: 1.35; padding-right: 16px; }
+.row { display: flex; gap: 8px; flex-wrap: wrap; }
+button { font: inherit; font-size: 13px; cursor: pointer; border-radius: 8px; padding: 8px 12px;
+  border: 1px solid #e4e4e7; background: #fafafa; color: #18181b; }
+button:hover { background: #f4f4f5; }
+button.primary { background: #18181b; color: #fff; border-color: #18181b; }
+.opt { display: block; width: 100%; text-align: left; margin-bottom: 6px; }
+.x { position: absolute; top: 8px; right: 10px; border: none; background: none; font-size: 16px;
+  color: #a1a1aa; padding: 2px 6px; cursor: pointer; }
+.done { font-size: 13px; color: #18181b; margin: 0; }
+input { font: inherit; font-size: 13px; width: 100%; box-sizing: border-box; padding: 8px 10px;
+  border: 1px solid #e4e4e7; border-radius: 8px; margin-bottom: 8px; }
+`;
+    THANKS_MS = 1100;
+  }
+});
+
 // src/capture.ts
 init_privacy();
 var TRAIL_MAX = 30;
@@ -573,6 +724,117 @@ function canPrompt(state, now, caps = DEFAULT_CAPS) {
   return true;
 }
 
+// src/intervention.ts
+var RENDERABLE = /* @__PURE__ */ new Set(["survey"]);
+function str(v, max) {
+  if (typeof v !== "string") return void 0;
+  const t = v.trim();
+  return t ? t.slice(0, max) : void 0;
+}
+function buildServeContext(route, identity) {
+  const ctx = {};
+  const r = str(route, 500);
+  if (r) ctx.route = r;
+  const account = str(identity == null ? void 0 : identity.account, 200);
+  if (account) ctx.account = account;
+  const plan = str(identity == null ? void 0 : identity.plan, 80);
+  if (plan) ctx.plan = plan;
+  return ctx;
+}
+function normalizeServed(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw;
+  const id = str(r.id, 64);
+  const type = str(r.type, 40);
+  if (!id || !type || !RENDERABLE.has(type)) return null;
+  const cfg = r.config && typeof r.config === "object" ? r.config : {};
+  const question = str(cfg.question, 500);
+  if (!question) return null;
+  const options = Array.isArray(cfg.options) ? cfg.options.map((o) => str(o, 200)).filter((o) => !!o).slice(0, 6) : void 0;
+  const config = {
+    question,
+    ...options && options.length ? { options } : {},
+    allow_text: cfg.allow_text === true
+  };
+  return { id, type, config };
+}
+function pickRespondentKey(userId, persisted, sessionRef) {
+  const uid = str(userId, 200);
+  if (uid) return uid;
+  const p = str(persisted, 200);
+  if (p) return p;
+  return sessionRef;
+}
+var RK_STORAGE_KEY = "sightspool_rk";
+function getRespondentKey(identity, sessionRef) {
+  const uid = str(identity == null ? void 0 : identity.userId, 200);
+  if (uid) return uid;
+  try {
+    let v = localStorage.getItem(RK_STORAGE_KEY);
+    if (!v) {
+      v = "anon-" + Math.random().toString(36).slice(2) + Date.now().toString(36);
+      localStorage.setItem(RK_STORAGE_KEY, v);
+    }
+    return pickRespondentKey(void 0, v, sessionRef);
+  } catch (e) {
+    return sessionRef;
+  }
+}
+function serveUrl(endpoint, path) {
+  return `${endpoint.replace(/\/+$/, "")}/api/sdk/${path}`;
+}
+async function fetchIntervention(opts) {
+  var _a2;
+  try {
+    if (typeof fetch !== "function") return null;
+    const res = await fetch(serveUrl(opts.endpoint, "serve"), {
+      method: "POST",
+      headers: { "Content-Type": "text/plain" },
+      body: JSON.stringify({
+        key: opts.key,
+        context: opts.ctx,
+        respondent_key: opts.respondentKey
+      }),
+      mode: "cors",
+      credentials: "omit"
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    const served = normalizeServed(data == null ? void 0 : data.intervention);
+    if (opts.debug) console.debug("[sightspool] serve", (_a2 = served == null ? void 0 : served.id) != null ? _a2 : "(none)");
+    return served;
+  } catch (e) {
+    return null;
+  }
+}
+function submitResponse(opts) {
+  try {
+    const url = serveUrl(opts.endpoint, "respond");
+    const json = JSON.stringify({
+      key: opts.key,
+      intervention_id: opts.interventionId,
+      response: opts.response,
+      respondent_key: opts.respondentKey
+    });
+    if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+      const blob = new Blob([json], { type: "text/plain" });
+      if (navigator.sendBeacon(url, blob)) return;
+    }
+    if (typeof fetch === "function") {
+      void fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "text/plain" },
+        body: json,
+        keepalive: true,
+        mode: "cors",
+        credentials: "omit"
+      }).catch(() => {
+      });
+    }
+  } catch (e) {
+  }
+}
+
 // src/env.ts
 var LOCAL_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "0.0.0.0", "::1", ""]);
 function isLocalhost(hostname) {
@@ -585,6 +847,8 @@ function isLocalhost(hostname) {
 var DEFAULT_ENDPOINT = "https://app.sightspool.com";
 var FRICTION_EMIT_COOLDOWN_MS = 3e4;
 var EVENT_DEBOUNCE_MS = 600;
+var SERVE_SETTLE_MS = 2500;
+var MAX_INTERVENTIONS_PER_SESSION = 1;
 function currentHostname() {
   try {
     return typeof location !== "undefined" ? location.hostname : "";
@@ -649,9 +913,53 @@ async function maybePrompt(c, trigger) {
     c.egress.enqueue(buildSignal(c, trigger));
   }
 }
+async function maybeServeIntervention(c) {
+  if (!c.running || !c.interventionsEnabled || c.suppressed) return;
+  if (c.surveyOnScreen) return;
+  if (c.interventionsShown >= MAX_INTERVENTIONS_PER_SESSION) return;
+  const now = Date.now();
+  if (c.fatigue.lastPromptAt !== null && now - c.fatigue.lastPromptAt < DEFAULT_CAPS.cooldownMs)
+    return;
+  const respondentKey = getRespondentKey(c.identity, c.sessionRef);
+  const served = await fetchIntervention({
+    endpoint: c.config.endpoint,
+    key: c.config.key,
+    ctx: buildServeContext(c.capture.route(), c.identity),
+    respondentKey,
+    debug: c.config.debug
+  });
+  if (!served || !c.running) return;
+  c.surveyOnScreen = true;
+  c.interventionsShown += 1;
+  c.fatigue.lastPromptAt = Date.now();
+  try {
+    const { showSurvey: showSurvey2 } = await Promise.resolve().then(() => (init_survey(), survey_exports));
+    const result = await showSurvey2(served.config);
+    if (!result.dismissed && (result.choice || result.text)) {
+      submitResponse({
+        endpoint: c.config.endpoint,
+        key: c.config.key,
+        interventionId: served.id,
+        response: { choice: result.choice, text: result.text },
+        respondentKey
+      });
+    }
+  } catch (e) {
+  } finally {
+    c.surveyOnScreen = false;
+  }
+}
 function onCaptureEvent() {
   const c = ctrl;
   if (!c || !c.running) return;
+  try {
+    const route = c.capture.route();
+    if (route && route !== c.lastServeRoute) {
+      c.lastServeRoute = route;
+      void maybeServeIntervention(c);
+    }
+  } catch (e) {
+  }
   if (c.eventTimer !== null) return;
   c.eventTimer = (typeof window !== "undefined" ? window.setTimeout : setTimeout)(() => {
     c.eventTimer = null;
@@ -692,6 +1000,18 @@ function startRuntime(c) {
     document.addEventListener("mouseout", onExitIntent);
   } catch (e) {
   }
+  if (c.interventionsEnabled) {
+    c.lastServeRoute = (() => {
+      try {
+        return c.capture.route();
+      } catch (e) {
+        return null;
+      }
+    })();
+    (typeof window !== "undefined" ? window.setTimeout : setTimeout)(() => {
+      void maybeServeIntervention(c);
+    }, SERVE_SETTLE_MS);
+  }
   if (c.config.debug) console.debug("[sightspool] started", c.sessionRef);
 }
 function init(config) {
@@ -723,7 +1043,11 @@ function init(config) {
       lastFrictionEmitAt: 0,
       eventTimer: null,
       running: false,
-      suppressed: isLocalhost(currentHostname()) && config.captureOnLocalhost !== true
+      suppressed: isLocalhost(currentHostname()) && config.captureOnLocalhost !== true,
+      interventionsEnabled: config.interventions !== false,
+      lastServeRoute: null,
+      surveyOnScreen: false,
+      interventionsShown: 0
     };
     if (config.consent !== false) startRuntime(ctrl);
   } catch (err) {
@@ -796,6 +1120,7 @@ try {
         redact: list("data-sightspool-redact"),
         block: list("data-sightspool-block"),
         captureOnLocalhost: (el == null ? void 0 : el.hasAttribute("data-sightspool-capture-localhost")) || void 0,
+        interventions: (el == null ? void 0 : el.hasAttribute("data-sightspool-no-interventions")) ? false : void 0,
         debug: (el == null ? void 0 : el.hasAttribute("data-sightspool-debug")) || void 0
       });
     }