nudge-sdk

Embeddable in-app walkthroughs. Drop it into any web app — React, Vue, Svelte, or vanilla — and an AI-guided cursor walks users through flows you've recorded.

• Zero host-app pollution — UI lives in a closed shadow DOM, so it can't leak styles in or out
• Shadow cursor + instruction bar — points at real DOM, reacts to real events
• Authoring built in — click-record flows from inside the app with AI-assisted instruction writing
• Semantic goal matching — users type "export csv", SDK finds the right flow via pgvector + LLM fallback
• Privacy-first — password and credit-card fields are never recorded, even by accident
• ~17 KB gzipped

Install

npm install nudge-sdk
# or
pnpm add nudge-sdk

You'll see the welcome banner once on install. To reprint it any time:

npx nudge          # banner + quick start
npx nudge docs     # open docs
npx nudge --help   # all commands

Set NUDGE_NO_BANNER=1 to silence the install banner.

Use

import { NudgeSDK } from "nudge-sdk";

const nudge = NudgeSDK.init({
  apiKey: process.env.NEXT_PUBLIC_NUDGE_API_KEY!,
  apiBase: "https://your-nudge-backend.example.com/api",
  defaultProjectKey: "onboarding",          // optional: click-trigger starts this
  endUserIdHash: hashedUserId,               // optional: stable hash for analytics
  theme: {
    trigger: { position: "bottom-right", bg: "#7c3aed", fg: "#fff" },
  },
  onEvent: (event) => console.log(event),
}).mount();

That's it. A floating "Ask your buddy" trigger appears in the corner.

Programmatic start

await nudge.start({ projectKey: "your-flow-key" });

Opening the goal input

nudge.openInput(); // shows the free-form "what would you like to do?" modal

Authoring (recording new flows)

const nudge = NudgeSDK.init({
  apiKey, apiBase,
  authoring: { enabled: true, aiAssist: true },
}).mount();

// Later, gated behind `user.role === 'admin'`:
nudge.startRecording();  // shows a red record FAB + captures clicks
nudge.stopRecording();   // opens the review modal — edit instructions, publish

The API key must carry the authoring capability (granted in the dashboard).

Privacy controls

NudgeSDK.init({
  apiKey, apiBase,
  privacy: {
    redactSelectors: [".billing-history tr", "[data-internal]"],
    // built-in defaults already cover input[type=password], cc-* autocompletes,
    // and [data-nudge-skip]
  },
});

See docs/privacy.md for the full data-flow writeup.

Config reference

| Option | Type | Notes | | --- | --- | --- | | apiKey | string | Required. The pk_live_... key from your dashboard. | | apiBase | string | Required. Your Nudge backend base URL. | | defaultProjectKey | string? | Trigger-button click starts this flow. Omit to always open the goal modal. | | endUserIdHash | string? | Stable opaque id (hash your user id; never raw PII). | | theme | NudgeTheme? | Runtime CSS custom properties. See NudgeTheme in types. | | trigger.mode | "button" \| "programmatic" | Default button. | | authoring.enabled | boolean | Mounts the record FAB. Default off. | | authoring.aiAssist | boolean | Default true — AI writes instruction copy on publish. | | privacy.redactSelectors | string[]? | Extra selectors the recorder must never capture. | | privacy.replaceDefaults | boolean? | Disable the built-in redact list. Not recommended. | | onEvent | (e: NudgeEvent) => void | Observe session + authoring + matching lifecycle. |

Events

Every meaningful transition emits an event:

• session_started, step_started, step_completed, wrong_click, session_completed
• goal_matched (carries source: 'exact' | 'fuzzy' | 'semantic' | 'llm'), goal_unmatched
• authoring_started, step_recorded, authoring_stopped, flow_published
• click_redacted — the recorder refused to capture a click (password field, etc.)
• error — unrecoverable SDK error

License

MIT