@eventop/sdk 1.0.2 → 1.0.3

package/dist/index.js

@@ -1,32 +1,474 @@
-"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]; } };
+import { createContext, useContext, useRef, useCallback, useEffect, Children, cloneElement, useState } from 'react';
+
+/**
+ * Root context — holds the global feature registry.
+ * Set by EventopAIProvider at the root of the app.
+ */
+const EventopRegistryContext = /*#__PURE__*/createContext(null);
+
+/**
+ * Feature scope context — set by EventopTarget.
+ * Tells any EventopStep inside the tree which feature it belongs to,
+ * so you can nest EventopStep inside a EventopTarget without repeating
+ * the feature id. Also supports explicit feature="id" on EventopStep
+ * for steps that live outside their parent EventopTarget in the tree.
+ */
+const EventopFeatureScopeContext = /*#__PURE__*/createContext(null);
+function useRegistry() {
+  const ctx = useContext(EventopRegistryContext);
+  if (!ctx) throw new Error('[EventopAI] Must be used inside <EventopAIProvider>.');
+  return ctx;
+}
+function useFeatureScope() {
+  return useContext(EventopFeatureScopeContext); // null is fine — steps can declare feature explicitly
+}
+
+/**
+ * FeatureRegistry
+ *
+ * The live map of everything currently mounted in the React tree.
+ *
+ * Features   — registered by ShepherdTarget
+ * Flow steps — registered by ShepherdStep, attached to a feature by id
+ *
+ * Both features and steps can live anywhere in the component tree.
+ * They don't need to be co-located. A ShepherdStep just needs to know
+ * which feature id it belongs to.
+ *
+ * Nested steps:
+ *   Steps can themselves have children steps (sub-steps) by passing
+ *   a parentStep prop to ShepherdStep. This lets you model flows like:
+ *
+ *   Feature: "Create styled text"
+ *     Step 0: Click Add Text
+ *     Step 1: Type your content          ← parentStep: 0
+ *       Step 1.0: Select the text        ← parentStep: 1, index: 0
+ *       Step 1.1: Open font picker       ← parentStep: 1, index: 1
+ *       Step 1.2: Choose a font          ← parentStep: 1, index: 2
+ *     Step 2: Click Done
+ *
+ *   In practice most flows are flat (index 0, 1, 2, 3...) but the
+ *   registry supports nested depth for complex interactions.
+ */
+function createFeatureRegistry() {
+  // Map<featureId, featureData>
+  const features = new Map();
+  // Map<featureId, Map<stepKey, stepData>>
+  // stepKey is either a number (flat) or "parentIndex.childIndex" (nested)
+  const flowSteps = new Map();
+  const listeners = new Set();
+  function notify() {
+    listeners.forEach(fn => fn());
+  }
+
+  // ── Feature registration ─────────────────────────────────────────────────
+
+  function registerFeature(feature) {
+    features.set(feature.id, {
+      ...feature,
+      _registeredAt: Date.now()
+    });
+    notify();
+  }
+  function unregisterFeature(id) {
+    features.delete(id);
+    flowSteps.delete(id);
+    notify();
+  }
+
+  // ── Step registration ────────────────────────────────────────────────────
+
+  /**
+   * Register a flow step.
+   *
+   * @param {string} featureId      - Parent feature id
+   * @param {number} index          - Position in the flat flow (0, 1, 2…)
+   * @param {number|null} parentStep - If set, this is a sub-step of parentStep
+   * @param {object} stepData       - { selector, waitFor, advanceOn, ... }
+   */
+  function registerStep(featureId, index, parentStep, stepData) {
+    if (!flowSteps.has(featureId)) {
+      flowSteps.set(featureId, new Map());
+    }
+    const key = parentStep != null ? `${parentStep}.${index}` : String(index);
+    flowSteps.get(featureId).set(key, {
+      ...stepData,
+      index,
+      parentStep: parentStep ?? null,
+      key
+    });
+    notify();
+  }
+  function unregisterStep(featureId, index, parentStep) {
+    const map = flowSteps.get(featureId);
+    if (!map) return;
+    const key = parentStep != null ? `${parentStep}.${index}` : String(index);
+    map.delete(key);
+    if (map.size === 0) flowSteps.delete(featureId);
+    notify();
+  }
+
+  // ── Snapshot ─────────────────────────────────────────────────────────────
+
+  /**
+   * Build the flat flow array the SDK core expects.
+   *
+   * For nested steps we inline sub-steps after their parent step,
+   * in index order. This means a flow like:
+   *
+   *   Step 0 (flat)
+   *   Step 1 (flat)
+   *     Step 1.0 (sub-step of 1)
+   *     Step 1.1 (sub-step of 1)
+   *   Step 2 (flat)
+   *
+   * becomes the SDK flow: [step0, step1, step1.0, step1.1, step2]
+   *
+   * The AI writes titles/text for the parent feature.
+   * Sub-steps inherit the parent step's text with a "(N/M)" suffix added
+   * by the SDK's expandFlowSteps() function.
+   */
+  function buildFlow(featureId) {
+    const map = flowSteps.get(featureId);
+    if (!map || map.size === 0) return null;
+    const allSteps = Array.from(map.values());
+
+    // Separate top-level and nested steps
+    const topLevel = allSteps.filter(s => s.parentStep == null).sort((a, b) => a.index - b.index);
+    const result = [];
+    topLevel.forEach(step => {
+      result.push(step);
+      // Inline any sub-steps after the parent
+      const children = allSteps.filter(s => s.parentStep === step.index).sort((a, b) => a.index - b.index);
+      result.push(...children);
+    });
+    return result.length > 0 ? result : null;
+  }
+
+  /**
+   * Returns the live feature array in the format the SDK core expects.
+   * screen.check() is automatic — mounted = available.
+   */
+  function snapshot() {
+    return Array.from(features.values()).map(feature => {
+      const flow = buildFlow(feature.id);
+      return {
+        id: feature.id,
+        name: feature.name,
+        description: feature.description,
+        selector: feature.selector,
+        advanceOn: feature.advanceOn || null,
+        waitFor: feature.waitFor || null,
+        ...(flow ? {
+          flow
+        } : {}),
+        screen: {
+          id: feature.id,
+          check: () => features.has(feature.id),
+          navigate: feature.navigate || null,
+          waitFor: feature.navigateWaitFor || feature.selector || null
+        }
+      };
+    });
+  }
+  return {
+    registerFeature,
+    unregisterFeature,
+    registerStep,
+    unregisterStep,
+    snapshot,
+    isRegistered: id => features.has(id),
+    subscribe: fn => {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    }
+  };
+}
+
+/**
+ * EventopProvider
+ *
+ * Drop this once at the root of your app.
+ * Every EventopTarget and EventopStep anywhere in the tree will
+ * register with this provider automatically.
+ *
+ * @example
+ * <EventopProvider
+ *   provider={myServerFetcher}
+ *   appName="PixelCraft"
+ *   assistantName="Pixel AI"
+ *   suggestions={['Add a shadow', 'Export design']}
+ *   theme={{ mode: 'dark', tokens: { accent: '#6366f1' } }}
+ *   position={{ corner: 'bottom-right' }}
+ * >
+ *   <App />
+ * </EventopProvider>
+ */
+function EventopProvider({
+  children,
+  provider,
+  appName,
+  assistantName,
+  suggestions,
+  theme,
+  position
+}) {
+  if (!provider) throw new Error('[Eventop] <EventopProvider> requires a provider prop.');
+  if (!appName) throw new Error('[Eventop] <EventopProvider> requires an appName prop.');
+  const registry = useRef(createFeatureRegistry()).current;
+  const sdkReady = useRef(false);
+  const syncToSDK = useCallback(() => {
+    if (!sdkReady.current || !window.Eventop) return;
+    window.Eventop._updateConfig?.({
+      features: registry.snapshot()
+    });
+  }, [registry]);
+  useEffect(() => {
+    function boot() {
+      window.Eventop.init({
+        provider,
+        config: {
+          appName,
+          assistantName,
+          suggestions,
+          theme,
+          position,
+          features: registry.snapshot(),
+          _providerName: 'custom'
+        }
+      });
+      sdkReady.current = true;
+      syncToSDK();
     }
-    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);
+    if (window.Eventop) {
+      boot();
+    } else {
+      const s = document.createElement('script');
+      s.src = 'https://unpkg.com/shepherd-ai-sdk/dist/shepherd-ai.umd.js';
+      s.onload = boot;
+      document.head.appendChild(s);
     }
+    const unsub = registry.subscribe(syncToSDK);
+    return () => {
+      unsub();
+      window.Eventop?.cancelTour();
+    };
+  }, []);
+  const ctx = {
+    registerFeature: registry.registerFeature,
+    unregisterFeature: registry.unregisterFeature,
+    registerStep: registry.registerStep,
+    unregisterStep: registry.unregisterStep,
+    isRegistered: registry.isRegistered
+  };
+  return /*#__PURE__*/React.createElement(EventopRegistryContext.Provider, {
+    value: ctx
+  }, children);
+}
+
+/**
+ * EventopTarget
+ *
+ * Wraps any component and registers it as an Eventop feature at the call site.
+ * The wrapped component does not need to know about Eventop.
+ */
+function EventopTarget({
+  children,
+  id,
+  name,
+  description,
+  navigate,
+  navigateWaitFor,
+  advanceOn,
+  waitFor,
+  ...rest
+}) {
+  const registry = useRegistry();
+  const ref = useRef(null);
+  const dataAttr = `data-evtp-${id}`;
+  const selector = `[${dataAttr}]`;
+  useEffect(() => {
+    if (!id || !name) {
+      console.warn('[Eventop] <EventopTarget> requires id and name props.');
+      return;
+    }
+    registry.registerFeature({
+      id,
+      name,
+      description,
+      selector,
+      navigate,
+      navigateWaitFor,
+      waitFor,
+      advanceOn: advanceOn ? {
+        selector,
+        ...advanceOn
+      } : null
+    });
+    return () => registry.unregisterFeature(id);
+  }, [id, name, description]);
+  const child = Children.only(children);
+  let wrapped;
+  try {
+    wrapped = /*#__PURE__*/cloneElement(child, {
+      [dataAttr]: '',
+      ref: node => {
+        ref.current = node;
+        const originalRef = child.ref;
+        if (typeof originalRef === 'function') originalRef(node);else if (originalRef && 'current' in originalRef) originalRef.current = node;
+      }
+    });
+  } catch {
+    wrapped = /*#__PURE__*/React.createElement("span", {
+      [dataAttr]: '',
+      ref: ref,
+      style: {
+        display: 'contents'
+      }
+    }, child);
+  }
+  return /*#__PURE__*/React.createElement(EventopFeatureScopeContext.Provider, {
+    value: id
+  }, wrapped);
+}
+
+/**
+ * EventopStep
+ *
+ * Registers one step in a multi-step flow. Can live anywhere in the tree.
+ * Steps self-assemble into order via the `index` prop.
+ */
+function EventopStep({
+  children,
+  feature,
+  index,
+  parentStep,
+  waitFor,
+  advanceOn
+}) {
+  const registry = useRegistry();
+  const featureScope = useFeatureScope();
+  const featureId = feature || featureScope;
+  const ref = useRef(null);
+  if (!featureId) {
+    console.warn('[Eventop] <EventopStep> needs either a feature prop or an <EventopTarget> ancestor.');
+  }
+  if (index == null) {
+    console.warn('[Eventop] <EventopStep> requires an index prop.');
+  }
+  const dataAttr = `data-evtp-step-${featureId}-${parentStep != null ? `${parentStep}-` : ''}${index}`;
+  const selector = `[${dataAttr}]`;
+  useEffect(() => {
+    if (!featureId || index == null) return;
+    registry.registerStep(featureId, index, parentStep ?? null, {
+      selector,
+      waitFor: waitFor || null,
+      advanceOn: advanceOn ? {
+        selector,
+        ...advanceOn
+      } : null
+    });
+    return () => registry.unregisterStep(featureId, index, parentStep ?? null);
+  }, [featureId, index, parentStep]);
+  const child = Children.only(children);
+  let wrapped;
+  try {
+    wrapped = /*#__PURE__*/cloneElement(child, {
+      [dataAttr]: '',
+      ref: node => {
+        ref.current = node;
+        const originalRef = child.ref;
+        if (typeof originalRef === 'function') originalRef(node);else if (originalRef && 'current' in originalRef) originalRef.current = node;
+      }
+    });
+  } catch {
+    wrapped = /*#__PURE__*/React.createElement("span", {
+      [dataAttr]: '',
+      ref: ref,
+      style: {
+        display: 'contents'
+      }
+    }, child);
+  }
+  return wrapped;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+//  useEventopAI
+//
+//  Access the SDK programmatic API from inside any component.
+//  Use for stepComplete(), stepFail(), open(), close() etc.
+//
+//  @example
+//  function CheckoutForm() {
+//    const { stepComplete, stepFail } = useEventopAI();
+//
+//    async function handleNext() {
+//      const ok = await validateEmail(email);
+//      if (ok) stepComplete();
+//      else stepFail('Please enter a valid email address.');
+//    }
+//  }
+// ═══════════════════════════════════════════════════════════════════════════
+
+function useEventop() {
+  const sdk = () => window.Eventop;
+  return {
+    open: () => sdk()?.open(),
+    close: () => sdk()?.close(),
+    cancelTour: () => sdk()?.cancelTour(),
+    resumeTour: () => sdk()?.resumeTour(),
+    isActive: () => sdk()?.isActive() ?? false,
+    isPaused: () => sdk()?.isPaused() ?? false,
+    stepComplete: () => sdk()?.stepComplete(),
+    stepFail: msg => sdk()?.stepFail(msg),
+    runTour: steps => sdk()?.runTour(steps)
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+//  useEventopTour
+//
+//  Reactively tracks tour state so you can render your own UI.
+//  Polls at 300ms — lightweight enough for a status indicator.
+//
+//  @example
+//  function TourBar() {
+//    const { isActive, isPaused, resume, cancel } = useEventopTour();
+//    if (!isActive && !isPaused) return null;
+//    return (
+//      <div>
+//        {isPaused && <button onClick={resume}>Resume tour</button>}
+//        <button onClick={cancel}>End</button>
+//      </div>
+//    );
+//  }
+// ═══════════════════════════════════════════════════════════════════════════
+
+function useEventopTour() {
+  const [state, setState] = useState({
+    isActive: false,
+    isPaused: false
+  });
+  useEffect(() => {
+    const id = setInterval(() => {
+      const sdk = window.Eventop;
+      if (!sdk) return;
+      const next = {
+        isActive: sdk.isActive(),
+        isPaused: sdk.isPaused()
+      };
+      setState(prev => prev.isActive !== next.isActive || prev.isPaused !== next.isPaused ? next : prev);
+    }, 300);
+    return () => clearInterval(id);
+  }, []);
+  return {
+    ...state,
+    resume: useCallback(() => window.Eventop?.resumeTour(), []),
+    cancel: useCallback(() => window.Eventop?.cancelTour(), []),
+    open: useCallback(() => window.Eventop?.open(), []),
+    close: useCallback(() => window.Eventop?.close(), [])
+  };
 }
-exports.Eventop = Eventop;
-__exportStar(require("./types"), exports);
-__exportStar(require("./errors"), exports);
+
+export { EventopProvider, EventopStep, EventopTarget, useEventop, useEventopTour };

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@eventop/sdk",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Official SDK for Eventop on-chain subscriptions",
-  "keywords": ["solana", "subscriptions", "crypto", "payments"],
+  "keywords": [
+    "solana",
+    "subscriptions",
+    "crypto",
+    "payments"
+  ],
   "homepage": "https://github.com/eventop-s/sdk#readme",
   "bugs": {
     "url": "https://github.com/eventop-s/sdk/issues"
@@ -12,15 +17,14 @@
     "url": "git+https://github.com/eventop-s/sdk.git"
   },
   "license": "MIT",
-  "author": "Eventop",
-  "main": "./dist/cjs/index.js",
-  "module": "./dist/esm/index.js",
-  "types": "./dist/types/index.d.ts",
+  "author": "Emengkeng Juslen",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
   "exports": {
     ".": {
-      "require": "./dist/cjs/index.js",
-      "import": "./dist/esm/index.js",
-      "types": "./dist/types/index.d.ts"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
   },
   "files": [
@@ -28,18 +32,21 @@
     "README.md"
   ],
   "scripts": {
-    "build": "npm run build:cjs && npm run build:esm && npm run build:types",
-    "build:cjs": "tsc --project tsconfig.cjs.json",
-    "build:esm": "tsc --project tsconfig.esm.json",
-    "build:types": "tsc --project tsconfig.types.json",
-    "prepublishOnly": "npm run build"
+    "build": "rollup -c",
+    "prepublishOnly": "yarn run build"
   },
   "dependencies": {
     "node-fetch": "^2.6.7"
   },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
   "devDependencies": {
-    "@types/node": "^18.0.0",
-    "@types/node-fetch": "^2.6.2",
-    "typescript": "^5.0.0"
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-babel": "^6.0.4",
+    "@babel/core": "^7.23.9",
+    "@babel/preset-react": "^7.23.3",
+    "rollup": "^4.9.6"
   }
 }