npm - @whisperr/wizard - Versions diffs - 0.1.4 → 0.1.6 - Mend

@whisperr/wizard 0.1.4 → 0.1.6

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 (2) hide show

package/dist/index.js +141 -50
package/package.json +1 -1

package/dist/index.js CHANGED Viewed

@@ -113,7 +113,7 @@ var target2 = {
   id: "nextjs",
   displayName: "Next.js",
   language: "typescript",
-  availability: "planned"
+  availability: "available"
 };
 async function detect2(ctx) {
   if (!await ctx.exists("package.json")) return null;
@@ -140,34 +140,37 @@ async function detect2(ctx) {
   return { target: target2, confidence: Math.min(confidence, 1), evidence };
 }
 var systemPrompt2 = `
-## SDK: Whisperr for Web in Next.js \u2014 package \`@whisperr/web\`
+## SDK: Whisperr for Next.js \u2014 package \`@whisperr/next\` (+ \`@whisperr/web\`)
-Same SDK as plain web, with Next-specific wiring.
+1) Install: \`<pm> add @whisperr/next @whisperr/web\`. Put the key in
+   NEXT_PUBLIC_WHISPERR_KEY in .env.local (and add it to .env.example).
-1) Install \`@whisperr/web\`. Put the key in NEXT_PUBLIC_WHISPERR_KEY in
-   .env.local (and add it to .env.example).
+2) Mount the provider in app/layout.tsx. It is already a 'use client' boundary,
+   so it drops straight into the server-component layout \u2014 no wrapper file needed:
+     import { WhisperrProvider } from '@whisperr/next';
+     // inside <body>:
+     <WhisperrProvider apiKey={process.env.NEXT_PUBLIC_WHISPERR_KEY!}>{children}</WhisperrProvider>
+   Pages Router: wrap the tree in pages/_app.tsx with <WhisperrProvider apiKey=...>.
-2) Whisperr runs client-side. Create a client provider:
-   - App Router: a 'use client' component (e.g. app/whisperr-provider.tsx) that
-     calls Whisperr.init(...) in a useEffect and renders children; mount it in
-     app/layout.tsx.
-   - Pages Router: init in pages/_app.tsx inside a useEffect.
+3) identify() after auth resolves on the client (in your session hook/effect);
+   reset() on sign-out. Use the useWhisperr() hook inside 'use client' components.
-3) identify() after auth resolves on the client (e.g. in your auth/session
-   hook). reset() on sign-out.
-4) track() in client components / event handlers / mutation callbacks. Do NOT
-   call track from server components, route handlers, or getServerSideProps \u2014
-   this SDK is a browser client. Copy event_type verbatim from the manifest.
+4) track() in client components / event handlers / mutation callbacks:
+     'use client';
+     import { useWhisperr } from '@whisperr/next';
+     const whisperr = useWhisperr();
+     whisperr.track('event_type_from_manifest', { ... });
+   Do NOT call track from server components, route handlers, or getServerSideProps \u2014
+   it is a browser client. Copy event_type verbatim (snake_case) from the manifest.
 Notes:
-- Guard against double-init under React Strict Mode (init is idempotent, but
-  wire it so it only runs once).
+- Pageviews are auto-captured via the History API (covers Next client navigation).
+- Provider init is idempotent (safe under React Strict Mode).
 `.trim();
 var nextjsPlaybook = {
   target: target2,
   detect: detect2,
-  packageRef: "@whisperr/web (npm)",
+  packageRef: "@whisperr/next (npm)",
   systemPrompt: systemPrompt2
 };
@@ -176,8 +179,7 @@ var target3 = {
   id: "web-js",
   displayName: "Web (JavaScript / TypeScript)",
   language: "typescript",
-  // Flip to "available" once @whisperr/web ships (Phase 2).
-  availability: "planned"
+  availability: "available"
 };
 function dependsOn(pkgJson, names) {
   try {
@@ -209,41 +211,41 @@ async function detect3(ctx) {
   return { target: target3, confidence: Math.min(confidence, 0.95), evidence };
 }
 var systemPrompt3 = `
-## SDK: Whisperr for Web (TypeScript/JavaScript) \u2014 package \`@whisperr/web\`
+## SDK: Whisperr for Web \u2014 package \`@whisperr/web\` (+ \`@whisperr/react\` for React)
-1) Dependency. Install with the repo's package manager (detect pnpm/yarn/npm
-   from the lockfile): \`<pm> add @whisperr/web\`.
+1) Install (detect pnpm/yarn/npm from the lockfile):
+   - Vanilla / Vue / Svelte / Angular / plain TS: \`<pm> add @whisperr/web\`
+   - React (not Next.js): \`<pm> add @whisperr/react @whisperr/web\`
-2) Initialize once at app entry (e.g. src/main.tsx, src/index.ts, or the root
-   layout). Create a singleton client:
-     import { Whisperr } from '@whisperr/web';
-     export const whisperr = Whisperr.init({
-       apiKey: import.meta.env.VITE_WHISPERR_KEY, // or process.env.NEXT_PUBLIC_... etc
-       baseUrl: '<INGESTION_BASE_URL from manifest>',
-     });
-   Put the key in the project's env mechanism (Vite VITE_*, CRA REACT_APP_*,
-   plain .env) and write the example var into .env / .env.example.
+2) Initialize once at app entry, using the app's PUBLIC env var (VITE_*,
+   REACT_APP_*, etc.). Write the var into .env / .env.example.
+   - Core (any framework): create a singleton in e.g. src/whisperr.ts:
+       import { Whisperr } from '@whisperr/web';
+       export const whisperr = Whisperr.init({
+         apiKey: import.meta.env.VITE_WHISPERR_KEY,
+         baseUrl: '<INGESTION_BASE_URL from manifest>', // omit if it's the default
+       });
+   - React: wrap the app root instead of a bare singleton:
+       import { WhisperrProvider } from '@whisperr/react';
+       <WhisperrProvider apiKey={import.meta.env.VITE_WHISPERR_KEY}>\u2026</WhisperrProvider>
 3) identify(). After auth resolves (login success, and on app load if a session
    is restored):
-     whisperr.identify(user.id, {
-       traits: { /* manifest traits */ },
-       email: user.email, phone: user.phone,
-     });
+       whisperr.identify(user.id, { traits: { /* manifest traits */ }, email: user.email, phone: user.phone });
+   React: const whisperr = useWhisperr();  then whisperr.identify(...).
    Call whisperr.reset() on logout.
 4) track(). For each manifest event, instrument the real handler:
-     whisperr.track('event_type_from_manifest', { /* properties */ });
-   In React, this belongs in event handlers / effects / mutation callbacks, not
+       whisperr.track('event_type_from_manifest', { /* properties */ });
+   In React this belongs in event handlers / effects / mutation callbacks, never
    in render. Copy event_type verbatim (snake_case) from the manifest.
 Notes:
-- The SDK batches via /v1/events/batch and flushes on a timer + on
-  visibilitychange/unload (sendBeacon). Fire-and-forget is fine.
-- Only the NEXT_PUBLIC_/VITE_-style public env vars are exposed to the browser;
-  the ingestion key is a public, rate-limited key so that is expected.
-- If the project uses an analytics wrapper/provider pattern, follow it rather
-  than scattering raw whisperr.track calls.
+- The SDK batches + flushes automatically (timer + on page hide). Fire-and-forget
+  is fine; do NOT await track().
+- It auto-captures pageviews \u2014 you only add the named business events.
+- Only PUBLIC env vars (VITE_/REACT_APP_/NEXT_PUBLIC_) reach the browser; the
+  ingestion key is meant to be public + rate-limited, so that's expected.
 `.trim();
 var webPlaybook = {
   target: target3,
@@ -522,10 +524,11 @@ function sleep(ms) {
 }
 // src/core/manifest.ts
-async function fetchManifest(config, session, targetId) {
+async function fetchManifest(config, session, targetId, repoFingerprint2) {
   if (config.offline) return mockManifest(session.appId, config);
   const url = new URL(`${config.apiBaseUrl}/wizard/manifest`);
   if (targetId) url.searchParams.set("target", targetId);
+  if (repoFingerprint2) url.searchParams.set("repo", repoFingerprint2);
   const res = await fetch(url, {
     headers: { authorization: `Bearer ${session.token}` }
   });
@@ -680,10 +683,17 @@ function renderEventsBrief(m) {
   lines.push(
     `${events.length} candidate events (highest-impact first). For each: fire track('<event_type>', { ...properties }) at the real moment it happens, and attach every listed property you can source from values in scope there. Skip an event entirely if it has no clear client-side trigger.`
   );
+  if (events.some((e) => e.coverage?.length)) {
+    lines.push("");
+    lines.push(
+      "Some events are already instrumented elsewhere (noted inline). Skip any marked [already wired here]; for [wired on <surface>], only add it if this codebase ALSO genuinely triggers it."
+    );
+  }
   for (const e of events) {
     lines.push("");
     const why = e.interventions?.length ? `  \xB7  drives: ${e.interventions.map((i) => i.label ?? i.code).join(", ")}` : "";
-    lines.push(`\u25A0 ${e.eventType}${e.label ? `  (${e.label})` : ""}${why}`);
+    const cov = coverageNote(e.coverage);
+    lines.push(`\u25A0 ${e.eventType}${e.label ? `  (${e.label})` : ""}${why}${cov}`);
     if (e.description) lines.push(`  ${e.description}`);
     if (e.properties?.length) {
       lines.push("  properties to capture if available:");
@@ -696,6 +706,16 @@ function renderEventsBrief(m) {
   }
   return lines.join("\n");
 }
+function coverageNote(coverage) {
+  if (!coverage?.length) return "";
+  const here = coverage.find((c) => c.sameSurface && c.status === "wired");
+  if (here) return "  [already wired here]";
+  const elsewhere = coverage.filter((c) => c.status === "wired");
+  if (elsewhere.length) {
+    return `  [wired on ${elsewhere.map((c) => c.target).join(", ")}]`;
+  }
+  return "";
+}
 // src/core/agent.ts
 async function runIntegrationAgent(opts) {
@@ -867,6 +887,9 @@ function short(s, max = 60) {
 // src/core/git.ts
 import { spawn } from "child_process";
+import { createHash } from "crypto";
+import { readFile as readFile2 } from "fs/promises";
+import { basename, join as join2 } from "path";
 async function takeCheckpoint(repoPath) {
   const isRepo = (await run(repoPath, ["rev-parse", "--is-inside-work-tree"])).ok;
   if (!isRepo) return { isRepo: false };
@@ -897,6 +920,38 @@ function revertHint(checkpoint) {
   if (!checkpoint.isRepo || !checkpoint.baseRef) return void 0;
   return `git restore . && git clean -fd   (back to ${checkpoint.baseRef.slice(0, 7)})`;
 }
+async function repoFingerprint(repoPath) {
+  const remote = await run(repoPath, ["remote", "get-url", "origin"]);
+  const seed = remote.ok && remote.stdout.trim() ? normalizeRemote(remote.stdout.trim()) : `dir:${basename(repoPath)}`;
+  return createHash("sha256").update(seed).digest("hex").slice(0, 16);
+}
+function normalizeRemote(url) {
+  return url.replace(/^git@([^:]+):/, "$1/").replace(/^https?:\/\//, "").replace(/\.git$/, "").replace(/\/+$/, "").toLowerCase();
+}
+async function scanWiredEvents(repoPath, files, eventTypes) {
+  const wired = /* @__PURE__ */ new Map();
+  const patterns = eventTypes.map((e) => ({
+    eventType: e,
+    re: new RegExp(`track\\s*\\(\\s*['"\`]${escapeRegExp(e)}['"\`]`)
+  }));
+  for (const file of files) {
+    let content = "";
+    try {
+      content = await readFile2(join2(repoPath, file), "utf8");
+    } catch {
+      continue;
+    }
+    for (const { eventType, re } of patterns) {
+      if (!wired.has(eventType) && re.test(content)) {
+        wired.set(eventType, file);
+      }
+    }
+  }
+  return wired;
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function run(cwd, args) {
   return new Promise((resolve2) => {
     const child = spawn("git", args, { cwd });
@@ -934,6 +989,22 @@ async function pollFirstEvent(config, session, opts = {}) {
   return { received: false };
 }
+// src/core/report.ts
+async function postRunReport(config, session, report) {
+  if (config.offline) return;
+  try {
+    await fetch(`${config.apiBaseUrl}/wizard/report`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${session.token}`
+      },
+      body: JSON.stringify(report)
+    });
+  } catch {
+  }
+}
 // src/ui/banner.ts
 function banner() {
   const wave = theme.signal("\u223F\u223F\u223F");
@@ -997,9 +1068,10 @@ Flutter is live today; ${theme.bright(
     p.cancel(theme.alert(err.message));
     return 1;
   }
+  const fingerprint = await repoFingerprint(repoPath);
   const manifest = await withSpinner(
     "Loading your onboarding context",
-    () => fetchManifest(config, session, chosen.playbook.target.id)
+    () => fetchManifest(config, session, chosen.playbook.target.id, fingerprint)
   );
   p.note(
     summarizeManifest(manifest),
@@ -1055,9 +1127,28 @@ Flutter is live today; ${theme.bright(
   if (outcome.summary.trim()) {
     p.log.message(outcome.summary.trim());
   }
+  const wiredMap = await scanWiredEvents(
+    repoPath,
+    files,
+    manifest.events.map((e) => e.eventType)
+  );
+  const reportEvents = manifest.events.map((e) => ({
+    event_type: e.eventType,
+    status: wiredMap.has(e.eventType) ? "wired" : "skipped",
+    file: wiredMap.get(e.eventType)
+  }));
+  await postRunReport(config, session, {
+    target: chosen.playbook.target.id,
+    repo_fingerprint: fingerprint,
+    identify_wired: outcome.coreOk,
+    cost_usd: outcome.costUsd,
+    duration_ms: outcome.durationMs,
+    summary: outcome.summary.slice(0, 4e3),
+    events: reportEvents
+  });
   p.log.info(
     theme.muted(
-      `${files.length} file${files.length === 1 ? "" : "s"} changed \xB7 ~$${outcome.costUsd.toFixed(2)} \xB7 ${Math.round(outcome.durationMs / 1e3)}s`
+      `${wiredMap.size}/${manifest.events.length} events wired \xB7 ${files.length} file${files.length === 1 ? "" : "s"} changed \xB7 ~$${outcome.costUsd.toFixed(2)} \xB7 ${Math.round(outcome.durationMs / 1e3)}s`
     )
   );
   if (!config.offline) {
@@ -1226,7 +1317,7 @@ async function main() {
     return;
   }
   if ("version" in parsed) {
-    console.log("0.1.4");
+    console.log("0.1.6");
     return;
   }
   try {

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@whisperr/wizard",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Whisperr Wizard — one command to integrate the Whisperr SDK into your app. Authenticates with your onboarded account and uses an AI coding agent to wire up identify() and your business events automatically.",
   "license": "UNLICENSED",
   "private": false,