@coxwave/tap-sdk 0.0.11 → 0.1.0

package/README.md

@@ -1,9 +1,35 @@
 # @coxwave/tap-sdk
 
-TapSDK is a lightweight JavaScript SDK for embedding the EduTap AI tutor inside any web property. It renders the toggle button, manages the iframe chat surface, and provides a structured messaging layer for bi-directional communication with the host page.
+TapSDK is a lightweight JavaScript loader (~2-3KB) that dynamically loads the EduTap AI tutor from CDN. It provides the same familiar API for embedding interactive chat into any web property, but with the flexibility of instant updates without requiring npm package updates.
+
+## Architecture
+
+This package is a **bootloader** that follows the ChannelTalk pattern:
+
+1. **Loader Package** (`@coxwave/tap-sdk`) - Published to npm (~2.3KB)
+   - Provides the familiar `TapSDK` API
+   - Dynamically loads the actual SDK from CloudFront CDN
+   - Handles version management and integrity checks
+   - Only needs updates when API surface changes
+
+2. **Core SDK** (`tap-kit-core`) - Deployed to S3/CloudFront
+   - Contains the actual implementation (UI, iframe management, etc.)
+   - Can be updated instantly without npm publishing
+   - Version controlled with timestamps (YYYYMMDDHHMMSS format)
+   - URL: `https://files.edutap.ai/tap-sdk/core-{VERSION}.js`
+
+### Why This Architecture?
+
+- **Instant Updates**: Deploy bug fixes and features to all users immediately
+- **Smaller npm Package**: ~2-3KB loader vs ~20KB+ full SDK
+- **Version Control**: Centralized version management via CDN
+- **Integrity Checks**: Subresource Integrity (SRI) ensures security
+- **Backward Compatibility**: Same API surface, seamless for existing users
 
 ## Installation
 
+### via npm
+
 ```bash
 npm install @coxwave/tap-sdk
 # or
@@ -12,8 +38,21 @@ pnpm add @coxwave/tap-sdk
 yarn add @coxwave/tap-sdk
 ```
 
+### Understanding the Loader
+
+When you install `@coxwave/tap-sdk` from npm, you get a small loader that:
+
+1. Imports the package normally: `import TapSDK from '@coxwave/tap-sdk'`
+2. On instantiation, loads the core SDK from `https://files.edutap.ai/tap-sdk/core-{VERSION}.js`
+3. Proxies all API calls to the loaded core SDK
+4. Verifies integrity using SHA-384 hashes
+
+**No code changes required** - the API is identical to the previous monolithic SDK.
+
 ## Quick Start
 
+### ES Modules (npm)
+
 ```ts
 import TapSDK from "@coxwave/tap-sdk";
 
@@ -28,17 +67,34 @@ await sdk.init({
     courseId: "course-456",
     clipId: null,
   },
-  customStyles: {
-    chatBody: {
-      position: { top: "64px", right: "32px" },
-      width: "360px",
-      height: "calc(100% - 128px)",
-      borderRadius: "18px",
-    },
+  container: {
+    position: { top: "64px", right: "32px" },
+    width: "360px",
+    height: "calc(100% - 128px)",
+    borderRadius: "18px",
   },
 });
 ```
 
+### How It Works
+
+```mermaid
+sequenceDiagram
+    participant App as Your App
+    participant Loader as tap-sdk (npm)
+    participant CDN as CloudFront CDN
+    participant Core as Core SDK
+
+    App->>Loader: import TapSDK
+    App->>Loader: new TapSDK(config)
+    Loader->>CDN: GET /tap-sdk/core-{VERSION}.js
+    CDN-->>Loader: JavaScript Bundle
+    Loader->>Core: Initialize with config
+    App->>Loader: sdk.init(params)
+    Loader->>Core: Forward init call
+    Core-->>App: Chat Interface Ready
+```
+
 On initialization the SDK:
 
 - ensures it is running in a browser (guards against SSR)
@@ -52,29 +108,30 @@ On initialization the SDK:
 
 The SDK will attach alarm badges and click handlers to the element with the provided `buttonId`.
 
-### Chat body
+### Chat container
 
-The chat surface is a fixed container (`#cw-chat-body`). You can override:
+The chat surface is a fixed-position container. Customize via the `container` option:
 
 - `position` — partial `{ top/right/bottom/left }` values (strings with units)
 - `width` / `height` — strings with CSS units
-- `borderRadius`
+- `borderRadius` — border radius (e.g., "16px")
 
-The container gracefully hides itself when the chat closes and expands when EduTap opens embedded PDFs.
+The container automatically shows/hides when chat opens/closes and expands when EduTap displays embedded PDFs.
 
 ### Alarm notifications & pop-ups
 
-EduTap can send rich alarm notifications and HTML pop-ups over the iframe channel. The SDK fades alarms in/out, handles clicks, and renders pop-ups next to the chat container while inheriting relevant sizing from `chatBody` styles.
+EduTap can send rich alarm notifications and HTML pop-ups over the iframe channel. The SDK automatically fades alarms in/out, handles clicks, and renders pop-ups next to the chat container.
 
 ## Runtime API
 
 ### `init(options)`
 
-Initializes the iframe, performs the handshake, and wires up UI controls. Required options:
+Initializes the iframe, performs the handshake, and wires up UI controls.
 
-- `buttonId` – string (required) - ID of the HTML element to attach the toggle button to
-- `course` – minimal course context (`userId`, `courseId`, `clipId`)
-- `customStyles?` – `{ chatBody? }` - optional UI customization
+**Options:**
+- `buttonId` (required) – ID of the HTML element to attach the toggle button to
+- `course` (required) – Course context with `userId`, `courseId`, `clipId`
+- `container?` – Optional UI customization with `position`, `width`, `height`, `borderRadius`
 
 ### `events.seekTimeline({ clipId, clipPlayHead })`
 
@@ -116,26 +173,98 @@ sdk.events.onPdfOpen(() => console.log("PDF overlay opened"));
 sdk.events.onPdfClose(() => console.log("PDF overlay closed"));
 ```
 
-## TypeScript support
+## TypeScript Support
 
-Type definitions ship with the package. Notable exports:
+Type definitions are included with the package. Key exports:
+
+```ts
+import type {
+  TapSDKConfig,
+  TapSDKInitParams,
+  Course,
+  ContainerStyle,
+  PositionType,
+  SeekTimelineParamsType,
+  AlarmMessageInstanceType,
+} from "@coxwave/tap-sdk";
+```
 
-- `TapSDKConfig`
-- `Course`
-- `CustomStyles`
-- `ChatBodyStyle`
-- `SeekTimelineParamsType`
-- `AlarmMessageInstanceType`
+All iframe message contracts are sourced from `@coxwave/tap-messages` and validated with valibot schemas.
+
+## Version Management
+
+### How It Works
+
+The npm package (`@coxwave/tap-sdk`) simply loads the CDN loader script:
+
+```typescript
+const CDN_LOADER_URL = 'https://files.edutap.ai/tap-sdk/loader.js';
+```
 
-All message contracts are sourced from `@coxwave/tap-messages` and validated with `valibot` during the iframe handshake.
+The CDN loader (`tap-kit-core/loader.ts`) handles all version management:
+1. Fetches `versions.json` to get the latest version
+2. Loads the appropriate `tap-kit-{version}.js` with SRI verification
+3. Initializes the actual SDK
 
-## Browser support
+### Deployment Workflow
+
+**For SDK updates (most common):**
+```bash
+cd packages/tap-kit-core
+pnpm build
+./scripts/deploy-s3.sh
+```
+
+This deploys to CDN and all users automatically get the update.
+
+**For npm package updates (rare):**
+```bash
+cd packages/tap-sdk
+pnpm build
+pnpm publish:npm
+```
+
+Only needed when the API surface changes (new methods, types, etc).
+
+## Security Considerations
+
+### Content Security Policy (CSP)
+
+If your site uses CSP headers, add these directives:
+
+```http
+Content-Security-Policy:
+  script-src 'self' https://files.edutap.ai;
+  style-src 'self' 'unsafe-inline';
+  connect-src 'self' https://your-tap-api-domain.com;
+  frame-src 'self' https://your-edutap-domain.com;
+```
+
+**Important:**
+- `script-src` must include `https://files.edutap.ai` for CDN loading
+- `style-src 'unsafe-inline'` is required for injected CSS (Vanilla Extract)
+
+### Subresource Integrity (SRI)
+
+The loader verifies CDN files using SHA-384 integrity checks:
+
+```typescript
+// In loader.ts
+script.integrity = CDN_INTEGRITY;
+script.crossOrigin = 'anonymous';
+```
+
+This ensures the loaded SDK hasn't been tampered with, even if CloudFront is compromised.
+
+## Browser Support
 
 - Chrome 60+
 - Firefox 60+
 - Safari 12+
 - Edge 79+
 
+Requires modern browsers with ES2020 support and `postMessage` API.
+
 ## License
 
 MIT © 2025 Coxwave

package/dist/index.d.cts

@@ -1,49 +1,12 @@
-import { ChatInitMessage, ChatOpenMessage, ChatCloseMessage, TimelineSeekMessage, AlarmClickMessage, PopUpCloseMessage, PdfEnlargedMessage, PdfShrinkedMessage, ChatInitiatedMessage, ChatOpenedMessage, ChatClosedMessage, AlarmFadeInMessage, PopUpOpenMessage, PdfOpenMessage, PdfCloseMessage, AlarmMessageInstanceType } from '@coxwave/tap-messages';
+import { AlarmMessageInstanceType } from '@coxwave/tap-messages';
+export { AlarmMessageInstanceType, AlarmType } from '@coxwave/tap-messages';
 
-type Unsubscribe = () => void;
-type Message = {
-    type: string;
-    [key: string]: any;
-};
-declare abstract class Messenger<TToTargetMessages extends Message = Message, TFromTargetMessage extends Message = Message> {
-    protected listeners: Map<TFromTargetMessage["type"], ((event: MessageEvent) => void)[]>;
-    protected unifiedMessageHandler: ((event: MessageEvent) => void) | null;
-    protected on<T extends TFromTargetMessage["type"]>(messageType: T, callback: (data: Extract<TFromTargetMessage, {
-        type: T;
-    }>) => void): Unsubscribe;
-    removeListener(messageType: TFromTargetMessage["type"]): void;
-    removeAllListeners(): void;
-    postMessage(message: TToTargetMessages): boolean;
-    protected abstract isValidOrigin(event: MessageEvent): boolean;
-    protected abstract getMessageTarget(): Window | null;
-    protected abstract getTargetOrigin(): string;
-}
-
-interface HandshakeOptions {
-    timeout?: number;
-    maxRetries?: number;
-    retryInterval?: number;
-}
-
-interface LogEvent {
-    action: string;
-    category: string;
-    label?: string;
-    value?: number;
-    customParams?: Record<string, any>;
-}
-interface EventMiddleware {
-    handle(event: LogEvent): void;
-}
-declare class EventLogger {
-    private middlewares;
-    addMiddleware(middleware: EventMiddleware): void;
-    removeMiddleware(middleware: EventMiddleware): void;
-    log(event: LogEvent): void;
-    logChatAction(action: "opened" | "closed" | "initialized", customParams?: Record<string, any>): void;
-    logButtonClick(buttonType: "toggle" | "alarm", state?: string, customParams?: Record<string, any>): void;
-    logSDKInitialization(success: boolean, startTime: number, error?: string): void;
-}
+/**
+ * TapSDK Type Definitions
+ *
+ * Re-exported types for API compatibility with the loader.
+ * These types match the actual SDK implementation in tap-sdk-cdn.
+ */
 
 type TapSDKConfig = {
     apiKey: string;
@@ -71,155 +34,86 @@ type PositionType = {
     right?: string;
     bottom?: string;
 };
-
 type SeekTimelineParamsType = {
     clipId: string;
     clipPlayHead: number;
 };
 
-type ToTapMessage = ChatInitMessage | ChatOpenMessage | ChatCloseMessage | TimelineSeekMessage | AlarmClickMessage | PopUpCloseMessage | PdfEnlargedMessage | PdfShrinkedMessage;
-type FromTapMessage = ChatInitiatedMessage | ChatOpenedMessage | ChatClosedMessage | AlarmFadeInMessage | PopUpOpenMessage | PdfOpenMessage | PdfCloseMessage | TimelineSeekMessage;
-interface ChatInitConfig {
-    course: Course;
-    container?: ContainerStyle;
-}
-declare class TapIframeBridge extends Messenger<ToTapMessage, FromTapMessage> {
-    #private;
-    protected hostOrigin: string;
-    protected apiKey: string;
-    protected iframe: HTMLIFrameElement | null;
-    private eventLogger;
-    constructor({ hostOrigin, apiKey, eventLogger, }: {
-        hostOrigin: string;
-        apiKey: string;
-        eventLogger?: EventLogger;
-    });
-    protected isValidOrigin(_event: MessageEvent): boolean;
-    protected getMessageTarget(): Window | null;
-    protected getTargetOrigin(): string;
-    renderIframe(iframeRootElement?: HTMLElement): Promise<HTMLIFrameElement>;
-    hasIframe(): boolean;
-    ensureIframe(rootElement?: HTMLElement): Promise<HTMLIFrameElement>;
-    removeIframe(): void;
-    postToTap: (message: ToTapMessage) => boolean;
-    listenToTap: <T extends "timeline:seek" | "chat:opened" | "chat:initiated" | "chat:closed" | "alarm:fadeIn" | "popUp:open" | "pdf:open" | "pdf:close">(messageType: T, callback: (data: Extract<TimelineSeekMessage, {
-        type: T;
-    }> | Extract<ChatInitiatedMessage, {
-        type: T;
-    }> | Extract<ChatOpenedMessage, {
-        type: T;
-    }> | Extract<ChatClosedMessage, {
-        type: T;
-    }> | Extract<AlarmFadeInMessage, {
-        type: T;
-    }> | Extract<PopUpOpenMessage, {
-        type: T;
-    }> | Extract<PdfOpenMessage, {
-        type: T;
-    }> | Extract<PdfCloseMessage, {
-        type: T;
-    }>) => void) => () => void;
-    performHandshake(config: ChatInitConfig, options?: HandshakeOptions): Promise<ChatInitiatedMessage>;
-    static defaultHandshakeOptions: HandshakeOptions;
-}
+/**
+ * TapSDK - npm package wrapper
+ *
+ * Simply loads the CDN loader which handles version management and SDK loading.
+ * This keeps the npm package minimal and allows instant updates via CDN.
+ */
 
-declare class EventManager {
-    private iframeBridge;
-    constructor(iframeBridge: TapIframeBridge);
-    /**
-     * Updates timeline position in the chat interface
-     * @param params - Timeline seek parameters
-     */
-    seekTimeline({ clipId, clipPlayHead }: SeekTimelineParamsType): void;
-    onTimelineSeek(handler: (clipPlayHead: number, clipId: string) => void): void;
-    onChatOpened(handler: () => void): void;
-    onChatClosed(handler: () => void): void;
-    onChatInitiated(handler: () => void): void;
-    onAlarmFadeIn(handler: (messageInfo: AlarmMessageInstanceType) => void): void;
-    onPopUpOpen(handler: (popUpInfo: PopUpOpenMessage["popUpInfo"]) => void): void;
-    onPdfOpen(handler: () => void): void;
-    onPdfClose(handler: () => void): void;
+type TapSDKConstructor = new (config: TapSDKConfig) => TapSDKInstance;
+declare global {
+    interface Window {
+        TapSDK?: TapSDKConstructor;
+        __TAP_SDK_LOADER_LOADED__?: boolean;
+        __TAP_SDK_LOADER_LOADING__?: Promise<void>;
+    }
+}
+interface TapSDKInstance {
+    events: {
+        seekTimeline: (params: SeekTimelineParamsType) => void;
+        onTimelineSeek: (callback: (clipPlayHead: number, clipId: string) => void) => void;
+        onChatInitiated: (handler: () => void) => void;
+        onChatOpened: (handler: () => void) => void;
+        onChatClosed: (handler: () => void) => void;
+        onAlarmFadeIn: (handler: (messageInfo: AlarmMessageInstanceType) => void) => void;
+        onPopUpOpen: (handler: (popUpInfo: any) => void) => void;
+        onPdfOpen: (handler: () => void) => void;
+        onPdfClose: (handler: () => void) => void;
+    };
+    isOpen: boolean;
+    isInitialized: boolean;
+    init(params: TapSDKInitParams): Promise<void>;
+    destroy(): void;
+    initChat(params: TapSDKInitParams): Promise<void>;
+    postChatInfo(params: {
+        clipId: string;
+        clipPlayHead: number;
+    }): Promise<void>;
+    getTimelineInfo(params: {
+        callback: (clipPlayHead: number, clipId: string) => void;
+    }): Promise<void>;
 }
-
 /**
- * TapSDK - Interactive chat SDK with toggle button and iframe communication
+ * TapSDK Wrapper Class
  *
- * @example
- * ```typescript
- * const sdk = new TapSDK({ apiKey: 'your-key' });
- * await sdk.init({ course: { userId: 'user1', courseId: 'course1' } });
- * ```
+ * Loads the CDN loader and proxies all calls to the actual SDK
  */
-declare class TapSDK {
-    private apiKey;
-    private iframeBridge;
-    events: EventManager;
-    private eventLogger;
-    private container;
-    private button;
-    private alarm;
-    private containerVisible;
-    private isPdfOpen;
-    private _isInitialized;
-    /**
-     * Creates a new TapSDK instance
-     * @param config - SDK configuration options
-     */
-    constructor({ apiKey }: TapSDKConfig);
+declare class TapSDK implements TapSDKInstance {
+    private config;
+    private sdkInstance?;
+    private loadPromise;
+    constructor(config: TapSDKConfig);
+    private loadAndInitialize;
+    private ensureLoaded;
+    get events(): {
+        seekTimeline: (params: SeekTimelineParamsType) => void;
+        onTimelineSeek: (callback: (clipPlayHead: number, clipId: string) => void) => void;
+        onChatInitiated: (handler: () => void) => void;
+        onChatOpened: (handler: () => void) => void;
+        onChatClosed: (handler: () => void) => void;
+        onAlarmFadeIn: (handler: (messageInfo: AlarmMessageInstanceType) => void) => void;
+        onPopUpOpen: (handler: (popUpInfo: any) => void) => void;
+        onPdfOpen: (handler: () => void) => void;
+        onPdfClose: (handler: () => void) => void;
+    };
     get isOpen(): boolean;
     get isInitialized(): boolean;
-    /**
-     * Initializes the TapSDK with course data and optional container styles
-     * @param params - Initialization parameters
-     * @param params.course - Course information for chat context
-     * @param params.container - Optional container styling options
-     * @throws {Error} When initialization fails
-     */
-    init({ buttonId, course, container }: TapSDKInitParams): Promise<void>;
-    /**
-     * Destroys the SDK instance and cleans up all resources
-     */
+    init(params: TapSDKInitParams): Promise<void>;
     destroy(): void;
-    private setupEventLogger;
-    private toggleChatOpen;
-    private validateEnvironment;
-    private setupContainer;
-    private updateContainerStyles;
-    private setupButton;
-    private setupEventListeners;
-    /**
-     * Update container styles dynamically
-     */
-    updateStyles(container: ContainerStyle): void;
-    /**
-     * POC: Dynamically set container size
-     */
-    setContainerSize(width: string, height: string): void;
-    /**
-     * POC: Animate container resize
-     */
-    animateContainerResize(width: string, height: string, duration?: number): void;
-    /**
-     * POC: Set responsive mode
-     */
-    setResponsiveMode(mode: "compact" | "normal" | "expanded"): void;
-    /**
-     * @deprecated Use `init` method instead. Will be removed in v1.0.0
-     */
     initChat(params: TapSDKInitParams): Promise<void>;
-    /**
-     * @deprecated Use `events.seekTimeline` method instead. Will be removed in v1.0.0
-     */
-    postChatInfo({ clipId, clipPlayHead, }: {
+    postChatInfo(params: {
         clipId: string;
         clipPlayHead: number;
-    }): void;
-    /**
-     * @deprecated Use `events.onTimelineSeek` method instead. Will be removed in v1.0.0
-     */
-    getTimelineInfo({ callback, }: {
+    }): Promise<void>;
+    getTimelineInfo(params: {
         callback: (clipPlayHead: number, clipId: string) => void;
-    }): void;
+    }): Promise<void>;
 }
 
-export { TapSDK as default };
+export { type ContainerStyle, type Course, type PositionType, type SeekTimelineParamsType, TapSDK, type TapSDKConfig, type TapSDKConstructor, type TapSDKInitParams, type TapSDKInstance, TapSDK as default };