@eventop/sdk 1.0.2 → 1.0.4

package/README.md

@@ -1,44 +1,315 @@
-# Sdk for event api
-```javascript 
-import { Eventop } from '@eventop/sdk';
-
-// Initialize client
-const eventop = new Eventop({
-  apiKey: process.env.EVENTOP_API_KEY!, // sk_test_... or sk_live_...
-  // environment auto-detected from key prefix
-});
+# 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.
+
+---
+
+## Install
+
+```bash
+npm install @eventop/sdk
+```
+
+---
+
+## The mental model
+
+```jsx
+// ❌ Old way — registration inside the component, breaks reusability
+function ExportButton() {
+  useeventopFeature({ id: 'export', name: 'Export' }); // hardcoded
+  return <button>Export</button>;
+}
 
-// Create checkout session
-const session = await eventop.checkout.create({
-  planId: 'premium-monthly',
-  customerEmail: 'user@example.com',
-  customerId: 'user_123',
-  successUrl: 'https://yourdomain.com/success',
-  cancelUrl: 'https://yourdomain.com/pricing',
-  metadata: {
-    userId: '123',
-    source: 'web',
-  },
+// ✅ New way — registration at the call site, component stays generic
+function Button({ children, onClick }) {
+  return <button onClick={onClick}>{children}</button>;
+}
+
+// Different features, same component, different places in the app
+<eventopTarget id="export" name="Export Design" description="Download as PNG or SVG">
+  <Button onClick={handleExport}>Export</Button>
+</eventopTarget>
+
+<eventopTarget id="download-report" name="Download Report" description="Save as PDF">
+  <Button onClick={handleDownload}>Download</Button>
+</eventopTarget>
+```
+
+---
+
+## Quick start
+
+```jsx
+// main.jsx — provider at the root, nothing else needed here
+import { EventopAIProvider } from '@eventop/sdk';
+import eventopAI from 'eventop-ai-sdk';
+
+const provider = eventopAI.providers.custom(async ({ systemPrompt, messages }) => {
+  const res = await fetch('/api/guide', {
+    method:  'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body:    JSON.stringify({ systemPrompt, messages }),
+  });
+  return res.json();
 });
 
-console.log('Checkout URL:', session.url);
+export default function App() {
+  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' }}
+    >
+      <YourApp />
+    </eventopAIProvider>
+  );
+}
+```
+
+---
+
+## Components
+
+### `<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.
+
+```jsx
+import { EventopTarget } from '@eventop/sdk';
+
+// Simple feature
+<EventopTarget id="export" name="Export Design" description="Download as PNG or SVG">
+  <Button>Export</Button>
+</EventopTarget>
+
+// 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>
+
+// Auto-advance the tour when clicked
+<EventopTarget
+  id="open-settings"
+  name="Settings"
+  description="Open the workspace settings"
+  advanceOn={{ event: 'click', delay: 200 }}
+>
+  <SettingsButton />
+</EventopTarget>
+```
+
+**Props:**
+
+| 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     |
+
+---
+
+### `<eventopStep>`
+
+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.
+
+```jsx
+import { EventopStep } from '@eventop/sdk';
+
+// These three components are totally separate — different files, different parents
+// They form a flow by sharing the same feature id and sequential indexes
+
+// 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>
 
-// Verify webhook
-app.post('/webhooks/eventop', express.raw({ type: 'application/json' }), (req, res) => {
-  const signature = req.headers['x-webhook-signature'] as string;
-  const payload = req.body.toString();
+// 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>
 
-  try {
-    const event = eventop.webhooks.constructEvent(
-      payload,
-      signature,
-      process.env.WEBHOOK_SECRET!,
-    );
+// 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>
+```
 
-    console.log('Received event:', event.event);
-    res.json({ received: true });
-  } catch (err) {
-    res.status(400).send('Webhook signature verification failed');
+**Nested sub-steps:**
+
+Pass `parentStep` to model steps that belong inside another step.
+Useful for things like "open font picker → (select font family → select weight → set size)".
+
+```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>
+```
+
+**Implicit feature id from `eventopTarget` ancestor:**
+
+If `eventopStep` is inside a `eventopTarget`, it inherits the feature id:
+
+```jsx
+<EventopTarget id="drop-shadow" name="Drop Shadow" description="...">
+  <div>
+    <EventopStep index={0} advanceOn={{ selector: '.el', event: 'click' }}>
+      <Canvas />
+    </EventopStep>
+    <EventopStep index={1} waitFor=".el.selected">
+      <EffectsButton />
+    </EventopStep>
+  </div>
+</EventopTarget>
+```
+
+**Props:**
+
+| 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            |
+
+---
+
+### `useeventopAI`
+
+Call SDK methods from inside any component. Use for `stepComplete()` and
+`stepFail()` when you have async validation the tour should respect.
+
+```jsx
+import { useeventopAI } from '@eventop/sdk';
+
+function CheckoutStep() {
+  const { stepComplete, stepFail } = useeventopAI();
+
+  async function handleContinue() {
+    const ok = await validateCard(cardNumber);
+    if (ok) stepComplete();            // tour advances to next step
+    else stepFail('Invalid card number — please try again.');
   }
-});
-```
+
+  return <button onClick={handleContinue}>Continue</button>;
+}
+```
+
+**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.
+
+```jsx
+import { useeventopTour } from '@eventop/sdk';
+
+function TourStatusBar() {
+  const { isActive, isPaused, resume, cancel } = useeventopTour();
+
+  if (!isActive && !isPaused) return null;
+
+  return (
+    <div className="tour-bar">
+      {isPaused ? (
+        <>
+          <span>⏸ Tour paused</span>
+          <button onClick={resume}>Resume</button>
+        </>
+      ) : (
+        <span>▶ Guided tour running</span>
+      )}
+      <button onClick={cancel}>End tour</button>
+    </div>
+  );
+}
+```
+
+---
+
+## Screen navigation
+
+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.
+
+For features that live behind a route change, pass `navigate`:
+
+```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>
+  );
+}
+```

package/dist/cjs/client.js

@@ -1,52 +1,54 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.EventopClient = void 0;
-const node_fetch_1 = __importDefault(require("node-fetch"));
-const errors_1 = require("./errors");
-class EventopClient {
-    constructor(config) {
-        this.apiKey = config.apiKey;
-        // Set base URL based on environment
-        if (config.apiUrl) {
-            this.baseUrl = config.apiUrl;
-        }
-        else {
-            const env = config.environment || this.detectEnvironment();
-            this.baseUrl =
-                env === 'devnet'
-                    ? 'https://eventop-server-app-production.up.railway.app'
-                    : 'https://api.eventop.xyz';
-        }
-    }
-    detectEnvironment() {
-        // Detect from API key prefix
-        if (this.apiKey.startsWith('sk_test_')) {
-            return 'devnet';
-        }
-        else if (this.apiKey.startsWith('sk_live_')) {
-            return 'mainnet';
-        }
-        throw new errors_1.AuthenticationError('Invalid API key format');
-    }
-    async request(method, path, body) {
-        const url = `${this.baseUrl}${path}`;
-        const headers = {
-            'Authorization': `Bearer ${this.apiKey}`,
-            'Content-Type': 'application/json',
-        };
-        const response = await (0, node_fetch_1.default)(url, {
-            method,
-            headers,
-            body: body ? JSON.stringify(body) : undefined,
-        });
-        const data = await response.json();
-        if (!response.ok) {
-            throw new errors_1.EventopError(data.message || 'Request failed', response.status, data.code);
-        }
-        return data;
-    }
-}
-exports.EventopClient = EventopClient;
+// import fetch from 'node-fetch';
+// import { EventopConfig, Environment } from './types';
+// import { EventopError, AuthenticationError } from './errors';
+// export class EventopClient {
+//   private apiKey: string;
+//   private baseUrl: string;
+//   constructor(config: EventopConfig) {
+//     this.apiKey = config.apiKey;
+//     // Set base URL based on environment
+//     if (config.apiUrl) {
+//       this.baseUrl = config.apiUrl;
+//     } else {
+//       const env = config.environment || this.detectEnvironment();
+//       this.baseUrl =
+//         env === 'devnet'
+//           ? 'https://eventop-server-app-production.up.railway.app'
+//           : 'https://api.eventop.xyz';
+//     }
+//   }
+//   private detectEnvironment(): Environment {
+//     // Detect from API key prefix
+//     if (this.apiKey.startsWith('sk_test_')) {
+//       return 'devnet';
+//     } else if (this.apiKey.startsWith('sk_live_')) {
+//       return 'mainnet';
+//     }
+//     throw new AuthenticationError('Invalid API key format');
+//   }
+//   async request<T>(
+//     method: string,
+//     path: string,
+//     body?: any,
+//   ): Promise<T> {
+//     const url = `${this.baseUrl}${path}`;
+//     const headers: Record<string, string> = {
+//       'Authorization': `Bearer ${this.apiKey}`,
+//       'Content-Type': 'application/json',
+//     };
+//     const response = await fetch(url, {
+//       method,
+//       headers,
+//       body: body ? JSON.stringify(body) : undefined,
+//     });
+//     const data = await response.json();
+//     if (!response.ok) {
+//       throw new EventopError(
+//         data.message || 'Request failed',
+//         response.status,
+//         data.code,
+//       );
+//     }
+//     return data as T;
+//   }
+// }

package/dist/cjs/errors.js

@@ -1,33 +1,28 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.NotFoundError = exports.InvalidRequestError = exports.AuthenticationError = exports.EventopError = void 0;
-class EventopError extends Error {
-    constructor(message, statusCode, code) {
-        super(message);
-        this.statusCode = statusCode;
-        this.code = code;
-        this.name = 'EventopError';
-    }
-}
-exports.EventopError = EventopError;
-class AuthenticationError extends EventopError {
-    constructor(message = 'Invalid API key') {
-        super(message, 401, 'authentication_error');
-        this.name = 'AuthenticationError';
-    }
-}
-exports.AuthenticationError = AuthenticationError;
-class InvalidRequestError extends EventopError {
-    constructor(message) {
-        super(message, 400, 'invalid_request');
-        this.name = 'InvalidRequestError';
-    }
-}
-exports.InvalidRequestError = InvalidRequestError;
-class NotFoundError extends EventopError {
-    constructor(message) {
-        super(message, 404, 'not_found');
-        this.name = 'NotFoundError';
-    }
-}
-exports.NotFoundError = NotFoundError;
+// export class EventopError extends Error {
+//   constructor(
+//     message: string,
+//     public statusCode?: number,
+//     public code?: string,
+//   ) {
+//     super(message);
+//     this.name = 'EventopError';
+//   }
+// }
+// export class AuthenticationError extends EventopError {
+//   constructor(message: string = 'Invalid API key') {
+//     super(message, 401, 'authentication_error');
+//     this.name = 'AuthenticationError';
+//   }
+// }
+// export class InvalidRequestError extends EventopError {
+//   constructor(message: string) {
+//     super(message, 400, 'invalid_request');
+//     this.name = 'InvalidRequestError';
+//   }
+// }
+// export class NotFoundError extends EventopError {
+//   constructor(message: string) {
+//     super(message, 404, 'not_found');
+//     this.name = 'NotFoundError';
+//   }
+// }