@eventop/sdk 1.0.1 → 1.0.3

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

@@ -0,0 +1,54 @@
+// 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

@@ -0,0 +1,28 @@
+// 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';
+//   }
+// }

package/dist/cjs/index.js

@@ -0,0 +1,32 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Eventop = void 0;
+const client_1 = require("./client");
+const checkout_1 = require("./resources/checkout");
+const subscriptions_1 = require("./resources/subscriptions");
+const webhooks_1 = require("./resources/webhooks");
+class Eventop {
+    constructor(config) {
+        const client = new client_1.EventopClient(config);
+        this.checkout = new checkout_1.Checkout(client);
+        this.subscriptions = new subscriptions_1.Subscriptions(client);
+        this.webhooks = new webhooks_1.Webhooks(client);
+    }
+}
+exports.Eventop = Eventop;
+__exportStar(require("./types"), exports);
+__exportStar(require("./errors"), exports);

package/dist/cjs/resources/checkout.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Checkout = void 0;
+class Checkout {
+    constructor(client) {
+        this.client = client;
+    }
+    async create(params) {
+        return this.client.request('POST', '/checkout/create', params);
+    }
+    async get(sessionId) {
+        return this.client.request('GET', `/checkout/${sessionId}`);
+    }
+    async cancel(sessionId) {
+        return this.client.request('POST', `/checkout/${sessionId}/cancel`);
+    }
+}
+exports.Checkout = Checkout;

package/dist/cjs/resources/customers.js

@@ -0,0 +1 @@
+"use strict";

package/dist/cjs/resources/subscriptions.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Subscriptions = void 0;
+class Subscriptions {
+    constructor(client) {
+        this.client = client;
+    }
+    async list() {
+        return this.client.request('GET', '/subscriptions');
+    }
+    async get(subscriptionId) {
+        return this.client.request('GET', `/subscriptions/${subscriptionId}`);
+    }
+    async cancel(subscriptionId) {
+        return this.client.request('POST', `/subscriptions/${subscriptionId}/cancel`);
+    }
+}
+exports.Subscriptions = Subscriptions;

package/dist/cjs/resources/webhooks.js

@@ -0,0 +1,60 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Webhooks = void 0;
+const crypto = __importStar(require("crypto"));
+class Webhooks {
+    constructor(client) {
+        this.client = client;
+    }
+    verifySignature(payload, signature, secret) {
+        const payloadString = typeof payload === 'string' ? payload : JSON.stringify(payload);
+        const expectedSignature = crypto
+            .createHmac('sha256', secret)
+            .update(payloadString)
+            .digest('hex');
+        return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
+    }
+    constructEvent(payload, signature, secret) {
+        const payloadString = Buffer.isBuffer(payload)
+            ? payload.toString('utf8')
+            : payload;
+        if (!this.verifySignature(payloadString, signature, secret)) {
+            throw new Error('Invalid webhook signature');
+        }
+        return JSON.parse(payloadString);
+    }
+}
+exports.Webhooks = Webhooks;

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/esm/client.js

@@ -0,0 +1,45 @@
+import fetch from 'node-fetch';
+import { EventopError, AuthenticationError } from './errors';
+export 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 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 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;
+    }
+}

package/dist/esm/errors.js

@@ -0,0 +1,26 @@
+export class EventopError extends Error {
+    constructor(message, statusCode, code) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+        this.name = 'EventopError';
+    }
+}
+export class AuthenticationError extends EventopError {
+    constructor(message = 'Invalid API key') {
+        super(message, 401, 'authentication_error');
+        this.name = 'AuthenticationError';
+    }
+}
+export class InvalidRequestError extends EventopError {
+    constructor(message) {
+        super(message, 400, 'invalid_request');
+        this.name = 'InvalidRequestError';
+    }
+}
+export class NotFoundError extends EventopError {
+    constructor(message) {
+        super(message, 404, 'not_found');
+        this.name = 'NotFoundError';
+    }
+}

package/dist/esm/index.js

@@ -0,0 +1,14 @@
+import { EventopClient } from './client';
+import { Checkout } from './resources/checkout';
+import { Subscriptions } from './resources/subscriptions';
+import { Webhooks } from './resources/webhooks';
+export class Eventop {
+    constructor(config) {
+        const client = new EventopClient(config);
+        this.checkout = new Checkout(client);
+        this.subscriptions = new Subscriptions(client);
+        this.webhooks = new Webhooks(client);
+    }
+}
+export * from './types';
+export * from './errors';

package/dist/esm/resources/checkout.js

@@ -0,0 +1,14 @@
+export class Checkout {
+    constructor(client) {
+        this.client = client;
+    }
+    async create(params) {
+        return this.client.request('POST', '/checkout/create', params);
+    }
+    async get(sessionId) {
+        return this.client.request('GET', `/checkout/${sessionId}`);
+    }
+    async cancel(sessionId) {
+        return this.client.request('POST', `/checkout/${sessionId}/cancel`);
+    }
+}

package/dist/esm/resources/customers.js

@@ -0,0 +1 @@
+"use strict";