npm - @sightspool/sdk - Versions diffs - 0.1.0 → 0.2.0 - Mend

@sightspool/sdk 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md +193 -1
package/dist/index.cjs +326 -1
package/dist/index.cjs.map +1 -1
package/dist/index.d.cts +2 -0
package/dist/index.d.ts +2 -0
package/dist/index.js +175 -1
package/dist/index.js.map +1 -1
package/dist/sdk.global.js +21 -3
package/dist/sdk.global.js.map +1 -1
package/dist/survey-CICJQ5VI.js +145 -0
package/dist/survey-CICJQ5VI.js.map +1 -0
package/package.json +9 -7

package/README.md CHANGED Viewed

@@ -14,6 +14,10 @@ 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://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)
 ---
 ## Install — two lines
@@ -83,9 +87,10 @@ The script tag also reads these optional attributes (the no-build equivalent of
 | option | type | default | purpose |
 |---|---|---|---|
-| `key` | `string` | — | **required.** Your publishable key (`pk_live_…`), from the Connections → In-product SDK card. Publishable — safe to ship in client JS. |
+| `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. |
@@ -107,6 +112,193 @@ un-allowlisted origin.
 ---
+## Keys & environments
+Your key is **publishable** — safe to ship in client JS (the Stripe `pk_` model). Two
+prefixes, one per environment:
+| prefix | use it for |
+|---|---|
+| `pk_test_…` | development / staging / preview deploys |
+| `pk_live_…` | production |
+The SDK treats both prefixes **identically** — there's no client-side special-casing; the
+prefix tells *Sightspool* (at ingest) which environment a Signal belongs to, so test traffic
+never mixes into production analytics. Issue both from **Connections → In-product SDK**.
+> The SDK also **no-ops on localhost** by default (see `captureOnLocalhost`), so even a
+> `pk_live_` key won't capture from `npm run dev`. Test keys are for *deployed* non-prod
+> environments (staging, previews).
+Keep the key in an environment variable rather than hardcoding it, and pick test vs live by
+environment. The key is exposed to the browser, so use your framework's **client** env-var
+prefix (`NEXT_PUBLIC_`, `VITE_`, `PUBLIC_`, …) — it's publishable, so that's expected:
+```js
+Sightspool.init({ key: process.env.NEXT_PUBLIC_SIGHTSPOOL_KEY })
+```
+```bash
+# .env.development / preview
+NEXT_PUBLIC_SIGHTSPOOL_KEY=pk_test_…
+# .env.production
+NEXT_PUBLIC_SIGHTSPOOL_KEY=pk_live_…
+```
+---
+## Framework integration
+### Next.js (App Router) — `next/script`
+The idiomatic install is `next/script`, not a raw `<script>`. Add it once in your root
+layout — the tag auto-`init`s from `data-sightspool-key`:
+```tsx
+// app/layout.tsx
+import Script from 'next/script'
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <Script
+          src="https://app.sightspool.com/sdk.global.js"
+          data-sightspool-key={process.env.NEXT_PUBLIC_SIGHTSPOOL_KEY}
+          strategy="afterInteractive"
+        />
+      </body>
+    </html>
+  )
+}
+```
+Then `identify` the user once known (e.g. a client component after auth):
+```tsx
+'use client'
+useEffect(() => {
+  window.Sightspool?.identify(user.id, { account: user.account, plan: user.plan })
+}, [user])
+```
+> `data-sightspool-key` is inlined at build time, so `NEXT_PUBLIC_SIGHTSPOOL_KEY` must be set
+> in the environment Next builds in. `strategy="afterInteractive"` keeps it off the critical
+> path.
+### React / Next.js — `@sightspool/react`
+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])
+  return null
+}
+```
+</details>
+---
+## Content-Security-Policy
+If your app sets a CSP, allow the SDK's two footprints — the **script load** and the
+**ingest beacon**. With the standard install they're the *same host* (the bundle is served
+from the app it ingests to), so it's one host in two directives:
+**Script-tag install**
+```
+script-src  https://app.sightspool.com;
+connect-src https://app.sightspool.com;
+```
+**npm / bundler install** — the SDK is bundled into your own first-party JS, so no
+`script-src` host is needed; only the ingest origin:
+```
+connect-src https://app.sightspool.com;
+```
+If you pass a custom `endpoint`, use *that* origin in `connect-src`. The beacon goes via
+`navigator.sendBeacon` with a `fetch(keepalive)` fallback — both governed by `connect-src`.
+- **`strict-dynamic` / nonce.** Under `script-src 'strict-dynamic'`, host allowlists are
+  ignored for scripts — give the `<script>` tag your per-request nonce (`nonce={nonce}` in
+  Next) so it's trusted. `connect-src` still needs the ingest host.
+- **Prompt styles.** The one-tap prompt renders into a **shadow root** and injects its own
+  `<style>`. Under a strict `style-src` without `'unsafe-inline'`, those styles may not apply
+  — the prompt stays **fully functional but unstyled** (the SDK never throws into your page).
+  Add `'unsafe-inline'` to `style-src` if you want it styled.
+---
+## 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 CHANGED Viewed

@@ -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
       });
     }