@coxwave/tap-sdk 0.0.3 → 0.0.5

package/README.md

@@ -1,390 +1,170 @@
-# ax-sdk-chatbot
+# @coxwave/tap-sdk
 
-## version: 1.1.0
+A vanilla JavaScript SDK for embedding AI chat widgets into web applications with seamless iframe communication.
 
-## 📚 Table of Contents
-
-- [Installation](#installation)
-- [Quick Use](#quick-use)
-- [Types](#types)
-- [Legacy](#legacy)
-- [License](#license)
-
-## installation
-
-### npm
+## Installation
 
 ```bash
-npm i ax-sdk-chatbot
+npm install @coxwave/tap-sdk
 ```
 
-### yarn
-
-```bash
-yarn add ax-sdk-chatbot
-```
-
-## Quick Use
-
-### vite
-
-#### Use In Root
+## Quick Start
 
-```ts
--main.tsx;
-
-import { createRoot } from "react-dom/client";
-
-import TapSDK from "ax-sdk-chatbot";
-
-import App from "./App.tsx";
-
-import "./index.css";
+```javascript
+import TapSDK from "@coxwave/tap-sdk";
 
 const sdk = new TapSDK({
-  hostClientUrl: import.meta.env.VITE_CLIENT_URL, // your client url (if you use localhost, your client url is http://localhost:5173)
-  pluginKey: import.meta.env.VITE_FIRSTBRAIN_PLUGIN_KEY,
-  isProd: false,
+  pluginKey: "your-plugin-key",
+  isProd: true,
 });
 
-createRoot(document.getElementById("root")!).render(<App />);
-
-sdk.initChat({
+await sdk.initChat({
   chatApiParams: {
-    userId: "user_id",
-    courseId: "course_id",
-    courseName: "course_name",
-    courseCategory: "course_category",
-    courseSubCategory: "course_sub_category",
-    clipId: "clip_id",
-    clipPlayHead:  clip_play_head_number,
-  },
-  shortcutKey: {
-    openChat: { key: "/", modifier: "" },
-    sendChat: { key: "Enter", modifier: "" },
-  },
-  customStyles: {
-    floatingButton: {
-      isInElement: true,
-      parentElementId: "root-button", // <------ here is your Floating Button parent element Id
-    },
+    userId: "user-123",
+    courseId: "course-456",
+    courseName: "JavaScript Fundamentals",
+    courseCategory: "Programming",
+    courseSubCategory: "Frontend",
+    clipId: null,
+    clipPlayHead: null,
   },
 });
+```
 
--App.tsx;
-
-import { useEffect, useState } from "react";
-
-import "./App.css";
+## Features
 
-import TapSDK from "coxwave-sdk";
+- 🎯 **Iframe Communication** - Secure cross-origin messaging with handshake protocol
+- 🎨 **Customizable UI** - Floating button, chat body, and popup styling
+- 📊 **Event System** - Timeline sync, chat events, alarms, and PDF integration
+- 🔔 **Smart Notifications** - Auto-fading alarm system with custom styling
+- 📱 **Responsive Design** - Mobile-friendly with automatic positioning
+- 🚀 **Zero Dependencies** - Self-contained with tree-shaking optimization
 
-function App({ sdk }: { sdk: TapSDK }) {
-  const [clipPlayHead, setClipPlayHead] = useState(0);
+## API Reference
 
-  useEffect(() => {
-    const interval = setInterval(() => {
-      setClipPlayHead((prev) => prev + 5);
-    }, 1000);
+### Constructor
 
-    return () => clearInterval(interval);
-  }, []);
-
-  useEffect(() => {
-    sdk.postChatInfo({
-      clipId: "58767",
-      clipPlayHead,
-    });
-  }, [clipPlayHead]);
-
-  return (
-    <>
-      <div id="root-button">{Your Floating Button styles Element}</div> // <------ This is your floating button parent element. It must have the same ID as parentElementId.
-    </>
-  );
-}
-
-export default App;
+```javascript
+new TapSDK(options);
 ```
 
-#### Use Custom Hook (with useEffect)
+**Options:**
 
-- Test.tsx (can use any component)
+- `pluginKey` (string) - Your unique plugin identifier
+- `isProd` (boolean) - Production mode flag (default: false)
+- `isLocal` (boolean) - Local development flag (default: false)
 
-```ts
-import { useEffect, useState } from "react";
+### Methods
 
-import TapSDK from "ax-sdk-chatbot";
+#### `initChat(config)`
 
-import BotImage from "./assets/quick-menu.png";
-
-const sdk = new TapSDK({
-  hostClientUrl: import.meta.env.VITE_CLIENT_URL,
-  pluginKey: import.meta.env.VITE_FIRSTBRAIN_PLUGIN_KEY,
-  isProd: import.meta.env.VITE_IS_PROD === "true",
+```javascript
+await sdk.initChat({
+  chatApiParams: {
+    userId: string,
+    courseId: string | null,
+    courseName: string,
+    courseCategory: string,
+    courseSubCategory: string,
+    clipId: string | null,
+    clipPlayHead: number | null
+  },
+  customStyles?: {
+    floatingButton?: {
+      isInElement?: boolean,
+      parentElementId?: string,
+      style?: Partial<CSSStyleDeclaration>
+    },
+    chatBody?: {
+      position?: { top?: string, right?: string, left?: string, bottom?: string },
+      width?: string,
+      height?: string,
+      borderRadius?: string
+    }
+  }
 });
+```
 
+#### `seekTimeline(params)`
 
-function Test() {
-  const [clipPlayHead, setClipPlayHead] = useState(0);
-
-  useEffect(() => {
-    sdk.initChat({
-      chatApiParams: {
-        userId: "user_id",
-        courseId: "course_id",
-        courseName: "course_name",
-        courseCategory: "course_category",
-        courseSubCategory: "course_sub_category",
-        clipId: "clip_id",
-        clipPlayHead: clip_play_head_number,
-      },
-      customStyles: {
-        floatingButton: {
-          isInElement: true,
-          parentElementId: "root-button",
-        },
-      },
-    });
-
-    return () => {
-      sdk.removeChat(); // this is sdk cleanup function
-    };
-  }, []);
-
-  useEffect(() => {
-    const interval = setInterval(() => {
-      setClipPlayHead((prev) => prev + 5);
-    }, 1000);
-
-    return () => clearInterval(interval);
-  }, []);
-
-  useEffect(() => {
-    sdk.postChatInfo({
-      clipId: "58767",
-      clipPlayHead,
-    });
-  }, [clipPlayHead]);
-
-  return (
-    <S.LayoutContainer $isWhiteBack={true}>
-      <S.ContentBox>
-        <S.RootButton id="root-button">
-          <S.BotImage src={BotImage} />
-          <S.Text>AI 튜터</S.Text>
-        </S.RootButton>
-      </S.ContentBox>
-    </S.LayoutContainer>
-  );
-}
-
-export default Test;
+```javascript
+sdk.seekTimeline({
+  clipId: "clip-123",
+  clipPlayHead: 150.5,
+});
+```
 
-const S = {
-  ~
-} // your styles (this example is for styled-components)
+#### `removeChat()`
 
+```javascript
+sdk.removeChat();
 ```
 
-### Next.js
-
-- page.tsx
+### Event Listeners
 
-```ts
-import Sdk from "./Sdk";
+```javascript
+// Timeline seek events
+sdk.events.onTimelineSeek((clipPlayHead, clipId) => {
+  console.log(`Seek to ${clipPlayHead}s in ${clipId}`);
+});
 
-export default function Home() {
-  return (
-    <Sdk />
-  );
-}
+// Chat state events
+sdk.events.onChatOpened(() => console.log("Chat opened"));
+sdk.events.onChatClosed(() => console.log("Chat closed"));
 
+// Notification events
+sdk.events.onAlarmFadeIn((messageInfo) => {
+  console.log("Alarm notification:", messageInfo);
+});
 ```
 
-- Sdk.tsx
+## Framework Integration
 
-```ts
-"use client"; // if you use this sdk in Next.js, you must use this
+### React
 
+```jsx
 import { useEffect, useRef } from "react";
+import TapSDK from "@coxwave/tap-sdk";
 
-import TapSDK from "ax-sdk-chatbot";
-
-const clientUrl = process.env.NEXT_PUBLIC_HOST_CLIENT_URL; // your client url (if you use localhost, your client url is http://localhost:3000)
-const pluginKey = process.env.NEXT_PUBLIC_COXWAVE_PLUGIN_KEY;
-
-if (!clientUrl) {
-  throw new Error("NEXT_PUBLIC_COXWAVE_CLIENT_URL is not set");
-}
-
-if (!pluginKey) {
-  throw new Error("NEXT_PUBLIC_COXWAVE_PLUGIN_KEY is not set");
-}
-
-function Sdk() {
-  const iframeRef = useRef<HTMLDivElement>(null);
+function ChatWidget({ userId, courseId }) {
+  const sdkRef = useRef(null);
 
   useEffect(() => {
-    if (!clientUrl || !pluginKey) return;
-
-    const TapSDKInstance = new TapSDK({
-      hostClientUrl: clientUrl,
-      pluginKey: pluginKey,
-    });
-
-    const init = async () => {
-      try {
-        await TapSDKInstance.initChat({
-          chatApiParams: {
-            userId: "user_id",
-            courseId: "course_id",
-            courseName: "course_name",
-            courseCategory: "course_category",
-            courseSubCategory: "course_sub_category",
-            clipId: "clip_id",
-            clipPlayHead: clip_play_head_number,
-          },
-          customStyles: {
-            floatingButton: {
-              isInElement: true,
-              parentElementId: "root-button", // <------ here is your Floating Button parent element Id
-            },
-          },
-        });
-      } catch (err) {
-        console.error("SDK initChat 실패:", err);
-      }
+    const initSDK = async () => {
+      sdkRef.current = new TapSDK({
+        pluginKey: process.env.REACT_APP_TAP_PLUGIN_KEY,
+        isProd: process.env.NODE_ENV === "production",
+      });
+
+      await sdkRef.current.initChat({
+        chatApiParams: { userId, courseId /* ... */ },
+      });
     };
 
-    init(); // 즉시 실행
+    initSDK();
+    return () => sdkRef.current?.removeChat();
+  }, [userId, courseId]);
 
-    return () => {
-      TapSDKInstance.removeChat();
-    };
-  }, [clientUrl]);
-
-  return (
-    <div
-      ref={iframeRef}
-      id="root-button" // <------ This is your floating button parent element. It must have the same ID as parentElementId.
-      style={{
-        width: "50px",
-        height: "50px",
-        backgroundColor: "red",
-        cursor: "pointer",
-      }}
-    >
-      <button>Open Chat</button>
-    </div>
-  );
+  return <div id="chat-container" />;
 }
-
-export default Sdk;
-```
-
-## Types
-
-### SDK Class
-
-```ts
-const TapSDKInstance = new TapSDK({
-  hostClientUrl: "~",
-  pluginKey: "~",
-});
-
-type TapSDKType = {
-  hostClientUrl: string;
-  pluginKey: string;
-  isProd?: boolean;
-};
 ```
 
-### initChat Method
-
-```ts
-async initChat({
-    chatApiParams,
-    customStyles,
-    shortcutKey,
-  }: {
-    chatApiParams: ChatApiParamsType;
-    customStyles?: CustomStylesType;
-    shortcutKey?: ShortcutKeyType;
-  })
-
-type ChatApiParamsType = {
-  userId: string;
-  courseId: string;
-  courseName: string;
-  courseCategory: string;
-  courseSubCategory: string;
-  clipId: string | null;
-  clipPlayHead: number | null;
-};
-
-type CustomStylesType = {
-  floatingButton?: FloatingButtonType;
-  chatBody?: ChatBodyType;
-};
-
-type ShortcutKeyType = {
-  openChat: ShortcutKeyPropertiesType;
-  sendChat: ShortcutKeyPropertiesType;
-};
-
-type FloatingButtonType = {
-  isInElement?: boolean;
-  parentElementId?: string;
-  style?: Partial<CSSStyleDeclaration>;
-};
-
-type ChatBodyType = {
-  position?: PositionType;
-  width?: string;
-  height?: string;
-};
-
-type PositionType = {
-  top?: string;
-  left?: string;
-  right?: string;
-  bottom?: string;
-};
-
-type ShortcutKeyPropertiesType = {
-  key: string;
-  modifier: "ctrlKey" | "altKey" | "shiftKey" | "metaKey" | "";
-};
+## Build Formats
 
-```
-
-### postChatInfo Method
-
-```ts
-  postChatInfo({
-    clipId,
-    clipPlayHead,
-  }: {
-    clipId: string;
-    clipPlayHead: number;
-  })
-```
-
-- you must use postChatInfo method after initChat method
-
-### removeChat Method
-
-```ts
-removeChat();
-```
+- **ESM**: `dist/index.mjs` - Modern ES modules
+- **CJS**: `dist/index.js` - CommonJS for Node.js
+- **IIFE**: `dist/index.global.js` - Browser global variable
+- **Types**: `dist/index.d.ts` - TypeScript declarations
 
-## legacy
+## Browser Support
 
-Ver 0.x.x: https://www.npmjs.com/package/ax-sdk-chatbot/v/0.3.7
+- Chrome 60+
+- Firefox 60+
+- Safari 12+
+- Edge 79+
 
-## license
+## License
 
-[MIT](https://opensource.org/licenses/MIT)
+MIT
 
 Copyright (c) 2025-present, Coxwave

package/dist/index.d.cts

@@ -40,7 +40,7 @@ declare class TapIframeBridge extends Messenger<ToTapMessage, FromTapMessage> {
         hostClientUrl: string;
         pluginKey: string;
     });
-    protected isValidOrigin(event: MessageEvent): boolean;
+    protected isValidOrigin(_event: MessageEvent): boolean;
     protected getMessageTarget(): Window | null;
     protected getTargetOrigin(): string;
     renderIframe({ chatBody, isProd, isLocal, }: {
@@ -50,7 +50,7 @@ declare class TapIframeBridge extends Messenger<ToTapMessage, FromTapMessage> {
     }): Promise<HTMLIFrameElement>;
     hasIframe(): boolean;
     removeIframe(): void;
-    get postToTap(): (message: ToTapMessage) => boolean;
+    get postToTap(): (() => void) | ((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, {

package/dist/index.d.ts

@@ -40,7 +40,7 @@ declare class TapIframeBridge extends Messenger<ToTapMessage, FromTapMessage> {
         hostClientUrl: string;
         pluginKey: string;
     });
-    protected isValidOrigin(event: MessageEvent): boolean;
+    protected isValidOrigin(_event: MessageEvent): boolean;
     protected getMessageTarget(): Window | null;
     protected getTargetOrigin(): string;
     renderIframe({ chatBody, isProd, isLocal, }: {
@@ -50,7 +50,7 @@ declare class TapIframeBridge extends Messenger<ToTapMessage, FromTapMessage> {
     }): Promise<HTMLIFrameElement>;
     hasIframe(): boolean;
     removeIframe(): void;
-    get postToTap(): (message: ToTapMessage) => boolean;
+    get postToTap(): (() => void) | ((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, {