@coxwave/tap-kit-types 0.0.34

package/README.md

@@ -0,0 +1,84 @@
+# @coxwave/tap-kit-types
+
+Shared TypeScript types for TapKit SDK packages.
+
+## Purpose
+
+This package serves as the **single source of truth** for all TapKit type definitions, eliminating duplication between:
+
+- `@coxwave/tap-sdk` - npm wrapper package
+- `@coxwave/tap-kit-core` - CDN implementation
+
+## Installation
+
+```bash
+npm install @coxwave/tap-kit-types
+# or
+pnpm add @coxwave/tap-kit-types
+```
+
+## Usage
+
+```typescript
+import type {
+  TapKitConfig,
+  TapKitInitParams,
+  Course,
+  ContainerStyle,
+} from "@coxwave/tap-kit-types";
+
+const config: TapKitConfig = {
+  apiKey: "your-api-key",
+};
+
+const params: TapKitInitParams = {
+  buttonId: "tap-button",
+  course: {
+    userId: "user-1",
+    courseId: "course-1",
+    clipId: "clip-1",
+  },
+};
+```
+
+## Exported Types
+
+### Core Configuration
+
+- `TapKitConfig` - SDK configuration
+- `TapKitInitParams` - Initialization parameters
+- `Course` - Course information
+
+### Styling
+
+- `ContainerStyle` - Container styling options
+- `PositionType` - Position configuration
+- `CustomStyles` - Backward compatibility alias
+
+### Events
+
+- `SeekTimelineParamsType` - Timeline seek parameters
+- `ShortcutKeyPropertiesType` - Keyboard shortcut configuration
+- `ContainerVisibility` - Visibility state
+
+### Errors
+
+- `TapKitError` - Base error class
+- `TapKitInitializationError` - Initialization errors
+- `TapKitMessageError` - Message communication errors
+- `TapKitConfigurationError` - Configuration errors
+- `TapKitLoaderError` - Loader errors
+- `TapKitIframeError` - iframe operation errors
+
+### Re-exports from @coxwave/tap-messages
+
+- `AlarmMessageInstanceType`
+- `AlarmType`
+
+## Version
+
+Current version: 0.1.0
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,176 @@
+import { AlarmMessageInstanceType } from '@coxwave/tap-messages';
+export { AlarmMessageInstanceType, AlarmType } from '@coxwave/tap-messages';
+
+/**
+ * @coxwave/tap-kit-types
+ * Shared TypeScript types for TapKit SDK packages
+ *
+ * This package serves as the single source of truth for all TapKit types,
+ * used by both @coxwave/tap-sdk (npm wrapper) and @coxwave/tap-kit-core (CDN implementation).
+ */
+
+/**
+ * SDK Configuration
+ */
+type TapKitConfig = {
+    apiKey: string;
+};
+/**
+ * SDK Initialization Parameters
+ */
+type TapKitInitParams = {
+    buttonId: string;
+    course: Course;
+    container?: ContainerStyle;
+};
+/**
+ * Course Information
+ */
+type Course = {
+    userId: string;
+    courseId: string;
+    clipId: string;
+    clipPlayHead?: number;
+};
+/**
+ * Container Styling
+ */
+type ContainerStyle = {
+    position?: PositionType;
+    width?: string;
+    height?: string;
+    borderRadius?: string;
+};
+type PositionType = {
+    top?: string;
+    left?: string;
+    right?: string;
+    bottom?: string;
+};
+/**
+ * Flattened container styles (backward compatibility)
+ */
+type CustomStyles = ContainerStyle;
+/**
+ * Timeline seek parameters
+ */
+type SeekTimelineParamsType = {
+    clipId: string;
+    clipPlayHead: number;
+};
+/**
+ * Shortcut Key Configuration
+ */
+type ShortcutKeyPropertiesType = {
+    key: string;
+    modifier: "ctrlKey" | "altKey" | "shiftKey" | "metaKey" | "";
+};
+/**
+ * Container Visibility State
+ */
+type ContainerVisibility = "open" | "closed";
+/**
+ * Pop-up information passed to onPopUpOpen event handler
+ */
+interface PopUpInfo {
+    html: string;
+    [key: string]: unknown;
+}
+/**
+ * Base TapKit instance interface
+ * Shared properties and methods between core and wrapper
+ */
+interface TapKitBaseInstance {
+    events: {
+        seekTimeline: (params: SeekTimelineParamsType) => Promise<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: PopUpInfo) => void) => () => void;
+        onPdfOpen: (handler: () => void) => () => void;
+        onPdfClose: (handler: () => void) => () => void;
+    };
+    isOpen: boolean;
+    isInitialized: boolean;
+    ready: Promise<void>;
+    init(params: TapKitInitParams): Promise<void>;
+    destroy(): void;
+}
+/**
+ * TapKit instance type from tap-kit-core
+ * This matches the actual TapKit class exported from @coxwave/tap-kit-core
+ * Exported for advanced use cases (e.g., when using window.TapKit directly)
+ *
+ * Currently identical to TapKitBaseInstance, but kept as separate type
+ * for future extensibility and semantic clarity
+ */
+interface TapKitCoreInstance extends TapKitBaseInstance {
+}
+/**
+ * Public TapKit instance interface
+ * This is what users interact with when using the SDK
+ */
+interface TapKitInstance extends TapKitBaseInstance {
+    getVersion(): string;
+}
+/**
+ * TapKit constructor type
+ */
+type TapKitConstructor = new (config: TapKitConfig) => TapKitCoreInstance;
+declare const TAP_ERROR_MARKER = "__tap_sdk_error__";
+interface TapErrorOptions {
+    code?: string;
+    cause?: Error;
+}
+/**
+ * Base error class for all TapKit errors
+ * Supports serialization across iframe boundaries
+ */
+declare class TapKitError extends Error {
+    cause: Error | undefined;
+    code: string | undefined;
+    constructor(message: string, options?: TapErrorOptions);
+    /**
+     * Restore error from postMessage serialization
+     */
+    static fromPossibleFrameSafeError(error: any): TapKitError | null;
+}
+/**
+ * Error thrown when SDK initialization fails
+ */
+declare class TapKitInitializationError extends TapKitError {
+    constructor(message: string, options?: TapErrorOptions);
+    static fromPossibleFrameSafeError(error: any): TapKitInitializationError | null;
+}
+/**
+ * Error thrown when message communication fails
+ */
+declare class TapKitMessageError extends TapKitError {
+    constructor(message: string, options?: TapErrorOptions);
+    static fromPossibleFrameSafeError(error: any): TapKitMessageError | null;
+}
+/**
+ * Error thrown when configuration is invalid
+ */
+declare class TapKitConfigurationError extends TapKitError {
+    constructor(message: string, options?: TapErrorOptions);
+    static fromPossibleFrameSafeError(error: any): TapKitConfigurationError | null;
+}
+/**
+ * Error thrown when loader fails to fetch or load resources
+ */
+declare class TapKitLoaderError extends TapKitError {
+    constructor(message: string, options?: TapErrorOptions);
+    static fromPossibleFrameSafeError(error: any): TapKitLoaderError | null;
+}
+/**
+ * Error thrown when iframe operations fail
+ */
+declare class TapKitIframeError extends TapKitError {
+    constructor(message: string, options?: TapErrorOptions);
+    static fromPossibleFrameSafeError(error: any): TapKitIframeError | null;
+}
+
+export { type ContainerStyle, type ContainerVisibility, type Course, type CustomStyles, TapKitInitializationError as InitializationError, type PopUpInfo, type PositionType, type SeekTimelineParamsType, type ShortcutKeyPropertiesType, TAP_ERROR_MARKER, type TapErrorOptions, type TapKitBaseInstance, type TapKitConfig, TapKitConfigurationError, type TapKitConstructor, type TapKitCoreInstance, TapKitError, TapKitIframeError, type TapKitInitParams, TapKitInitializationError, type TapKitInstance, TapKitLoaderError, TapKitMessageError };

package/dist/index.js

@@ -0,0 +1,136 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// index.ts
+var TAP_ERROR_MARKER = "__tap_sdk_error__";
+var TapKitError = class _TapKitError extends Error {
+  constructor(message, options) {
+    super(message);
+    __publicField(this, "cause");
+    __publicField(this, "code");
+    this.name = "TapKitError";
+    this.code = options?.code;
+    this.cause = options?.cause;
+  }
+  /**
+   * Restore error from postMessage serialization
+   */
+  static fromPossibleFrameSafeError(error) {
+    if (error instanceof _TapKitError) {
+      return error;
+    }
+    if (error && typeof error === "object" && TAP_ERROR_MARKER in error && error[TAP_ERROR_MARKER] === "TapKitError") {
+      const err = new _TapKitError(error.message, {
+        code: error.code
+      });
+      err.stack = error.stack;
+      return err;
+    }
+    return null;
+  }
+};
+var TapKitInitializationError = class _TapKitInitializationError extends TapKitError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "TapKitInitializationError";
+    this.code = options?.code ?? "ERR_INITIALIZATION";
+  }
+  static fromPossibleFrameSafeError(error) {
+    if (error instanceof _TapKitInitializationError) {
+      return error;
+    }
+    if (error && typeof error === "object" && TAP_ERROR_MARKER in error && error[TAP_ERROR_MARKER] === "TapKitInitializationError") {
+      const err = new _TapKitInitializationError(error.message, {
+        code: error.code
+      });
+      err.stack = error.stack;
+      return err;
+    }
+    return null;
+  }
+};
+var TapKitMessageError = class _TapKitMessageError extends TapKitError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "TapKitMessageError";
+    this.code = options?.code ?? "ERR_MESSAGE";
+  }
+  static fromPossibleFrameSafeError(error) {
+    if (error instanceof _TapKitMessageError) {
+      return error;
+    }
+    if (error && typeof error === "object" && TAP_ERROR_MARKER in error && error[TAP_ERROR_MARKER] === "TapKitMessageError") {
+      const err = new _TapKitMessageError(error.message, {
+        code: error.code
+      });
+      err.stack = error.stack;
+      return err;
+    }
+    return null;
+  }
+};
+var TapKitConfigurationError = class _TapKitConfigurationError extends TapKitError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "TapKitConfigurationError";
+    this.code = options?.code ?? "ERR_CONFIGURATION";
+  }
+  static fromPossibleFrameSafeError(error) {
+    if (error instanceof _TapKitConfigurationError) {
+      return error;
+    }
+    if (error && typeof error === "object" && TAP_ERROR_MARKER in error && error[TAP_ERROR_MARKER] === "TapKitConfigurationError") {
+      const err = new _TapKitConfigurationError(error.message, {
+        code: error.code
+      });
+      err.stack = error.stack;
+      return err;
+    }
+    return null;
+  }
+};
+var TapKitLoaderError = class _TapKitLoaderError extends TapKitError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "TapKitLoaderError";
+    this.code = options?.code ?? "ERR_LOADER";
+  }
+  static fromPossibleFrameSafeError(error) {
+    if (error instanceof _TapKitLoaderError) {
+      return error;
+    }
+    if (error && typeof error === "object" && TAP_ERROR_MARKER in error && error[TAP_ERROR_MARKER] === "TapKitLoaderError") {
+      const err = new _TapKitLoaderError(error.message, {
+        code: error.code
+      });
+      err.stack = error.stack;
+      return err;
+    }
+    return null;
+  }
+};
+var TapKitIframeError = class _TapKitIframeError extends TapKitError {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "TapKitIframeError";
+    this.code = options?.code ?? "ERR_IFRAME";
+  }
+  static fromPossibleFrameSafeError(error) {
+    if (error instanceof _TapKitIframeError) {
+      return error;
+    }
+    if (error && typeof error === "object" && TAP_ERROR_MARKER in error && error[TAP_ERROR_MARKER] === "TapKitIframeError") {
+      const err = new _TapKitIframeError(error.message, {
+        code: error.code
+      });
+      err.stack = error.stack;
+      return err;
+    }
+    return null;
+  }
+};
+
+export { TapKitInitializationError as InitializationError, TAP_ERROR_MARKER, TapKitConfigurationError, TapKitError, TapKitIframeError, TapKitInitializationError, TapKitLoaderError, TapKitMessageError };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../index.ts"],"names":[],"mappings":";;;;;AA4JO,IAAM,gBAAA,GAAmB;AAWzB,IAAM,WAAA,GAAN,MAAM,YAAA,SAAoB,KAAA,CAAM;AAAA,EAIrC,WAAA,CAAY,SAAiB,OAAA,EAA2B;AACtD,IAAA,KAAA,CAAM,OAAO,CAAA;AAJf,IAAA,aAAA,CAAA,IAAA,EAAS,OAAA,CAAA;AACT,IAAA,aAAA,CAAA,IAAA,EAAA,MAAA,CAAA;AAIE,IAAA,IAAA,CAAK,IAAA,GAAO,aAAA;AACZ,IAAA,IAAA,CAAK,OAAO,OAAA,EAAS,IAAA;AACrB,IAAA,IAAA,CAAK,QAAQ,OAAA,EAAS,KAAA;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO,2BAA2B,KAAA,EAAgC;AAChE,IAAA,IAAI,iBAAiB,YAAA,EAAa;AAChC,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,IACE,KAAA,IACA,OAAO,KAAA,KAAU,QAAA,IACjB,oBAAoB,KAAA,IACpB,KAAA,CAAM,gBAAgB,CAAA,KAAM,aAAA,EAC5B;AACA,MAAA,MAAM,GAAA,GAAM,IAAI,YAAA,CAAY,KAAA,CAAM,OAAA,EAAS;AAAA,QACzC,MAAM,KAAA,CAAM;AAAA,OACb,CAAA;AACD,MAAA,GAAA,CAAI,QAAQ,KAAA,CAAM,KAAA;AAClB,MAAA,OAAO,GAAA;AAAA,IACT;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AACF;AAKO,IAAM,yBAAA,GAAN,MAAM,0BAAA,SAAkC,WAAA,CAAY;AAAA,EACzD,WAAA,CAAY,SAAiB,OAAA,EAA2B;AACtD,IAAA,KAAA,CAAM,SAAS,OAAO,CAAA;AACtB,IAAA,IAAA,CAAK,IAAA,GAAO,2BAAA;AACZ,IAAA,IAAA,CAAK,IAAA,GAAO,SAAS,IAAA,IAAQ,oBAAA;AAAA,EAC/B;AAAA,EAEA,OAAgB,2BACd,KAAA,EACkC;AAClC,IAAA,IAAI,iBAAiB,0BAAA,EAA2B;AAC9C,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,IACE,KAAA,IACA,OAAO,KAAA,KAAU,QAAA,IACjB,oBAAoB,KAAA,IACpB,KAAA,CAAM,gBAAgB,CAAA,KAAM,2BAAA,EAC5B;AACA,MAAA,MAAM,GAAA,GAAM,IAAI,0BAAA,CAA0B,KAAA,CAAM,OAAA,EAAS;AAAA,QACvD,MAAM,KAAA,CAAM;AAAA,OACb,CAAA;AACD,MAAA,GAAA,CAAI,QAAQ,KAAA,CAAM,KAAA;AAClB,MAAA,OAAO,GAAA;AAAA,IACT;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AACF;AAKO,IAAM,kBAAA,GAAN,MAAM,mBAAA,SAA2B,WAAA,CAAY;AAAA,EAClD,WAAA,CAAY,SAAiB,OAAA,EAA2B;AACtD,IAAA,KAAA,CAAM,SAAS,OAAO,CAAA;AACtB,IAAA,IAAA,CAAK,IAAA,GAAO,oBAAA;AACZ,IAAA,IAAA,CAAK,IAAA,GAAO,SAAS,IAAA,IAAQ,aAAA;AAAA,EAC/B;AAAA,EAEA,OAAgB,2BACd,KAAA,EAC2B;AAC3B,IAAA,IAAI,iBAAiB,mBAAA,EAAoB;AACvC,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,IACE,KAAA,IACA,OAAO,KAAA,KAAU,QAAA,IACjB,oBAAoB,KAAA,IACpB,KAAA,CAAM,gBAAgB,CAAA,KAAM,oBAAA,EAC5B;AACA,MAAA,MAAM,GAAA,GAAM,IAAI,mBAAA,CAAmB,KAAA,CAAM,OAAA,EAAS;AAAA,QAChD,MAAM,KAAA,CAAM;AAAA,OACb,CAAA;AACD,MAAA,GAAA,CAAI,QAAQ,KAAA,CAAM,KAAA;AAClB,MAAA,OAAO,GAAA;AAAA,IACT;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AACF;AAKO,IAAM,wBAAA,GAAN,MAAM,yBAAA,SAAiC,WAAA,CAAY;AAAA,EACxD,WAAA,CAAY,SAAiB,OAAA,EAA2B;AACtD,IAAA,KAAA,CAAM,SAAS,OAAO,CAAA;AACtB,IAAA,IAAA,CAAK,IAAA,GAAO,0BAAA;AACZ,IAAA,IAAA,CAAK,IAAA,GAAO,SAAS,IAAA,IAAQ,mBAAA;AAAA,EAC/B;AAAA,EAEA,OAAgB,2BACd,KAAA,EACiC;AACjC,IAAA,IAAI,iBAAiB,yBAAA,EAA0B;AAC7C,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,IACE,KAAA,IACA,OAAO,KAAA,KAAU,QAAA,IACjB,oBAAoB,KAAA,IACpB,KAAA,CAAM,gBAAgB,CAAA,KAAM,0BAAA,EAC5B;AACA,MAAA,MAAM,GAAA,GAAM,IAAI,yBAAA,CAAyB,KAAA,CAAM,OAAA,EAAS;AAAA,QACtD,MAAM,KAAA,CAAM;AAAA,OACb,CAAA;AACD,MAAA,GAAA,CAAI,QAAQ,KAAA,CAAM,KAAA;AAClB,MAAA,OAAO,GAAA;AAAA,IACT;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AACF;AAKO,IAAM,iBAAA,GAAN,MAAM,kBAAA,SAA0B,WAAA,CAAY;AAAA,EACjD,WAAA,CAAY,SAAiB,OAAA,EAA2B;AACtD,IAAA,KAAA,CAAM,SAAS,OAAO,CAAA;AACtB,IAAA,IAAA,CAAK,IAAA,GAAO,mBAAA;AACZ,IAAA,IAAA,CAAK,IAAA,GAAO,SAAS,IAAA,IAAQ,YAAA;AAAA,EAC/B;AAAA,EAEA,OAAgB,2BACd,KAAA,EAC0B;AAC1B,IAAA,IAAI,iBAAiB,kBAAA,EAAmB;AACtC,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,IACE,KAAA,IACA,OAAO,KAAA,KAAU,QAAA,IACjB,oBAAoB,KAAA,IACpB,KAAA,CAAM,gBAAgB,CAAA,KAAM,mBAAA,EAC5B;AACA,MAAA,MAAM,GAAA,GAAM,IAAI,kBAAA,CAAkB,KAAA,CAAM,OAAA,EAAS;AAAA,QAC/C,MAAM,KAAA,CAAM;AAAA,OACb,CAAA;AACD,MAAA,GAAA,CAAI,QAAQ,KAAA,CAAM,KAAA;AAClB,MAAA,OAAO,GAAA;AAAA,IACT;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AACF;AAKO,IAAM,iBAAA,GAAN,MAAM,kBAAA,SAA0B,WAAA,CAAY;AAAA,EACjD,WAAA,CAAY,SAAiB,OAAA,EAA2B;AACtD,IAAA,KAAA,CAAM,SAAS,OAAO,CAAA;AACtB,IAAA,IAAA,CAAK,IAAA,GAAO,mBAAA;AACZ,IAAA,IAAA,CAAK,IAAA,GAAO,SAAS,IAAA,IAAQ,YAAA;AAAA,EAC/B;AAAA,EAEA,OAAgB,2BACd,KAAA,EAC0B;AAC1B,IAAA,IAAI,iBAAiB,kBAAA,EAAmB;AACtC,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,IACE,KAAA,IACA,OAAO,KAAA,KAAU,QAAA,IACjB,oBAAoB,KAAA,IACpB,KAAA,CAAM,gBAAgB,CAAA,KAAM,mBAAA,EAC5B;AACA,MAAA,MAAM,GAAA,GAAM,IAAI,kBAAA,CAAkB,KAAA,CAAM,OAAA,EAAS;AAAA,QAC/C,MAAM,KAAA,CAAM;AAAA,OACb,CAAA;AACD,MAAA,GAAA,CAAI,QAAQ,KAAA,CAAM,KAAA;AAClB,MAAA,OAAO,GAAA;AAAA,IACT;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AACF","file":"index.js","sourcesContent":["/**\n * @coxwave/tap-kit-types\n * Shared TypeScript types for TapKit SDK packages\n *\n * This package serves as the single source of truth for all TapKit types,\n * used by both @coxwave/tap-sdk (npm wrapper) and @coxwave/tap-kit-core (CDN implementation).\n */\n\n// ==================== Re-exports from tap-messages ====================\nimport type {\n  AlarmMessageInstanceType,\n  AlarmType,\n} from \"@coxwave/tap-messages\";\n\nexport type { AlarmMessageInstanceType, AlarmType };\n\n// ==================== Core Configuration Types ====================\n\n/**\n * SDK Configuration\n */\nexport type TapKitConfig = {\n  apiKey: string;\n};\n\n/**\n * SDK Initialization Parameters\n */\nexport type TapKitInitParams = {\n  buttonId: string;\n  course: Course;\n  container?: ContainerStyle;\n};\n\n/**\n * Course Information\n */\nexport type Course = {\n  userId: string;\n  courseId: string;\n  clipId: string;\n  clipPlayHead?: number;\n};\n\n// ==================== Styling Types ====================\n\n/**\n * Container Styling\n */\nexport type ContainerStyle = {\n  position?: PositionType;\n  width?: string;\n  height?: string;\n  borderRadius?: string;\n};\n\nexport type PositionType = {\n  top?: string;\n  left?: string;\n  right?: string;\n  bottom?: string;\n};\n\n/**\n * Flattened container styles (backward compatibility)\n */\nexport type CustomStyles = ContainerStyle;\n\n// ==================== Event Types ====================\n\n/**\n * Timeline seek parameters\n */\nexport type SeekTimelineParamsType = {\n  clipId: string;\n  clipPlayHead: number;\n};\n\n/**\n * Shortcut Key Configuration\n */\nexport type ShortcutKeyPropertiesType = {\n  key: string;\n  modifier: \"ctrlKey\" | \"altKey\" | \"shiftKey\" | \"metaKey\" | \"\";\n};\n\n/**\n * Container Visibility State\n */\nexport type ContainerVisibility = \"open\" | \"closed\";\n\n// ==================== SDK Instance Interfaces ====================\n\n/**\n * Pop-up information passed to onPopUpOpen event handler\n */\nexport interface PopUpInfo {\n  html: string;\n  [key: string]: unknown;\n}\n\n/**\n * Base TapKit instance interface\n * Shared properties and methods between core and wrapper\n */\nexport interface TapKitBaseInstance {\n  events: {\n    seekTimeline: (params: SeekTimelineParamsType) => Promise<void>;\n    onTimelineSeek: (\n      callback: (clipPlayHead: number, clipId: string) => void,\n    ) => () => void;\n    onChatInitiated: (handler: () => void) => () => void;\n    onChatOpened: (handler: () => void) => () => void;\n    onChatClosed: (handler: () => void) => () => void;\n    onAlarmFadeIn: (\n      handler: (messageInfo: AlarmMessageInstanceType) => void,\n    ) => () => void;\n    onPopUpOpen: (handler: (popUpInfo: PopUpInfo) => void) => () => void;\n    onPdfOpen: (handler: () => void) => () => void;\n    onPdfClose: (handler: () => void) => () => void;\n  };\n  isOpen: boolean;\n  isInitialized: boolean;\n  ready: Promise<void>;\n  init(params: TapKitInitParams): Promise<void>;\n  destroy(): void;\n}\n\n/**\n * TapKit instance type from tap-kit-core\n * This matches the actual TapKit class exported from @coxwave/tap-kit-core\n * Exported for advanced use cases (e.g., when using window.TapKit directly)\n *\n * Currently identical to TapKitBaseInstance, but kept as separate type\n * for future extensibility and semantic clarity\n */\nexport interface TapKitCoreInstance extends TapKitBaseInstance {}\n\n/**\n * Public TapKit instance interface\n * This is what users interact with when using the SDK\n */\nexport interface TapKitInstance extends TapKitBaseInstance {\n  // Wrapper-specific method\n  getVersion(): string;\n}\n\n/**\n * TapKit constructor type\n */\nexport type TapKitConstructor = new (\n  config: TapKitConfig,\n) => TapKitCoreInstance;\n\n// ==================== Error Classes ====================\n\nexport const TAP_ERROR_MARKER = \"__tap_sdk_error__\";\n\nexport interface TapErrorOptions {\n  code?: string;\n  cause?: Error;\n}\n\n/**\n * Base error class for all TapKit errors\n * Supports serialization across iframe boundaries\n */\nexport class TapKitError extends Error {\n  override cause: Error | undefined;\n  code: string | undefined;\n\n  constructor(message: string, options?: TapErrorOptions) {\n    super(message);\n    this.name = \"TapKitError\";\n    this.code = options?.code;\n    this.cause = options?.cause;\n  }\n\n  /**\n   * Restore error from postMessage serialization\n   */\n  static fromPossibleFrameSafeError(error: any): TapKitError | null {\n    if (error instanceof TapKitError) {\n      return error;\n    }\n    if (\n      error &&\n      typeof error === \"object\" &&\n      TAP_ERROR_MARKER in error &&\n      error[TAP_ERROR_MARKER] === \"TapKitError\"\n    ) {\n      const err = new TapKitError(error.message, {\n        code: error.code,\n      });\n      err.stack = error.stack;\n      return err;\n    }\n    return null;\n  }\n}\n\n/**\n * Error thrown when SDK initialization fails\n */\nexport class TapKitInitializationError extends TapKitError {\n  constructor(message: string, options?: TapErrorOptions) {\n    super(message, options);\n    this.name = \"TapKitInitializationError\";\n    this.code = options?.code ?? \"ERR_INITIALIZATION\";\n  }\n\n  static override fromPossibleFrameSafeError(\n    error: any\n  ): TapKitInitializationError | null {\n    if (error instanceof TapKitInitializationError) {\n      return error;\n    }\n    if (\n      error &&\n      typeof error === \"object\" &&\n      TAP_ERROR_MARKER in error &&\n      error[TAP_ERROR_MARKER] === \"TapKitInitializationError\"\n    ) {\n      const err = new TapKitInitializationError(error.message, {\n        code: error.code,\n      });\n      err.stack = error.stack;\n      return err;\n    }\n    return null;\n  }\n}\n\n/**\n * Error thrown when message communication fails\n */\nexport class TapKitMessageError extends TapKitError {\n  constructor(message: string, options?: TapErrorOptions) {\n    super(message, options);\n    this.name = \"TapKitMessageError\";\n    this.code = options?.code ?? \"ERR_MESSAGE\";\n  }\n\n  static override fromPossibleFrameSafeError(\n    error: any\n  ): TapKitMessageError | null {\n    if (error instanceof TapKitMessageError) {\n      return error;\n    }\n    if (\n      error &&\n      typeof error === \"object\" &&\n      TAP_ERROR_MARKER in error &&\n      error[TAP_ERROR_MARKER] === \"TapKitMessageError\"\n    ) {\n      const err = new TapKitMessageError(error.message, {\n        code: error.code,\n      });\n      err.stack = error.stack;\n      return err;\n    }\n    return null;\n  }\n}\n\n/**\n * Error thrown when configuration is invalid\n */\nexport class TapKitConfigurationError extends TapKitError {\n  constructor(message: string, options?: TapErrorOptions) {\n    super(message, options);\n    this.name = \"TapKitConfigurationError\";\n    this.code = options?.code ?? \"ERR_CONFIGURATION\";\n  }\n\n  static override fromPossibleFrameSafeError(\n    error: any\n  ): TapKitConfigurationError | null {\n    if (error instanceof TapKitConfigurationError) {\n      return error;\n    }\n    if (\n      error &&\n      typeof error === \"object\" &&\n      TAP_ERROR_MARKER in error &&\n      error[TAP_ERROR_MARKER] === \"TapKitConfigurationError\"\n    ) {\n      const err = new TapKitConfigurationError(error.message, {\n        code: error.code,\n      });\n      err.stack = error.stack;\n      return err;\n    }\n    return null;\n  }\n}\n\n/**\n * Error thrown when loader fails to fetch or load resources\n */\nexport class TapKitLoaderError extends TapKitError {\n  constructor(message: string, options?: TapErrorOptions) {\n    super(message, options);\n    this.name = \"TapKitLoaderError\";\n    this.code = options?.code ?? \"ERR_LOADER\";\n  }\n\n  static override fromPossibleFrameSafeError(\n    error: any\n  ): TapKitLoaderError | null {\n    if (error instanceof TapKitLoaderError) {\n      return error;\n    }\n    if (\n      error &&\n      typeof error === \"object\" &&\n      TAP_ERROR_MARKER in error &&\n      error[TAP_ERROR_MARKER] === \"TapKitLoaderError\"\n    ) {\n      const err = new TapKitLoaderError(error.message, {\n        code: error.code,\n      });\n      err.stack = error.stack;\n      return err;\n    }\n    return null;\n  }\n}\n\n/**\n * Error thrown when iframe operations fail\n */\nexport class TapKitIframeError extends TapKitError {\n  constructor(message: string, options?: TapErrorOptions) {\n    super(message, options);\n    this.name = \"TapKitIframeError\";\n    this.code = options?.code ?? \"ERR_IFRAME\";\n  }\n\n  static override fromPossibleFrameSafeError(\n    error: any\n  ): TapKitIframeError | null {\n    if (error instanceof TapKitIframeError) {\n      return error;\n    }\n    if (\n      error &&\n      typeof error === \"object\" &&\n      TAP_ERROR_MARKER in error &&\n      error[TAP_ERROR_MARKER] === \"TapKitIframeError\"\n    ) {\n      const err = new TapKitIframeError(error.message, {\n        code: error.code,\n      });\n      err.stack = error.stack;\n      return err;\n    }\n    return null;\n  }\n}\n\n// Backward compatibility alias\nexport { TapKitInitializationError as InitializationError };\n"]}

package/index.ts

@@ -0,0 +1,363 @@
+/**
+ * @coxwave/tap-kit-types
+ * Shared TypeScript types for TapKit SDK packages
+ *
+ * This package serves as the single source of truth for all TapKit types,
+ * used by both @coxwave/tap-sdk (npm wrapper) and @coxwave/tap-kit-core (CDN implementation).
+ */
+
+// ==================== Re-exports from tap-messages ====================
+import type {
+  AlarmMessageInstanceType,
+  AlarmType,
+} from "@coxwave/tap-messages";
+
+export type { AlarmMessageInstanceType, AlarmType };
+
+// ==================== Core Configuration Types ====================
+
+/**
+ * SDK Configuration
+ */
+export type TapKitConfig = {
+  apiKey: string;
+};
+
+/**
+ * SDK Initialization Parameters
+ */
+export type TapKitInitParams = {
+  buttonId: string;
+  course: Course;
+  container?: ContainerStyle;
+};
+
+/**
+ * Course Information
+ */
+export type Course = {
+  userId: string;
+  courseId: string;
+  clipId: string;
+  clipPlayHead?: number;
+};
+
+// ==================== Styling Types ====================
+
+/**
+ * Container Styling
+ */
+export type ContainerStyle = {
+  position?: PositionType;
+  width?: string;
+  height?: string;
+  borderRadius?: string;
+};
+
+export type PositionType = {
+  top?: string;
+  left?: string;
+  right?: string;
+  bottom?: string;
+};
+
+/**
+ * Flattened container styles (backward compatibility)
+ */
+export type CustomStyles = ContainerStyle;
+
+// ==================== Event Types ====================
+
+/**
+ * Timeline seek parameters
+ */
+export type SeekTimelineParamsType = {
+  clipId: string;
+  clipPlayHead: number;
+};
+
+/**
+ * Shortcut Key Configuration
+ */
+export type ShortcutKeyPropertiesType = {
+  key: string;
+  modifier: "ctrlKey" | "altKey" | "shiftKey" | "metaKey" | "";
+};
+
+/**
+ * Container Visibility State
+ */
+export type ContainerVisibility = "open" | "closed";
+
+// ==================== SDK Instance Interfaces ====================
+
+/**
+ * Pop-up information passed to onPopUpOpen event handler
+ */
+export interface PopUpInfo {
+  html: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Base TapKit instance interface
+ * Shared properties and methods between core and wrapper
+ */
+export interface TapKitBaseInstance {
+  events: {
+    seekTimeline: (params: SeekTimelineParamsType) => Promise<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: PopUpInfo) => void) => () => void;
+    onPdfOpen: (handler: () => void) => () => void;
+    onPdfClose: (handler: () => void) => () => void;
+  };
+  isOpen: boolean;
+  isInitialized: boolean;
+  ready: Promise<void>;
+  init(params: TapKitInitParams): Promise<void>;
+  destroy(): void;
+}
+
+/**
+ * TapKit instance type from tap-kit-core
+ * This matches the actual TapKit class exported from @coxwave/tap-kit-core
+ * Exported for advanced use cases (e.g., when using window.TapKit directly)
+ *
+ * Currently identical to TapKitBaseInstance, but kept as separate type
+ * for future extensibility and semantic clarity
+ */
+export interface TapKitCoreInstance extends TapKitBaseInstance {}
+
+/**
+ * Public TapKit instance interface
+ * This is what users interact with when using the SDK
+ */
+export interface TapKitInstance extends TapKitBaseInstance {
+  // Wrapper-specific method
+  getVersion(): string;
+}
+
+/**
+ * TapKit constructor type
+ */
+export type TapKitConstructor = new (
+  config: TapKitConfig,
+) => TapKitCoreInstance;
+
+// ==================== Error Classes ====================
+
+export const TAP_ERROR_MARKER = "__tap_sdk_error__";
+
+export interface TapErrorOptions {
+  code?: string;
+  cause?: Error;
+}
+
+/**
+ * Base error class for all TapKit errors
+ * Supports serialization across iframe boundaries
+ */
+export class TapKitError extends Error {
+  override cause: Error | undefined;
+  code: string | undefined;
+
+  constructor(message: string, options?: TapErrorOptions) {
+    super(message);
+    this.name = "TapKitError";
+    this.code = options?.code;
+    this.cause = options?.cause;
+  }
+
+  /**
+   * Restore error from postMessage serialization
+   */
+  static fromPossibleFrameSafeError(error: any): TapKitError | null {
+    if (error instanceof TapKitError) {
+      return error;
+    }
+    if (
+      error &&
+      typeof error === "object" &&
+      TAP_ERROR_MARKER in error &&
+      error[TAP_ERROR_MARKER] === "TapKitError"
+    ) {
+      const err = new TapKitError(error.message, {
+        code: error.code,
+      });
+      err.stack = error.stack;
+      return err;
+    }
+    return null;
+  }
+}
+
+/**
+ * Error thrown when SDK initialization fails
+ */
+export class TapKitInitializationError extends TapKitError {
+  constructor(message: string, options?: TapErrorOptions) {
+    super(message, options);
+    this.name = "TapKitInitializationError";
+    this.code = options?.code ?? "ERR_INITIALIZATION";
+  }
+
+  static override fromPossibleFrameSafeError(
+    error: any
+  ): TapKitInitializationError | null {
+    if (error instanceof TapKitInitializationError) {
+      return error;
+    }
+    if (
+      error &&
+      typeof error === "object" &&
+      TAP_ERROR_MARKER in error &&
+      error[TAP_ERROR_MARKER] === "TapKitInitializationError"
+    ) {
+      const err = new TapKitInitializationError(error.message, {
+        code: error.code,
+      });
+      err.stack = error.stack;
+      return err;
+    }
+    return null;
+  }
+}
+
+/**
+ * Error thrown when message communication fails
+ */
+export class TapKitMessageError extends TapKitError {
+  constructor(message: string, options?: TapErrorOptions) {
+    super(message, options);
+    this.name = "TapKitMessageError";
+    this.code = options?.code ?? "ERR_MESSAGE";
+  }
+
+  static override fromPossibleFrameSafeError(
+    error: any
+  ): TapKitMessageError | null {
+    if (error instanceof TapKitMessageError) {
+      return error;
+    }
+    if (
+      error &&
+      typeof error === "object" &&
+      TAP_ERROR_MARKER in error &&
+      error[TAP_ERROR_MARKER] === "TapKitMessageError"
+    ) {
+      const err = new TapKitMessageError(error.message, {
+        code: error.code,
+      });
+      err.stack = error.stack;
+      return err;
+    }
+    return null;
+  }
+}
+
+/**
+ * Error thrown when configuration is invalid
+ */
+export class TapKitConfigurationError extends TapKitError {
+  constructor(message: string, options?: TapErrorOptions) {
+    super(message, options);
+    this.name = "TapKitConfigurationError";
+    this.code = options?.code ?? "ERR_CONFIGURATION";
+  }
+
+  static override fromPossibleFrameSafeError(
+    error: any
+  ): TapKitConfigurationError | null {
+    if (error instanceof TapKitConfigurationError) {
+      return error;
+    }
+    if (
+      error &&
+      typeof error === "object" &&
+      TAP_ERROR_MARKER in error &&
+      error[TAP_ERROR_MARKER] === "TapKitConfigurationError"
+    ) {
+      const err = new TapKitConfigurationError(error.message, {
+        code: error.code,
+      });
+      err.stack = error.stack;
+      return err;
+    }
+    return null;
+  }
+}
+
+/**
+ * Error thrown when loader fails to fetch or load resources
+ */
+export class TapKitLoaderError extends TapKitError {
+  constructor(message: string, options?: TapErrorOptions) {
+    super(message, options);
+    this.name = "TapKitLoaderError";
+    this.code = options?.code ?? "ERR_LOADER";
+  }
+
+  static override fromPossibleFrameSafeError(
+    error: any
+  ): TapKitLoaderError | null {
+    if (error instanceof TapKitLoaderError) {
+      return error;
+    }
+    if (
+      error &&
+      typeof error === "object" &&
+      TAP_ERROR_MARKER in error &&
+      error[TAP_ERROR_MARKER] === "TapKitLoaderError"
+    ) {
+      const err = new TapKitLoaderError(error.message, {
+        code: error.code,
+      });
+      err.stack = error.stack;
+      return err;
+    }
+    return null;
+  }
+}
+
+/**
+ * Error thrown when iframe operations fail
+ */
+export class TapKitIframeError extends TapKitError {
+  constructor(message: string, options?: TapErrorOptions) {
+    super(message, options);
+    this.name = "TapKitIframeError";
+    this.code = options?.code ?? "ERR_IFRAME";
+  }
+
+  static override fromPossibleFrameSafeError(
+    error: any
+  ): TapKitIframeError | null {
+    if (error instanceof TapKitIframeError) {
+      return error;
+    }
+    if (
+      error &&
+      typeof error === "object" &&
+      TAP_ERROR_MARKER in error &&
+      error[TAP_ERROR_MARKER] === "TapKitIframeError"
+    ) {
+      const err = new TapKitIframeError(error.message, {
+        code: error.code,
+      });
+      err.stack = error.stack;
+      return err;
+    }
+    return null;
+  }
+}
+
+// Backward compatibility alias
+export { TapKitInitializationError as InitializationError };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@coxwave/tap-kit-types",
+  "version": "0.0.34",
+  "type": "module",
+  "description": "Shared TypeScript types for TapKit SDK packages",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint .",
+    "publish:npm": "./scripts/publish.sh"
+  },
+  "keywords": [
+    "tapkit",
+    "types",
+    "typescript"
+  ],
+  "author": "",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "index.ts"
+  ],
+  "peerDependencies": {
+    "@coxwave/tap-messages": "^0.0.1"
+  },
+  "devDependencies": {
+    "@coxwave/config-eslint": "workspace:*",
+    "@coxwave/config-typescript": "workspace:*",
+    "@coxwave/tap-messages": "workspace:*",
+    "tsup": "^8.5.0"
+  }
+}