{"_id":"@ai-dap/sdk","name":"@ai-dap/sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@ai-dap/sdk","version":"0.1.0","description":"AI-DAP SDK - Lightweight guide playback engine with zero runtime dependencies","license":"MIT","author":{"name":"AI-DAP Team"},"repository":{"type":"git","url":"git+https://github.com/bill1118qq/ai-dap.git","directory":"packages/sdk"},"keywords":["dap","digital-adoption","product-tour","onboarding","guide"],"main":"./dist/cjs/index.js","module":"./dist/esm/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"tsup","dev":"rollup -c rollup.config.mjs -w","clean":"rm -rf dist","test":"vitest run","test:watch":"vitest","lint":"tsc --noEmit","typecheck":"tsc --noEmit"},"devDependencies":{"@rollup/plugin-typescript":"^12.1.0","jsdom":"^25.0.0","rollup":"^4.28.0","tsup":"^8.5.1","typescript":"^5.7.0","vitest":"^2.1.0"},"sideEffects":false,"gitHead":"a5fc40283f274e0d38a854929199aa289df5ba0f","_id":"@ai-dap/sdk@0.1.0","bugs":{"url":"https://github.com/bill1118qq/ai-dap/issues"},"homepage":"https://github.com/bill1118qq/ai-dap#readme","_nodeVersion":"25.8.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-A+0iKeN9qMiMHg64eOC8bPIQgC8WZeNLNaFaCqJ7WFuOrLFSexlozI5cNOXMzSx0dLoa26p3ZmeHIckb+Pouhg==","shasum":"91ec10cd48995880004f70c107d7217b9511e231","tarball":"https://registry.npmjs.org/@ai-dap/sdk/-/sdk-0.1.0.tgz","fileCount":11,"unpackedSize":576673,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD48wVWmiJUqAZcrXXAxkcKeeT4i6OpBB+1at1zJ9XvCAIgNWS232wLco1U0Dm8DhKp0B54xVofpVIyo4kA9ACrPuk="}]},"_npmUser":{"name":"bill1118qq","email":"bill1118qq@gmail.com"},"directories":{},"maintainers":[{"name":"bill1118qq","email":"bill1118qq@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.0_1777944901598_0.12421164536355689"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-05T01:35:01.527Z","0.1.0":"2026-05-05T01:35:01.744Z","modified":"2026-05-05T01:35:01.948Z"},"maintainers":[{"name":"bill1118qq","email":"bill1118qq@gmail.com"}],"description":"AI-DAP SDK - Lightweight guide playback engine with zero runtime dependencies","homepage":"https://github.com/bill1118qq/ai-dap#readme","keywords":["dap","digital-adoption","product-tour","onboarding","guide"],"repository":{"type":"git","url":"git+https://github.com/bill1118qq/ai-dap.git","directory":"packages/sdk"},"author":{"name":"AI-DAP Team"},"bugs":{"url":"https://github.com/bill1118qq/ai-dap/issues"},"license":"MIT","readme":"# EasyGuide SDK\n\n**Zero-dependency, lightweight guide playback engine for interactive product tours.**\n\n零依赖的轻量级引导播放引擎，用于创建交互式产品引导和新手教程。\n\n## Demo / 演示\n\nOpen `demo/index.html` in a browser to see all features in action:\n\n```\npackages/sdk/demo/index.html\n```\n\n![SDK Demo](docs/demo-screenshot.png) <!-- TODO: add screenshot -->\n\n## Installation / 安装\n\n```bash\nnpm install @ai-dap/sdk\n# or\npnpm add @ai-dap/sdk\n# or\nyarn add @ai-dap/sdk\n```\n\n## Quick Start / 快速开始\n\n### Offline Mode / 离线模式 (No server needed / 无需服务器)\n\n```ts\nimport { DapSDK } from '@ai-dap/sdk';\n\nconst sdk = await DapSDK.init({\n  guides: [\n    {\n      id: 'onboarding-tour',\n      appId: 'my-app',\n      name: 'Product Tour',\n      description: 'A quick tour of the main features',\n      status: 'published',\n      version: 1,\n      trigger: { type: 'manual' },\n      theme: { primaryColor: '#6366f1' },\n      steps: [\n        {\n          id: 'step-1',\n          order: 1,\n          title: 'Welcome!',\n          content: 'Let me show you around.',\n          target: { css: '#hero-element' },\n          position: 'bottom',\n          highlight: true,\n          scrollToTarget: true,\n        },\n      ],\n      createdAt: new Date().toISOString(),\n      updatedAt: new Date().toISOString(),\n    },\n  ],\n  debug: true,\n});\n\n// Start a guide\nsdk.startGuide('onboarding-tour');\n```\n\n### SaaS Mode / 云端模式 (Fetch guides from API / 从 API 获取引导)\n\n```ts\nconst sdk = await DapSDK.init({\n  sdkKey: 'dap_your_sdk_key',\n  apiBaseUrl: 'https://api.easyguide.com',\n});\n\n// Guides are auto-fetched from the API\nsdk.startGuide('guide-id');\n```\n\n## Configuration / 配置参考\n\n### `DapSDK.init(options)` / 初始化选项\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `sdkKey` | `string` | - | Platform SDK key (SaaS mode / 云端模式密钥) |\n| `apiBaseUrl` | `string` | - | API base URL (SaaS mode / API 基础地址) |\n| `guides` | `Guide[]` | - | Inline guide configs (offline mode / 离线引导配置) |\n| `visitorId` | `string` | auto-generated | Custom visitor identifier (自定义访客 ID) |\n| `autoStart` | `boolean` | `true` | Auto-start guides after init (是否自动开始引导) |\n| `locale` | `string` | `'zh-CN'` | Locale code for i18n (国际化语言代码) |\n| `debug` | `boolean` | `false` | Enable console logging (启用调试日志) |\n\n> **Note**: Use either `sdkKey` + `apiBaseUrl` (SaaS mode) or `guides` (offline mode). Both can be combined.\n\n## API Reference / API 参考\n\n### `DapSDK` — Main SDK Class / 主入口类\n\n```ts\nconst sdk = await DapSDK.init(options: SdkConfig): Promise<DapSDK>\n```\n\n| Method | Description |\n|--------|-------------|\n| `getState()` | Get readonly SDK state (获取 SDK 只读状态) |\n| `getPlayer()` | Get the GuidePlayer instance (获取播放器实例) |\n| `getAnalytics()` | Get the AnalyticsCollector instance (获取分析器实例) |\n| `startGuide(guideId)` | Start a specific guide by ID (按 ID 启动引导) |\n| `stopGuide()` | Stop the currently playing guide (停止当前引导) |\n| `setLocale(locale)` | Change locale at runtime (运行时切换语言) |\n| `destroy()` | Clean up and remove SDK (销毁 SDK 实例) |\n\n### `GuidePlayer` — Step-by-step Playback / 逐步引导播放器\n\n```ts\nconst player = sdk.getPlayer();\n```\n\n| Method | Description |\n|--------|-------------|\n| `start(guide)` | Start playing a guide (开始播放引导) |\n| `next()` | Go to next step (下一步) |\n| `prev()` | Go to previous step (上一步) |\n| `showStep(index)` | Jump to a specific step (跳转到指定步骤) |\n| `complete()` | Complete the guide (完成引导) |\n| `dismiss()` | Dismiss the guide (关闭引导) |\n| `stop()` | Stop programmatically (程序化停止) |\n| `isActive()` | Check if a guide is playing (是否正在播放) |\n| `getState()` | Get player state (获取播放器状态) |\n| `refresh()` | Re-render current step (刷新当前步骤) |\n| `on(event, callback)` | Subscribe to events (订阅事件) |\n| `destroy()` | Clean up (销毁) |\n\n### `HelpWidget` — Floating Help Button / 帮助浮动按钮\n\n```ts\nimport { HelpWidget } from '@ai-dap/sdk';\n\nconst widget = new HelpWidget({\n  guides: publishedGuides,\n  onGuideStart: (guideId) => sdk.startGuide(guideId),\n  theme: { primaryColor: '#6366f1' },\n});\n\nwidget.mount();   // Add to DOM\nwidget.open();    // Open panel\nwidget.close();   // Close panel\nwidget.toggle();  // Toggle open/close\nwidget.unmount(); // Remove from DOM\nwidget.setGuides(newGuides); // Update available guides\nwidget.setPlaying(true);     // Update playing state\nwidget.isOpen();             // Check if panel is open\n```\n\n### `Tooltip` — Guide Tooltip / 引导提示框\n\n```ts\nimport { Tooltip } from '@ai-dap/sdk';\n\nconst tooltip = new Tooltip();\ntooltip.show({\n  targetElement: document.querySelector('#my-element'),\n  title: 'Step Title',\n  content: 'Description text',\n  position: 'bottom',    // top|bottom|left|right|top-start|top-end|bottom-start|bottom-end|center\n  isFirst: true,\n  isLast: false,\n  stepIndex: 0,\n  totalSteps: 3,\n  onNext: () => { /* ... */ },\n  onPrev: () => { /* ... */ },\n  onDismiss: () => { /* ... */ },\n});\ntooltip.hide();\ntooltip.applyTheme(theme);\n```\n\n### `Spotlight` — Element Highlight / 元素聚光灯\n\n```ts\nimport { Spotlight } from '@ai-dap/sdk';\n\nconst spotlight = new Spotlight();\nspotlight.highlight(document.querySelector('#target'));\nspotlight.clear();\nspotlight.applyTheme(theme);\n```\n\n### `Overlay` — Full-screen Dimmer / 全屏遮罩\n\n```ts\nimport { Overlay } from '@ai-dap/sdk';\n\nconst overlay = new Overlay();\noverlay.show();\noverlay.hide();\noverlay.applyTheme(theme);\n```\n\n### `AnalyticsCollector` — Event Tracking / 事件追踪\n\n```ts\nconst analytics = sdk.getAnalytics();\nanalytics.start();                          // Start periodic flush\nanalytics.stop();                           // Stop and flush\nanalytics.track('guide_started', { guideId: 'tour-1' });\nanalytics.setGuideContext(guideId, stepId); // Set current context\n```\n\n## Guide Step Format / 引导步骤格式\n\nEach step in a `Guide.steps` array follows this structure:\n\n```ts\ninterface GuideStep {\n  id: string;                // Unique step ID (唯一标识)\n  order: number;             // Display order (排序, 1-based)\n  title: string;             // Tooltip title (标题)\n  content: string;           // Tooltip content (内容)\n  target: {\n    css: string;             // CSS selector (CSS 选择器)\n    fallback?: string;       // Fallback selector (备选选择器)\n    waitTimeout?: number;    // Max wait time in ms (最大等待时间)\n  };\n  position: Position;        // Tooltip position (提示框位置)\n  imageUrl?: string;         // Optional image URL (可选图片)\n  highlight: boolean;        // Whether to spotlight the target (是否高亮)\n  scrollToTarget: boolean;   // Whether to scroll to target (是否滚动到目标)\n}\n```\n\n### Position Values / 位置取值\n\n```\ntop | bottom | left | right | top-start | top-end | bottom-start | bottom-end | center\n```\n\n### Full Guide Structure / 完整引导结构\n\n```ts\ninterface Guide {\n  id: string;                // Unique guide ID\n  appId: string;             // Application ID\n  name: string;              // Guide name (引导名称)\n  description: string;       // Guide description (引导描述)\n  status: 'draft' | 'published' | 'archived';\n  steps: GuideStep[];        // Ordered array of steps (步骤数组)\n  trigger: {\n    type: 'page_load' | 'selector_appears' | 'url_match' | 'manual' | 'schedule' | 'event';\n    selector?: string;       // For selector_appears trigger\n    urlPattern?: string;     // For url_match trigger\n    delay?: number;          // Delay in ms before auto-start\n    maxShowCount?: number;   // Max times to show this guide\n  };\n  theme: {\n    primaryColor?: string;   // Brand color (品牌色)\n    fontFamily?: string;     // Custom font (自定义字体)\n    borderRadius?: number;   // Border radius (圆角大小)\n    overlayColor?: string;   // Overlay background color\n    overlayOpacity?: number; // Overlay opacity (0-1)\n    cssVariables?: Record<string, string>;\n  };\n  version: number;           // Guide version (版本号)\n  i18n?: Record<string, Record<string, { title: string; content: string }>>;\n  createdAt: string;\n  updatedAt: string;\n}\n```\n\n## Events / 事件\n\nThe `GuidePlayer` emits the following events (via `player.on(event, callback)`):\n\n| Event | Payload | Description |\n|-------|---------|-------------|\n| `start` | `(guide: Guide)` | Guide started (引导开始) |\n| `step:enter` | `(index: number, step: GuideStep)` | Step entered (进入步骤) |\n| `step:exit` | `(index: number)` | Step exited (离开步骤) |\n| `complete` | `(guide: Guide)` | Guide completed (引导完成) |\n| `dismiss` | `(guide: Guide)` | User dismissed (用户关闭) |\n| `stop` | `(guide: Guide)` | Programmatically stopped (程序停止) |\n\n### Analytics Events / 分析事件\n\nThe `AnalyticsCollector` automatically tracks:\n\n| Event | When / 触发时机 |\n|-------|-----------------|\n| `sdk_initialized` | SDK init completes (SDK 初始化完成) |\n| `guide_started` | Guide begins playing (引导开始播放) |\n| `guide_completed` | User finishes all steps (用户完成所有步骤) |\n| `guide_dismissed` | User dismisses early (用户提前关闭) |\n| `step_viewed` | A step is displayed (步骤被展示) |\n\n## Progress Persistence / 进度持久化\n\nThe SDK automatically saves guide progress to `localStorage` under the key `dap_guide_progress`. Completed guides won't auto-start again.\n\n```ts\nimport { getProgress, updateProgress, isGuideCompleted, getLastStepIndex } from '@ai-dap/sdk';\n\nisGuideCompleted('tour-1');        // boolean\ngetLastStepIndex('tour-1');        // number\ngetProgress();                     // Record<string, GuideProgress>\nupdateProgress('tour-1', 3, false); // Update step 3, not completed\n```\n\n## Shadow DOM / 隐私 DOM 隔离\n\nThe `HelpWidget` uses **Shadow DOM** for complete style isolation. Widget styles are injected inside the shadow root and will never conflict with your application's CSS.\n\n> `Tooltip`, `Spotlight`, and `Overlay` use light DOM with CSS variables for theming, making them fully customizable.\n\n## Keyboard Navigation / 键盘导航\n\nWhen a guide is active, the following keyboard shortcuts are available:\n\n| Key | Action |\n|-----|--------|\n| `ArrowRight` / `ArrowDown` | Next step (下一步) |\n| `ArrowLeft` / `ArrowUp` | Previous step (上一步) |\n| `Escape` | Dismiss guide (关闭引导) |\n\n## Browser Support / 浏览器支持\n\n| Browser | Version |\n|---------|---------|\n| Chrome | 90+ |\n| Firefox | 88+ |\n| Safari | 14+ |\n| Edge | 90+ |\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-d8dd52782449431f753b7e9d2312a1b6"}