npm - @sightspool/sdk - Versions diffs - 0.1.1 → 0.2.1 - Mend

@sightspool/sdk 0.1.1 → 0.2.1

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 +76 -22
package/dist/index.cjs +327 -2
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 +176 -2
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 +1 -1

package/README.md CHANGED Viewed

@@ -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)
 ---
@@ -47,7 +47,7 @@ call for their analytics/support tools.
 ```html
 <script
   async
-  src="https://app.sightspool.com/sdk.global.js"
+  src="https://www.sightspool.com/sdk.global.js"
   data-sightspool-key="pk_live_…"
 ></script>
 ```
@@ -70,7 +70,7 @@ The script tag also reads these optional attributes (the no-build equivalent of
 ```html
 <script
   async
-  src="https://app.sightspool.com/sdk.global.js"
+  src="https://www.sightspool.com/sdk.global.js"
   data-sightspool-key="pk_live_…"
   data-sightspool-block=".billing-panel, [data-private]"
   data-sightspool-redact=".customer-name"
@@ -88,8 +88,9 @@ The script tag also reads these optional attributes (the no-build equivalent of
 | option | type | default | purpose |
 |---|---|---|---|
 | `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. |
+| `endpoint` | `string` | the bundle's origin (script tag) / `https://www.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. |
@@ -163,7 +164,7 @@ export default function RootLayout({ children }: { children: React.ReactNode })
       <body>
         {children}
         <Script
-          src="https://app.sightspool.com/sdk.global.js"
+          src="https://www.sightspool.com/sdk.global.js"
           data-sightspool-key={process.env.NEXT_PUBLIC_SIGHTSPOOL_KEY}
           strategy="afterInteractive"
         />
@@ -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>
 ---
@@ -221,15 +237,15 @@ 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;
+script-src  https://www.sightspool.com;
+connect-src https://www.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;
+connect-src https://www.sightspool.com;
 ```
 If you pass a custom `endpoint`, use *that* origin in `connect-src`. The beacon goes via
@@ -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://www.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) {
@@ -582,9 +844,11 @@ function isLocalhost(hostname) {
 }
 // src/index.ts
-var DEFAULT_ENDPOINT = "https://app.sightspool.com";
+var DEFAULT_ENDPOINT = "https://www.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
       });
     }