@whisperr/wizard 0.1.14 → 0.2.0

package/dist/index.js

@@ -11,7 +11,7 @@ import * as p from "@clack/prompts";
 
 // src/core/config.ts
 var DEFAULT_API_BASE = "https://api.whisperr.net";
-var DEFAULT_MODEL = "claude-sonnet-4-6";
+var DEFAULT_MODEL = "claude-sonnet-5";
 var DEFAULT_EFFORT = "high";
 var EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
 function resolveEffort() {
@@ -647,51 +647,135 @@ var phpPlaybook = {
 // src/core/playbooks/react-native.ts
 var target7 = {
   id: "react-native",
-  displayName: "React Native",
+  displayName: "React Native / Expo",
   language: "typescript",
-  availability: "planned"
+  availability: "available"
 };
 async function detect7(ctx) {
   if (!await ctx.exists("package.json")) return null;
   const pkgJson = await ctx.read("package.json");
-  let match = false;
+  let hasRN = false;
+  let hasExpo = false;
   try {
     const pkg = JSON.parse(pkgJson);
     const all = { ...pkg.dependencies ?? {}, ...pkg.devDependencies ?? {} };
-    match = "react-native" in all || "expo" in all;
+    hasRN = "react-native" in all;
+    hasExpo = "expo" in all;
   } catch {
-    match = false;
   }
-  if (!match) return null;
-  const evidence = ["react-native / expo dependency"];
+  if (!hasRN && !hasExpo) return null;
+  const evidence = [];
+  if (hasExpo) evidence.push("expo dependency");
+  if (hasRN) evidence.push("react-native dependency");
   let confidence = 0.85;
   if (await ctx.exists("app.json")) {
     evidence.push("app.json");
     confidence += 0.1;
+  } else if (await ctx.exists("app.config.js") || await ctx.exists("app.config.ts")) {
+    evidence.push("app.config");
+    confidence += 0.1;
   }
   return { target: target7, confidence: Math.min(confidence, 1), evidence };
 }
 var systemPrompt7 = `
 ## SDK: Whisperr for React Native \u2014 package \`@whisperr/react-native\`
 
-1) Install \`@whisperr/react-native\` with the repo's package manager. If it has
-   native modules, run pod install for iOS (mention it; don't attempt to build).
+Pure TypeScript, ZERO native code and zero dependencies of its own: it works in
+Expo Go, bare React Native, and dev clients with no pod install, no config
+plugin, no prebuild. Do not add or modify anything under ios/ or android/ for
+the SDK itself.
+
+0) Expo or bare? Decide first \u2014 it changes storage install + key handling.
+   Expo = \`expo\` in package.json dependencies (usually with app.json /
+   app.config.* containing an "expo" key).
+
+1) Install with the repo's package manager (pick by lockfile: pnpm-lock.yaml \u2192
+   pnpm, yarn.lock \u2192 yarn, bun.lockb \u2192 bun, else npm):
+       <pm> add @whisperr/react-native
+
+2) Durable storage \u2014 IMPORTANT. The SDK's offline queue is MEMORY-ONLY unless
+   you inject an AsyncStorage-compatible adapter (\`getItem\`/\`setItem\`/
+   \`removeItem\`); the SDK never imports native modules itself. In priority
+   order:
+   - \`@react-native-async-storage/async-storage\` already a dependency \u2192 import
+     it and pass as \`storage\`.
+   - The app already uses \`react-native-mmkv\` \u2192 reuse its existing instance
+     with a 3-line adapter (do NOT add a new storage dep):
+       const storage = {
+         getItem: (k: string) => mmkv.getString(k) ?? null,
+         setItem: (k: string, v: string) => { mmkv.set(k, v); },
+         removeItem: (k: string) => { mmkv.delete(k); },
+       };
+   - Neither \u2192 add async-storage. Expo: run \`npx expo install
+     @react-native-async-storage/async-storage\` via bash (installs the
+     SDK-matched version; works in Expo Go \u2014 it ships in the Go client). Bare
+     RN: \`<pm> add @react-native-async-storage/async-storage\` and note
+     "run npx pod-install before the next iOS build" as a follow-up (it IS a
+     native module; do not run pod install yourself).
+   Never silently ship without storage \u2014 if you genuinely can't add it, say so
+   in the summary.
+
+3) Initialize ONCE via a module singleton, e.g. src/whisperr.ts (match the
+   repo's source layout \u2014 src/, lib/, app/lib/\u2026):
+       import AsyncStorage from '@react-native-async-storage/async-storage';
+       import { Whisperr } from '@whisperr/react-native';
 
-2) Initialize once at the app root (App.tsx / app/_layout.tsx for Expo Router):
-     import { Whisperr } from '@whisperr/react-native';
-     Whisperr.init({ apiKey: <key from manifest/env>, baseUrl: <manifest baseUrl> });
-
-3) identify() after auth resolves / on session restore; reset() on logout.
-   For channels: email/phone where known, and the push token (expo-notifications
-   or @react-native-firebase/messaging) if the app has push set up.
-
-4) track() in event handlers / business logic, never in render. event_type
-   verbatim from the manifest.
+       export const whisperr = Whisperr.init({
+         apiKey: process.env.EXPO_PUBLIC_WHISPERR_KEY!,
+         storage: AsyncStorage,
+         baseUrl: '<INGESTION_BASE_URL from manifest>', // omit if it's the SDK default
+       });
+   Import the module for its side effect from the app entry: Expo Router \u2192
+   app/_layout.tsx (root layout); bare / React Navigation \u2192 App.tsx (or
+   index.js). Prefer the singleton over <WhisperrProvider> \u2014 auth listeners,
+   API clients, and non-component code can import it directly. If the codebase
+   is strongly hook-oriented you may ADDITIONALLY wrap the root with
+   <WhisperrProvider client={whisperr}> and use useWhisperr() in components \u2014
+   but never create a second client.
+   Whisperr.init() is an idempotent singleton \u2014 safe under Fast Refresh and
+   React StrictMode.
+
+   Key handling (the key is a publishable ingestion key \u2014 shipping it in the
+   bundle is expected):
+   - Expo SDK 49+: put EXPO_PUBLIC_WHISPERR_KEY=<key> in .env (create or
+     append) and mirror it in .env.example; reference via
+     process.env.EXPO_PUBLIC_WHISPERR_KEY.
+   - Bare RN with react-native-config: add WHISPERR_KEY to .env and read
+     Config.WHISPERR_KEY.
+   - Otherwise: a small constants file with the literal key is acceptable.
+
+4) identify() right after the end-user is known \u2014 on login/signup success AND
+   on session restore at app startup:
+       whisperr.identify(user.id, {
+         traits: { /* manifest traits sourced from the user object */ },
+         email: user.email,           // shortcut \u2192 opted-in email channel
+         phone: user.phone,           // shortcut \u2192 sms channel
+         pushToken: expoPushToken,    // shortcut \u2192 push channel, if the app
+                                      // registers for push (expo-notifications
+                                      // or @react-native-firebase/messaging)
+       });
+   Call whisperr.reset() on logout (already-queued events keep their user).
+   ANONYMOUS EVENTS ARE FINE: track() before identify() buffers on-device and
+   attributes to the user retroactively on identify() \u2014 do NOT gate track()
+   calls behind auth state, and do NOT skip pre-login manifest events.
+
+5) track() in event handlers / business logic (onPress, mutation onSuccess,
+   store/saga/thunk actions) \u2014 never in render:
+       whisperr.track('event_type_from_manifest', { /* properties in scope */ });
+   Synchronous fire-and-forget: it returns void \u2014 do NOT await it. Batching,
+   retries, background flush are all internal. event_type verbatim snake_case
+   from the manifest \u2014 the SDK client-side drops invalid names.
 
-Notes:
-- Persisted offline queue is built in (AsyncStorage); fire-and-forget is fine.
-- Prefer an env/config mechanism (react-native-config, app.config) for the key
-  if one exists; otherwise a constants file is acceptable.
+Notes / gotchas:
+- Every call is sync void except flush(); the only sensible manual flush is
+  \`await whisperr.flush()\` right before something destroys the process.
+- The SDK auto-flushes on an interval, at 20 queued events, and when the app
+  backgrounds. Don't sprinkle flush() calls.
+- whisperr.screen(name) records a screen_viewed event \u2014 wire it to the
+  navigation container's state-change callback ONLY if the manifest includes a
+  screen/page-view style event; otherwise leave navigation alone.
+- Works on the New Architecture and in Expo Go by construction (no native
+  code). Never suggest expo prebuild / dev-client for this SDK.
 `.trim();
 var reactNativePlaybook = {
   target: target7,
@@ -703,9 +787,9 @@ var reactNativePlaybook = {
 // src/core/playbooks/swift.ts
 var target8 = {
   id: "swift",
-  displayName: "Swift (iOS)",
+  displayName: "Swift (iOS / Apple)",
   language: "swift",
-  availability: "planned"
+  availability: "available"
 };
 async function detect8(ctx) {
   const evidence = [];
@@ -727,40 +811,115 @@ async function detect8(ctx) {
     evidence.push("Podfile");
     confidence += 0.2;
   }
+  if (await ctx.exists("Project.swift")) {
+    evidence.push("Project.swift (Tuist)");
+    confidence += 0.4;
+  }
+  if (await ctx.exists("project.yml")) {
+    evidence.push("project.yml (XcodeGen)");
+    confidence += 0.3;
+  }
   if (confidence === 0) return null;
   return { target: target8, confidence: Math.min(confidence, 1), evidence };
 }
 var systemPrompt8 = `
-## SDK: Whisperr for Swift (iOS) \u2014 Swift Package \`Whisperr\`
-
-1) Add the Swift Package dependency (github.com/WhisperrAI/whisperr-swift). If the
-   project uses Package.swift, add it there; if it's an .xcodeproj/.xcworkspace,
-   you cannot edit the project graph reliably from the shell \u2014 instead leave a
-   clearly commented setup note and the exact import + init code, and report it
-   as a manual follow-up.
+## SDK: Whisperr for Swift \u2014 Swift Package \`Whisperr\` (github.com/WhisperrAI/whisperr-swift)
+
+Platforms: iOS 13+, macOS 12+, tvOS 13+, watchOS 6+. The client is a Swift
+ACTOR: every call is \`await\`ed, and identify()/track() are throwing. Getting
+the concurrency and JSONValue details below right is what makes the diff
+compile first try.
+
+1) Dependency \u2014 pick by how the project is defined:
+   - Package.swift: add to the package's dependencies
+         .package(url: "https://github.com/WhisperrAI/whisperr-swift.git", from: "0.1.0")
+     and \`"Whisperr"\` to the app target's dependencies array.
+   - Tuist (Project.swift) or XcodeGen (project.yml): these manifests are plain
+     text \u2014 add the SPM package + product there following the file's existing
+     style.
+   - Raw .xcodeproj / .xcworkspace only: do NOT hand-edit project.pbxproj to
+     add a package reference (fragile, breaks the project on a bad GUID).
+     Write ALL the integration code anyway (imports, init, identify, track),
+     add a short WHISPERR_SETUP.md with the one manual step \u2014 Xcode \u2192 File \u2192
+     Add Package Dependencies\u2026 \u2192 \`https://github.com/WhisperrAI/whisperr-swift\`
+     \u2192 add "Whisperr" to the app target \u2014 and report that as the single manual
+     follow-up in your summary.
+
+2) Initialize once at launch.
+   SwiftUI:
+       import Whisperr
+
+       @main
+       struct MyApp: App {
+           init() {
+               Task { await Whisperr.initialize(apiKey: "<INGESTION_API_KEY>") }
+           }
+           // ... existing body
+       }
+   UIKit: same Task { } inside application(_:didFinishLaunchingOptions:).
+   Only pass a base URL if the manifest's differs from the SDK default:
+       await Whisperr.initialize(apiKey: "...", baseURL: URL(string: "<INGESTION_BASE_URL>")!)
+   Note baseURL takes a URL, not a String. Prefer reading the key from
+   Info.plist / an .xcconfig if the project already uses that pattern;
+   otherwise a literal is acceptable (publishable ingestion key).
+
+3) identify() right after the end-user is known \u2014 login/signup success AND
+   session restore. All calls go through the async optional singleton
+   \`await Whisperr.shared\`; in synchronous contexts wrap in Task { }:
+       Task {
+           try? await Whisperr.shared?.identify(
+               user.id,                    // stable external id \u2014 never a device id
+               traits: ["plan": .string(user.plan)],
+               email: user.email,          // shortcut \u2192 opted-in email channel
+               phone: user.phone,          // shortcut \u2192 sms channel
+               pushToken: apnsTokenHex     // if the app registers for remote notifications
+           )
+       }
+   Logout:
+       Task { await Whisperr.shared?.reset() }   // flushes, then clears the user
+   For explicit channel consent/verification use WhisperrChannel:
+       channels: [.email("a@b.com", verified: true), .sms("+1555\u2026", optedIn: false)]
+
+4) track() in action handlers / view-model methods \u2014 never in a View body:
+       Task {
+           try? await Whisperr.shared?.track(
+               "event_type_from_manifest",
+               properties: ["amount_cents": .number(Double(amountCents)),
+                            "plan": .string(plan)]
+           )
+       }
+   Awaiting only ENQUEUES (delivery batches in the background) \u2014 \`try? await\`
+   inside Task { } is the correct fire-and-forget in UI code. In an already-
+   async throwing context, plain \`try await\` is fine. event_type verbatim
+   snake_case from the manifest.
+
+CRITICAL \u2014 JSONValue typing for properties/traits:
+   Values are \`JSONValue\`, not \`Any\`. LITERALS convert automatically \u2014
+   \`["plan": "pro", "amount": 42, "active": true]\` compiles as-is \u2014 but
+   VARIABLES must be wrapped: \`.string(user.plan)\`, \`.number(Double(count))\`,
+   \`.bool(flag)\`, \`.array(...)\`, \`.object(...)\`. Mixing literals and wrapped
+   variables in one dictionary is fine. Forgetting the wrapper is the #1
+   compile error \u2014 check every non-literal value you pass.
+
+CRITICAL \u2014 no anonymous buffering in this SDK:
+   track() THROWS WhisperrClientError.missingUserID until identify() has run in
+   this process (or when you pass \`userID:\` explicitly). Session restore must
+   therefore call identify() early at startup. Do not place track() on
+   pre-auth surfaces (onboarding, login screen) unless you pass
+   \`userID: "<id>"\` \u2014 if a manifest event genuinely happens before the user
+   exists, skip it and note it in the summary.
 
-2) Initialize once at launch in the App struct (SwiftUI) or
-   application(_:didFinishLaunchingWithOptions:) (UIKit):
-     import Whisperr
-     Whisperr.initialize(apiKey: "<key>", baseUrl: "<manifest baseUrl>")
-
-3) identify() after the user is known / on session restore:
-     Whisperr.shared.identify("<external user id>", traits: [...], email: ..., phone: ...)
-   reset() on logout. Push channel = APNs device token if the app registers for
-   remote notifications.
-
-4) track() in action handlers / view-model methods, not in view body:
-     Whisperr.shared.track("event_type_from_manifest", properties: [ ... ])
-   event_type verbatim (snake_case) from the manifest.
-
-Notes:
-- Prefer reading the key from Info.plist / an xcconfig if the project uses one.
-- Do not attempt to run xcodebuild; verification is the human's step here.
+Notes / gotchas:
+- \`Whisperr.shared\` is \`async\` and optional \u2014 the call shape is always
+  \`await Whisperr.shared?.method(...)\`. Never store it in a non-async global.
+- The queue persists via UserDefaults and survives restarts; retries, backoff,
+  and auth-pause semantics are built in. No manual flush() needed.
+- Do not run xcodebuild, swift build, or tests \u2014 the human verifies in Xcode.
 `.trim();
 var swiftPlaybook = {
   target: target8,
   detect: detect8,
-  packageRef: "Whisperr (Swift Package)",
+  packageRef: "whisperr-swift (Swift Package)",
   systemPrompt: systemPrompt8
 };
 
@@ -1331,7 +1490,7 @@ async function runPass(opts) {
       cwd: repoPath,
       systemPrompt: systemPrompt9,
       // Adaptive thinking (Claude decides depth per step) + an explicit effort
-      // level. Sonnet 4.6 supports both; we set them rather than rely on SDK
+      // level. Sonnet 5 supports both; we set them rather than rely on SDK
       // defaults so the behavior is pinned regardless of SDK version.
       thinking: { type: "adaptive" },
       effort,

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "@whisperr/wizard",
-  "version": "0.1.14",
+  "version": "0.2.0",
   "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.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WhisperrAI/whisperr-wizard.git"
+  },
+  "homepage": "https://github.com/WhisperrAI/whisperr-wizard#readme",
   "license": "UNLICENSED",
   "private": false,
   "type": "module",
   "bin": {
-    "whisperr": "./dist/index.js"
+    "whisperr": "dist/index.js"
   },
   "files": [
     "dist"