@eventop/sdk 1.0.4 → 1.0.6

package/README.md

@@ -1,8 +1,6 @@
-# eventop/sdk
+# @eventop/sdk
 
-React integration for eventopAI. Features register at the **call site**, not
-inside component definitions — so any generic component works with any feature,
-and you never touch the component itself.
+AI-powered guided tours for any React or Next.js app. Drop-in, themeable, works with any component library.
 
 ---
 
@@ -10,55 +8,75 @@ and you never touch the component itself.
 
 ```bash
 npm install @eventop/sdk
+# or
+yarn add @eventop/sdk
+# or
+pnpm add @eventop/sdk
 ```
 
 ---
 
-## The mental model
+## How it works
 
-```jsx
-// ❌ Old way — registration inside the component, breaks reusability
-function ExportButton() {
-  useeventopFeature({ id: 'export', name: 'Export' }); // hardcoded
-  return <button>Export</button>;
-}
+You wrap any element with `<EventopTarget>` at the call site. The SDK registers it as a feature the AI can guide users to. When a user types what they need in the chat bubble, the AI picks the right features and walks them through step by step.
 
-// ✅ New way — registration at the call site, component stays generic
-function Button({ children, onClick }) {
-  return <button onClick={onClick}>{children}</button>;
-}
+The wrapped component stays completely generic — `<Button>`, `<div>`, anything from shadcn, MUI, Radix, whatever. You never modify the component itself.
 
-// Different features, same component, different places in the app
-<eventopTarget id="export" name="Export Design" description="Download as PNG or SVG">
+```jsx
+// Same Button, two different features, two different places in the app
+<EventopTarget id="export" name="Export Design" description="Download as PNG or SVG">
   <Button onClick={handleExport}>Export</Button>
-</eventopTarget>
+</EventopTarget>
 
-<eventopTarget id="download-report" name="Download Report" description="Save as PDF">
-  <Button onClick={handleDownload}>Download</Button>
-</eventopTarget>
+<EventopTarget id="share" name="Share Design" description="Share a link with teammates">
+  <Button onClick={handleShare}>Share</Button>
+</EventopTarget>
 ```
 
 ---
 
-## Quick start
+## React app
+
+### 1. Set up the server endpoint
+
+Never put API keys in the browser. Create a server route that proxies the AI call.
+
+```js
+// server.js (Express)
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+
+app.post('/api/guide', async (req, res) => {
+  const { systemPrompt, messages } = req.body;
+  const response = await client.messages.create({
+    model:      'claude-sonnet-4-20250514',
+    max_tokens: 1000,
+    system:     systemPrompt,
+    messages,
+  });
+  res.json(JSON.parse(response.content[0].text));
+});
+```
+
+### 2. Add the provider at the root
 
 ```jsx
-// main.jsx — provider at the root, nothing else needed here
-import { EventopAIProvider } from '@eventop/sdk';
-import eventopAI from 'eventop-ai-sdk';
+// main.jsx
+import { EventopAIProvider } from '@eventop/sdk/react';
 
-const provider = eventopAI.providers.custom(async ({ systemPrompt, messages }) => {
+const provider = async ({ systemPrompt, messages }) => {
   const res = await fetch('/api/guide', {
     method:  'POST',
     headers: { 'Content-Type': 'application/json' },
     body:    JSON.stringify({ systemPrompt, messages }),
   });
   return res.json();
-});
+};
 
 export default function App() {
   return (
-    <eventopAIProvider
+    <EventopAIProvider
       provider={provider}
       appName="My App"
       assistantName="AI Guide"
@@ -67,207 +85,289 @@ export default function App() {
       position={{ corner: 'bottom-right' }}
     >
       <YourApp />
-    </eventopAIProvider>
+    </EventopAIProvider>
   );
 }
 ```
 
----
+### 3. Wrap features anywhere in the tree
 
-## Components
+```jsx
+// ExportPanel.jsx
+import { EventopTarget } from '@eventop/sdk/react';
 
-### `<eventopTarget>`
+export function ExportPanel() {
+  return (
+    <EventopTarget
+      id="export"
+      name="Export Design"
+      description="Download the design as PNG, SVG or PDF"
+    >
+      <div id="export-panel">
+        <button>PNG</button>
+        <button>SVG</button>
+        <button>PDF</button>
+      </div>
+    </EventopTarget>
+  );
+}
+```
 
-Wraps any component and registers it as a feature. Works with your own components,
-shadcn, MUI, Radix — anything. The wrapped component does not need to accept refs
-or know about eventopAI.
+That's it. The chat bubble appears automatically. Users type what they need and get a guided tour.
 
-```jsx
-import { EventopTarget } from '@eventop/sdk';
+---
 
-// Simple feature
-<EventopTarget id="export" name="Export Design" description="Download as PNG or SVG">
-  <Button>Export</Button>
-</EventopTarget>
+## Next.js app
 
-// With navigation — for features behind a route change
-<EventopTarget
-  id="effects"
-  name="Effects Panel"
-  description="Apply shadows, blur and glow"
-  navigate={() => router.push('/canvas')}
-  navigateWaitFor="#canvas-stage"
->
-  <EffectsPanel />
-</EventopTarget>
+### 1. Create the API route
 
-// Auto-advance the tour when clicked
-<EventopTarget
-  id="open-settings"
-  name="Settings"
-  description="Open the workspace settings"
-  advanceOn={{ event: 'click', delay: 200 }}
->
-  <SettingsButton />
-</EventopTarget>
+```js
+// app/api/guide/route.js  (App Router)
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+
+export async function POST(request) {
+  const { systemPrompt, messages } = await request.json();
+  const response = await client.messages.create({
+    model:      'claude-sonnet-4-20250514',
+    max_tokens: 1000,
+    system:     systemPrompt,
+    messages,
+  });
+  return Response.json(JSON.parse(response.content[0].text));
+}
 ```
 
-**Props:**
+```js
+// pages/api/guide.js  (Pages Router)
+import Anthropic from '@anthropic-ai/sdk';
 
-| Prop              | Type     | Required | Description                                           |
-|-------------------|----------|----------|-------------------------------------------------------|
-| `id`              | string   | ✓        | Unique feature id                                     |
-| `name`            | string   | ✓        | Human-readable name (AI reads this)                   |
-| `description`     | string   |          | What it does (AI uses this to match user intent)      |
-| `navigate`        | function |          | Navigate here if component is not currently mounted   |
-| `navigateWaitFor` | string   |          | CSS selector to wait for after navigating             |
-| `advanceOn`       | object   |          | `{ event, delay?, selector? }` — auto-advance the tour|
-| `waitFor`         | string   |          | CSS selector to wait for before showing this step     |
+const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
 
----
+export default async function handler(req, res) {
+  const { systemPrompt, messages } = req.body;
+  const response = await client.messages.create({
+    model:      'claude-sonnet-4-20250514',
+    max_tokens: 1000,
+    system:     systemPrompt,
+    messages,
+  });
+  res.json(JSON.parse(response.content[0].text));
+}
+```
 
-### `<eventopStep>`
+### 2. Add the provider in a client component
 
-Registers one step in a multi-step flow. Can live **anywhere** in the component
-tree — it does not need to be inside a `eventopTarget`. Steps self-assemble
-into the correct sequence via the `index` prop.
+The SDK touches the DOM so the provider must be a client component.
 
 ```jsx
-import { EventopStep } from '@eventop/sdk';
+// components/EventopProvider.jsx
+'use client';
 
-// These three components are totally separate — different files, different parents
-// They form a flow by sharing the same feature id and sequential indexes
+import { EventopAIProvider } from '@eventop/sdk/react';
 
-// In CanvasStage.jsx
-<EventopStep
-  feature="drop-shadow"
-  index={0}
-  advanceOn={{ selector: '.canvas-el', event: 'click', delay: 300 }}
->
-  <div className="canvas-stage">...</div>
-</EventopStep>
-
-// In Toolbar.jsx
-<EventopStep
-  feature="drop-shadow"
-  index={1}
-  waitFor=".canvas-el.selected"
-  advanceOn={{ event: 'click', delay: 200 }}
->
-  <button id="btn-effects">Effects</button>
-</EventopStep>
-
-// In EffectsPanel.jsx
-<EventopStep
-  feature="drop-shadow"
-  index={2}
-  waitFor="#effects-panel.open"
-  advanceOn={{ event: 'click', delay: 300 }}
->
-  <button id="shadow-toggle">Shadow</button>
-</EventopStep>
+const provider = async ({ systemPrompt, messages }) => {
+  const res = await fetch('/api/guide', {
+    method:  'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body:    JSON.stringify({ systemPrompt, messages }),
+  });
+  return res.json();
+};
+
+export function EventopProvider({ children }) {
+  return (
+    <EventopAIProvider
+      provider={provider}
+      appName="My App"
+      assistantName="AI Guide"
+      suggestions={['How do I export?', 'Invite a teammate']}
+      theme={{ mode: 'auto', tokens: { accent: '#6366f1' } }}
+      position={{ corner: 'bottom-right' }}
+    >
+      {children}
+    </EventopAIProvider>
+  );
+}
+```
+
+```jsx
+// app/layout.jsx
+import { EventopProvider } from '@/components/EventopProvider';
 
-// Only renders when shadow is on — SDK waits for it via waitFor
-<EventopStep feature="drop-shadow" index={3} waitFor="#shadow-controls.visible">
-  <div id="shadow-controls">...</div>
-</EventopStep>
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <EventopProvider>
+          {children}
+        </EventopProvider>
+      </body>
+    </html>
+  );
+}
 ```
 
-**Nested sub-steps:**
+### 3. Wrap features in client components
 
-Pass `parentStep` to model steps that belong inside another step.
-Useful for things like "open font picker → (select font family → select weight → set size)".
+Any component that uses `EventopTarget`, `EventopStep`, or the hooks needs `'use client'`.
 
 ```jsx
-// Step 1: open font picker
-<EventopStep feature="style-text" index={1}>
-  <FontPickerButton />
-</EventopStep>
-
-// Sub-steps of step 1 — run after step 1, in order
-<EventopStep feature="style-text" index={0} parentStep={1} waitFor=".font-picker.open">
-  <FontFamilyList />
-</EventopStep>
-<EventopStep feature="style-text" index={1} parentStep={1} waitFor=".family-selected">
-  <FontWeightList />
-</EventopStep>
+// components/Toolbar.jsx
+'use client';
+
+import { EventopTarget } from '@eventop/sdk/react';
+
+export function Toolbar() {
+  return (
+    <div className="toolbar">
+      <EventopTarget
+        id="export"
+        name="Export Design"
+        description="Download as PNG, SVG or PDF"
+      >
+        <button>Export</button>
+      </EventopTarget>
+
+      <EventopTarget
+        id="share"
+        name="Share Design"
+        description="Share a link to this design"
+      >
+        <button>Share</button>
+      </EventopTarget>
+    </div>
+  );
+}
 ```
 
-**Implicit feature id from `eventopTarget` ancestor:**
+---
+
+## Multi-step flows
 
-If `eventopStep` is inside a `eventopTarget`, it inherits the feature id:
+For features that require multiple actions in sequence (open a panel, toggle a switch, adjust sliders), use `<EventopStep>`. Steps can live in completely different components — they self-assemble by index.
 
 ```jsx
-<EventopTarget id="drop-shadow" name="Drop Shadow" description="...">
-  <div>
-    <EventopStep index={0} advanceOn={{ selector: '.el', event: 'click' }}>
-      <Canvas />
+// CanvasStage.jsx — step 0: click an element
+'use client';
+import { EventopStep } from '@eventop/sdk/react';
+
+export function CanvasStage() {
+  return (
+    <EventopStep
+      feature="drop-shadow"
+      index={0}
+      advanceOn={{ selector: '.canvas-el', event: 'click', delay: 300 }}
+    >
+      <div className="canvas-stage">...</div>
+    </EventopStep>
+  );
+}
+
+// Toolbar.jsx — step 1: click Effects (different component entirely)
+export function EffectsButton() {
+  return (
+    <EventopStep
+      feature="drop-shadow"
+      index={1}
+      waitFor=".canvas-el.selected"
+      advanceOn={{ event: 'click', delay: 200 }}
+    >
+      <button id="btn-effects">✨ Effects</button>
     </EventopStep>
-    <EventopStep index={1} waitFor=".el.selected">
-      <EffectsButton />
+  );
+}
+
+// EffectsPanel.jsx — step 2: toggle shadow on
+export function ShadowToggle({ onToggle }) {
+  return (
+    <EventopStep
+      feature="drop-shadow"
+      index={2}
+      waitFor="#effects-panel.open"
+      advanceOn={{ event: 'click', delay: 300 }}
+    >
+      <button id="shadow-toggle" onClick={onToggle}>Shadow</button>
     </EventopStep>
-  </div>
-</EventopTarget>
+  );
+}
+
+// Step 3: sliders — only rendered when shadow is on
+// SDK waits for them via waitFor before showing this step
+export function ShadowSliders() {
+  return (
+    <EventopStep feature="drop-shadow" index={3} waitFor="#shadow-controls.visible">
+      <div id="shadow-controls" className="visible">...</div>
+    </EventopStep>
+  );
+}
 ```
 
-**Props:**
+The parent feature still needs a `<EventopTarget>` somewhere:
 
-| Prop         | Type   | Required | Description                                              |
-|--------------|--------|----------|----------------------------------------------------------|
-| `feature`    | string | *        | Feature id this step belongs to (*not needed if inside `eventopTarget`) |
-| `index`      | number | ✓        | Position in the flow (0-based)                           |
-| `parentStep` | number |          | Parent step index — makes this a sub-step                |
-| `waitFor`    | string |          | CSS selector to wait for before showing                  |
-| `advanceOn`  | object |          | `{ event, delay?, selector? }` — auto-advance            |
+```jsx
+// In whichever component owns the canvas screen
+<EventopTarget
+  id="drop-shadow"
+  name="Drop Shadow Effect"
+  description="Apply a customisable drop shadow to a selected element"
+  navigate={() => router.push('/canvas')}
+>
+  <div className="canvas-screen">
+    <CanvasStage />
+    <EffectsButton />
+    <ShadowToggle />
+    {shadowOn && <ShadowSliders />}
+  </div>
+</EventopTarget>
+```
 
 ---
 
-### `useeventopAI`
+## Async validation
 
-Call SDK methods from inside any component. Use for `stepComplete()` and
-`stepFail()` when you have async validation the tour should respect.
+Use `useEventopAI` when a tour step depends on the user completing a form action correctly before advancing.
 
 ```jsx
-import { useeventopAI } from '@eventop/sdk';
+'use client';
+import { useEventopAI } from '@eventop/sdk/react';
 
-function CheckoutStep() {
-  const { stepComplete, stepFail } = useeventopAI();
+export function CheckoutForm() {
+  const { stepComplete, stepFail } = useEventopAI();
+  const [email, setEmail] = useState('');
 
   async function handleContinue() {
-    const ok = await validateCard(cardNumber);
-    if (ok) stepComplete();            // tour advances to next step
-    else stepFail('Invalid card number — please try again.');
+    const ok = await validateEmail(email);
+    if (ok) stepComplete();
+    else stepFail('Please enter a valid email address.');
   }
 
-  return <button onClick={handleContinue}>Continue</button>;
+  return (
+    <EventopTarget id="email-field" name="Email Address" description="Enter your email">
+      <div>
+        <input
+          type="email"
+          value={email}
+          onChange={e => setEmail(e.target.value)}
+        />
+        <button onClick={handleContinue}>Continue</button>
+      </div>
+    </EventopTarget>
+  );
 }
 ```
 
-**Returns:**
-
-| Method           | Description                                         |
-|------------------|-----------------------------------------------------|
-| `stepComplete()` | Advance the active tour step                        |
-| `stepFail(msg)`  | Block advancement and show error in the tooltip     |
-| `open()`         | Open the chat panel                                 |
-| `close()`        | Close the chat panel                                |
-| `cancelTour()`   | Hard cancel — no resume state saved                 |
-| `resumeTour()`   | Resume a paused tour from where it left off         |
-| `isActive()`     | Returns true if a tour is running                   |
-| `isPaused()`     | Returns true if a tour is paused                    |
-| `runTour(steps)` | Run a manual tour bypassing the AI                  |
-
 ---
 
-### `useeventopTour`
-
-React to tour state in your own UI. Reactive — updates every 300ms.
+## Tour status in your own UI
 
 ```jsx
-import { useeventopTour } from '@eventop/sdk';
+'use client';
+import { useEventopTour } from '@eventop/sdk/react';
 
-function TourStatusBar() {
-  const { isActive, isPaused, resume, cancel } = useeventopTour();
+export function TourStatusBar() {
+  const { isActive, isPaused, resume, cancel } = useEventopTour();
 
   if (!isActive && !isPaused) return null;
 
@@ -289,27 +389,89 @@ function TourStatusBar() {
 
 ---
 
-## Screen navigation
+## API reference
+
+### `<EventopAIProvider>`
+
+| Prop            | Type       | Required | Default        | Description                   |
+|-----------------|------------|----------|----------------|-------------------------------|
+| `provider`      | function   | ✓        | —              | Async function that calls your server route |
+| `appName`       | string     | ✓        | —              | Shown in the chat header      |
+| `assistantName` | string     |          | `'AI Guide'`   | Name shown in the chat header |
+| `suggestions`   | string[]   |          | `[]`           | Clickable chips on first open |
+| `theme`         | object     |          | dark, default  | `{ mode, preset, tokens }`    |
+| `position`      | object     |          | bottom-right   | `{ corner, offsetX, offsetY }`|
+
+### `<EventopTarget>`
+
+| Prop              | Type     | Required | Description                                             |
+|-------------------|----------|----------|---------------------------------------------------------|
+| `id`              | string   | ✓        | Unique feature id                                       |
+| `name`            | string   | ✓        | Human-readable name the AI reads                        |
+| `description`     | string   |          | What it does — AI uses this to match user intent        |
+| `navigate`        | function |          | Navigate here if component is not currently mounted     |
+| `navigateWaitFor` | string   |          | CSS selector to wait for after navigating               |
+| `advanceOn`       | object   |          | `{ event, delay?, selector? }` — auto-advance the tour  |
+| `waitFor`         | string   |          | CSS selector to wait for before showing this step       |
+
+### `<EventopStep>`
+
+| Prop        | Type   | Required | Description                                                    |
+|-------------|--------|----------|----------------------------------------------------------------|
+| `feature`   | string | *        | Feature id (*not needed if inside `<EventopTarget>`)           |
+| `index`     | number | ✓        | Position in the flow, 0-based                                  |
+| `parentStep`| number |          | Makes this a sub-step of another step                          |
+| `waitFor`   | string |          | CSS selector to wait for before showing                        |
+| `advanceOn` | object |          | `{ event, delay?, selector? }` — auto-advance                  |
+
+### `useEventopAI`
+
+| Method             | Description                                          |
+|--------------------|------------------------------------------------------|
+| `stepComplete()`   | Advance the active tour step                         |
+| `stepFail(msg)`    | Block advancement and show error in the tooltip      |
+| `open()`           | Open the chat panel                                  |
+| `close()`          | Close the chat panel                                 |
+| `cancelTour()`     | Hard cancel — no resume state saved                  |
+| `resumeTour()`     | Resume a paused tour from where it left off          |
+| `isActive()`       | Returns true if a tour is currently running          |
+| `isPaused()`       | Returns true if a tour is paused                     |
+| `runTour(steps)`   | Run a tour manually, bypassing the AI                |
+
+### `useEventopTour`
+
+| Property / Method | Type     | Description                              |
+|-------------------|----------|------------------------------------------|
+| `isActive`        | boolean  | True if a tour is running                |
+| `isPaused`        | boolean  | True if a tour is paused                 |
+| `resume()`        | function | Resume a paused tour                     |
+| `cancel()`        | function | Hard cancel                              |
+| `open()`          | function | Open the chat panel                      |
+| `close()`         | function | Close the chat panel                     |
 
-Because `eventopTarget` only registers a feature while its component is mounted,
-screen detection is automatic. If the Effects Panel is not rendered, the `effects`
-feature simply does not exist in the registry — no `screen.check()` needed.
+---
+
+## Theme tokens
 
-For features that live behind a route change, pass `navigate`:
+| Token             | Default (dark)   | Default (light) |
+|-------------------|------------------|-----------------|
+| `accent`          | `#e94560`        | `#e94560`       |
+| `accentSecondary` | `#a855f7`        | `#7c3aed`       |
+| `bg`              | `#0f0f1a`        | `#ffffff`       |
+| `surface`         | `#1a1a2e`        | `#f8f8fc`       |
+| `border`          | `#2a2a4a`        | `#e4e4f0`       |
+| `text`            | `#e0e0f0`        | `#1a1a2e`       |
+| `radius`          | `16px`           | `16px`          |
+
+Override any token:
 
 ```jsx
-// Only rendered on /canvas route
-function EffectsPanel() {
-  return (
-    <EventopTarget
-      id="effects"
-      name="Effects Panel"
-      description="Apply shadows and blur"
-      navigate={() => router.push('/canvas')}
-      navigateWaitFor="#canvas-root"
-    >
-      <div id="effects-panel">...</div>
-    </EventopTarget>
-  );
-}
-```
+theme={{
+  mode: 'dark',
+  tokens: {
+    accent:     '#6366f1',
+    radius:     '12px',
+    fontFamily: "'Inter', sans-serif",
+  }
+}}
+```