kit.apiKey = 'your-api-key';  // O
// <tap-kit api-key="..."> Don't use

kit.userId = 'user-123';
// or <tap-kit user-id="user-123">

kit.courseId = 'course-456';

kit.clipId = 'clip-789';

kit.sectionId = 'section-456';
// or <tap-kit section-id="section-456">

kit.clipPlayHead = 100;

kit.externalReferenceId = 'ext-abc-123';
// or <tap-kit external-reference-id="ext-abc-123">

kit.userInputCode = 'ext-data-123';
// or <tap-kit user-input-code="ext-data-123">

kit.rowDataForCodeEditor = {
  language_id_nm: 'C++ (GCC 9.2.0)',
  d_test_case: '<p>...</p>',
  content: 'Problem description...',
  io_example: 'input: 1234 / output: 4S 0B',
  restriction: '1s / 256MB',
  // additional fields (grcode, sol_code, etc.) are ignored
};

kit.language = 'en';
// or <tap-kit language="en">

kit.mode = 'floating';
// or <tap-kit mode="sidebar">

kit.allowLayoutToggle = false;  // Hide layout toggle button

// HTMLVideoElement
kit.videoTarget = document.querySelector('video');

// VideoPlayerAdapter (YouTube, Vimeo, etc.)
kit.videoTarget = {
  getCurrentTime: () => player.getCurrentTime(),
  setCurrentTime: (time, clipId) => player.seekTo(time),  // clipId for cross-clip seeking (optional)
};

console.log(TapKit.version);  // "2.1.0"

console.log(TapKit.buildEnv);  // "prod"

kit.apiUrl = 'https://tapapistaging.coxwave.link';

kit.environment = 'staging';

// ❌ Don't use
kit.root = document.getElementById('chat-container');

await kit.ready;
kit.show();

interface SetCourseParams {
  userId?: string;
  courseId: string;    // Required
  clipId: string;      // Required
  sectionId?: string;  // Optional
  clipPlayHead?: number;
}

kit.setCourse({
  courseId: 'course-999',
  clipId: 'clip-001',
  clipPlayHead: 50
});

kit.setExternalReferenceId('ext-abc-123');
kit.setExternalReferenceId(undefined); // clear

kit.setExternalReferenceData('ext-data-123');
kit.setExternalReferenceData(undefined); // clear

kit.sendContext('passage:answer:submit', {
  question: 'What is the main idea of the passage?',
  selectedOptionId: 'A',
  correctAnswer: 'B',
  isCorrect: false,
});

kit.addEventListener('tap-kit:ready', () => {
  console.log('TapKit is ready!');
});

kit.addEventListener('tap-kit:error', (e) => {
  console.error('TapKit error:', e.detail.error);
});

interface IframeRetryEvent {
  attempt: number;      // Current retry count
  error: Error;         // The error that occurred
  nextDelay: number;    // Wait time until next retry (ms)
}

kit.addEventListener('tap-kit:iframe-retry', (e) => {
  console.log(`Retrying iframe... (attempt ${e.detail.attempt}, retry in ${e.detail.nextDelay}ms)`);
  console.error('Error:', e.detail.error.message);
});

interface SeekTimelineParams {
  clipPlayHead: number;  // Position to seek (seconds)
  clipId: string;
}

kit.events.seekTimeline({ clipPlayHead: 100, clipId: 'clip-789' });

const unsubscribe = kit.events.onTimelineSeek((playHead, clipId) => {
  console.log(`Seeking to ${playHead}s: ${clipId}`);
  videoElement.currentTime = playHead;
});

// Unsubscribe
unsubscribe();

const unsubscribe = kit.events.onAlarmFadeIn((alarm) => {
  console.log('New alarm:', alarm.message);
});

interface VideoPlayerAdapter {
  getCurrentTime: () => number;
  setCurrentTime: (time: number, clipId?: string) => void;  // clipId for cross-clip seeking
}

kit.video.bind(videoElement);

// When changing courses later, new clipId is automatically used
kit.setCourse({ courseId: 'new-course', clipId: 'new-clip' });

kit.video.bind({
  getCurrentTime: () => player.getCurrentTime(),
  // clipId is optional - used for cross-clip seeking
  setCurrentTime: (time, clipId) => player.seekTo(time, true),
});

kit.video.unbind();

// npm package
import { createTapKit } from '@coxwave/tap-kit';

const tapkit = createTapKit(options);
tapkit.mount();        // Add to DOM (required)
await tapkit.ready;    // Wait for initialization
tapkit.show();         // Show chat window

import { createTapKit } from '@coxwave/tap-kit';

const tapkit = createTapKit({
  apiKey: 'your-api-key',
  userId: 'user-123',
  courseId: 'course-456',
  clipId: 'clip-789',

  // Environment settings (for testing)
  apiUrl: 'https://tapapistaging.coxwave.link',
  environment: 'staging',

  // Event handlers
  onReady: () => console.log('Ready!'),
  onTimelineSeek: (time, clipId) => {
    videoElement.currentTime = time;
  },
});

// Add to DOM (required)
tapkit.mount();

// Or add to specific container
tapkit.mount(document.getElementById('chat-container'));

// Wait for initialization
await tapkit.ready;

// Show chat window
tapkit.show();

// Clean up
tapkit.destroy();

<script src="https://files.edutap.ai/tap-sdk/loader.js"></script>
<script>
  const kit = window.createTapKit({
    apiKey: 'your-api-key',
    userId: 'user-123',
    courseId: 'course-456',
    clipId: 'clip-789'
  });

  document.body.appendChild(kit);
  kit.ready.then(() => kit.show());
</script>

interface TapKitConfig {
  apiKey: string;
}

interface CreateTapKitOptions {
  // Required
  apiKey: string;

  // Course Information
  userId?: string;
  courseId?: string;
  clipId?: string;
  sectionId?: string;
  clipPlayHead?: number;
  externalReferenceId?: string;
  userInputCode?: string;
  rowDataForCodeEditor?: CodingRowData;

  // Display Options
  language?: 'ko' | 'en' | 'ja';
  mode?: 'inline' | 'floating' | 'sidebar';
  allowLayoutToggle?: boolean;
  videoTarget?: HTMLVideoElement | VideoPlayerAdapter;
  buttonId?: string;
  debug?: boolean;

  // Advanced Options (for testing/development)
  apiUrl?: string;
  tapUrl?: string;
  environment?: 'dev' | 'prod' | 'staging' | 'demo';

  // Event Handlers
  onReady?: () => void;
  onError?: (error: Error) => void;
  onTimelineSeek?: (clipPlayHead: number, clipId: string) => void;
  onAlarmFadeIn?: (messageInfo: AlarmMessageInstanceType) => void;
}

interface TapKitElement extends HTMLElement {
  // Properties
  apiKey: string;
  userId?: string;
  courseId?: string;
  clipId?: string;
  sectionId?: string;
  clipPlayHead?: number;
  externalReferenceId?: string;
  userInputCode?: string;
  rowDataForCodeEditor?: CodingRowData;
  language?: 'ko' | 'en' | 'ja';
  mode?: 'inline' | 'floating' | 'sidebar';
  allowLayoutToggle: boolean;
  videoTarget?: HTMLVideoElement | VideoPlayerAdapter;
  buttonId?: string;
  debug: boolean;

  // Advanced Properties
  apiUrl?: string;
  tapUrl?: string;
  environment?: 'dev' | 'prod' | 'staging' | 'demo';
  /** @deprecated This property no longer affects positioning */
  root?: HTMLElement;

  // Read-only
  readonly isOpen: boolean;
  readonly isInitialized: boolean;
  readonly ready: Promise<void>;

  // Methods
  show(): void;
  hide(): void;
  setCourse(params: SetCourseParams): void;
  setExternalReferenceId(id?: string): void;
  setExternalReferenceData(data?: string): void;
  sendContext(contextType: string, payload: Record<string, unknown>): void;

  // Sub-APIs
  readonly events: {
    seekTimeline(params: { clipPlayHead: number; clipId: string }): void;
    onTimelineSeek(handler: (playHead: number, clipId: string) => void): () => void;
    onAlarmFadeIn(handler: (messageInfo: AlarmMessageInstanceType) => void): () => void;
  };

  /** @deprecated Use videoTarget property instead */
  readonly video: {
    bind(config: HTMLVideoElement | VideoPlayerAdapter, clipId?: string): void;
    unbind(): void;
  };
}

interface CodingRowData {
  language_id_nm: string;  // → coding_language
  d_test_case: string;     // → coding_testcase
  content: string;         // → coding_content
  io_example: string;      // → coding_example
  restriction: string;     // → coding_restriction
  [key: string]: unknown;  // extra fields allowed (ignored by SDK)
}

interface AlarmMessageInstanceType {
  type: 'basic:welcome' | 'basic:default' | 'feat:quiz' | 'feat:guide' | 'feat:progress' | 'custom:cheer';
  content: AlarmElement;
}

interface AlarmElement {
  tag: string;
  props?: Record<string, unknown>;
  children?: (AlarmElement | string)[];
  payload?: {
    type: 'startChat';
    message: string;
    pingMessageId?: string;
  };
}

interface VideoPlayerAdapter {
  /** Current playback time (seconds) */
  getCurrentTime: () => number;
  /**
   * Set playback time
   * @param time - Time to seek (seconds)
   * @param clipId - Target clip ID for cross-clip seeking (optional)
   */
  setCurrentTime: (time: number, clipId?: string) => void;
}

/** HTMLVideoElement or custom adapter */
type VideoPlayerConfig = HTMLVideoElement | VideoPlayerAdapter;

<!-- Use with TapKit (auto toggle) -->
<tap-kit user-id="user-123" course-id="course-456" clip-id="clip-789" section-id="section-456"></tap-kit>
<tap-button position="bottom-right" size="large"></tap-button>

<script>
  const kit = document.querySelector('tap-kit');
  kit.apiKey = 'your-api-key';
</script>

<tap-button position="bottom-left"></tap-button>

<!-- Custom position example -->
<tap-button position="custom" style="top: 100px; right: 50px;"></tap-button>

<tap-button size="small"></tap-button>

<!-- Floating mode (default) -->
<tap-button></tap-button>

<!-- Static mode: placed like normal element -->
<tap-button floating="false"></tap-button>

<tap-button language="en"></tap-button>

<tap-button tutor-name="AI Tutor"></tap-button>

<tap-button position="bottom-right">
  <img src="/my-tutor-icon.svg" alt="AI Tutor" />
</tap-button>

tap-button::part(button) {
  background: linear-gradient(135deg, #6366f1, #8b5cf6);
  border-radius: 50%;
}

tap-button::part(tooltip) {
  background: #1f2937;
  color: white;
}

const button = document.querySelector('tap-button');
button.addEventListener('tap-button:click', (e) => {
  console.log('Button clicked', e.detail);
});