@coxwave/tap-kit-types 2.10.2 → 2.10.4

package/dist/index.d.ts

@@ -179,74 +179,36 @@ type ContainerConfig = {
 };
 
 /**
- * Feature Flags Type Definitions
- *
- * Extensible feature flag system using dot notation for namespacing.
- * Flags are optional booleans - undefined means "use default behavior".
- *
- * Naming convention: "domain.subdomain.feature"
- * Examples:
- * - "material.pdf.download" - PDF download in material viewer
- * - "quiz.enabled" - Quiz feature availability
- * - "chat.attachment" - File attachment in chat
- *
- * @example
- * const flags: FeatureFlags = {
- *   "material.pdf.download": false, // Disable PDF download
- * };
- */
-/**
- * Known feature flag keys (for type safety and autocomplete)
- *
- * When adding new flags:
- * 1. Add the key to this union type
- * 2. Document the flag's purpose in JSDoc
- */
-type FeatureFlagKey = 
-/**
- * Enable/disable PDF download button in material viewer
- * @default true (download enabled)
- */
-"material.pdf.download"
-/**
- * Enable/disable streak widget on home page
- * @default false (disabled, feature in development)
- */
- | "home.streak.enabled"
-/**
- * Enable/disable flashcard widget on home page
- * @default false (disabled, feature in development)
- */
- | "home.flashcard.enabled"
-/**
- * Enable/disable activity buttons on home page
- * @default true (enabled by default)
- */
- | "home.activity.enabled";
-/**
- * Feature flags object type
- *
- * All flags are optional - undefined means "use default behavior"
- * false = explicitly disabled
- * true = explicitly enabled
- */
+ * Feature Flags — Single Source of Truth
+ *
+ * FLAG_DEFAULTS is the sole authority.
+ * FeatureFlagKey is derived — never define keys separately.
+ * Server values always override: { ...FLAG_DEFAULTS, ...serverFlags }
+ *
+ * Naming: LaunchDarkly-style {action}.{subject}
+ *   - show.*  — UI visibility toggle
+ *   - allow.* — capability/permission gate
+ */
+/** Every flag and its default. Add new flags here — types update automatically. */
+declare const FLAG_DEFAULTS: {
+    readonly "show.tutor-profile": true;
+    readonly "show.streak": false;
+    readonly "show.activity": true;
+    readonly "show.quicktaps": true;
+    readonly "show.flashcard": false;
+    readonly "show.exam-activity": false;
+    readonly "show.chat-mode-chip": false;
+    readonly "allow.pdf-download": true;
+};
+/** Derived union of all known flag keys. */
+type FeatureFlagKey = keyof typeof FLAG_DEFAULTS;
+/** Partial flags — API boundary type (server may omit keys). */
 type FeatureFlags = Partial<Record<FeatureFlagKey, boolean>>;
-/**
- * Helper to check if a feature is enabled
- *
- * @param flags - Feature flags object
- * @param key - Feature flag key to check
- * @param defaultValue - Default value if flag is undefined (default: true)
- * @returns Whether the feature is enabled
- *
- * @example
- * const canDownload = isFeatureEnabled(flags, "material.pdf.download"); // default true
- * const quizEnabled = isFeatureEnabled(flags, "quiz.enabled", false); // default false
- */
-declare function isFeatureEnabled(flags: FeatureFlags | undefined, key: FeatureFlagKey, defaultValue?: boolean): boolean;
+/** Check if a feature is enabled. Falls back to FLAG_DEFAULTS. */
+declare function isFeatureEnabled(flags: FeatureFlags | undefined, key: FeatureFlagKey): boolean;
 
-type TapMessageType = "tap:ready" | "tap:close" | "timeline:seek" | "alarm:click" | "alarm:fadeIn" | "popUp:open" | "popUp:close" | "material:view:open" | "material:view:close" | "material:view:error" | "html:view:open" | "html:view:close" | "container:mode:change" | "container:mode:change:ack" | "container:layout:state:changed" | "viewport:resize" | "config:update" | "config:request" | "GA_EVENT" | "tutor:info" | "featureFlags:update";
-type TapMessage = TapReadyMessage | TapCloseMessage | TimelineSeekMessage | AlarmClickMessage | AlarmFadeInMessage | PopUpOpenMessage | PopUpCloseMessage | MaterialViewOpenMessage | MaterialViewCloseMessage | MaterialViewErrorMessage | HtmlViewOpenMessage | HtmlViewCloseMessage | ContainerModeChangeMessage | ContainerModeChangeAckMessage | ContainerLayoutStateChangedMessage | ViewportResizeMessage | ConfigUpdateMessage | ConfigRequestMessage | GAEventMessage | TutorInfoMessage | FeatureFlagsUpdateMessage;
+type TapMessageType = "tap:ready" | "tap:close" | "timeline:seek" | "alarm:click" | "alarm:fadeIn" | "popUp:open" | "popUp:close" | "material:view:open" | "material:view:close" | "material:view:error" | "html:view:open" | "html:view:close" | "container:mode:change" | "container:mode:change:ack" | "container:layout:state:changed" | "viewport:resize" | "config:update" | "config:request" | "GA_EVENT" | "tutor:info" | "host:context";
+type TapMessage = TapReadyMessage | TapCloseMessage | TimelineSeekMessage | AlarmClickMessage | AlarmFadeInMessage | PopUpOpenMessage | PopUpCloseMessage | MaterialViewOpenMessage | MaterialViewCloseMessage | MaterialViewErrorMessage | HtmlViewOpenMessage | HtmlViewCloseMessage | ContainerModeChangeMessage | ContainerModeChangeAckMessage | ContainerLayoutStateChangedMessage | ViewportResizeMessage | ConfigUpdateMessage | ConfigRequestMessage | GAEventMessage | TutorInfoMessage | HostContextMessage;
 interface TapReadyMessage {
     type: "tap:ready";
     gaId: string;
@@ -292,7 +254,7 @@ interface MaterialViewOpenMessage {
     title?: string;
     /** Text phrases to highlight in PDF (from reference_string parsing) */
     highlightPhrases?: string[];
-    /** Feature flags for viewer behavior (e.g., "material.pdf.download": false) */
+    /** Feature flags for viewer behavior (e.g., "allow.pdf-download": false) */
     flags?: FeatureFlags;
     nonce?: string | number;
 }
@@ -404,7 +366,7 @@ interface ConfigUpdateMessage {
     tapUrl?: string;
     apiUrl?: string;
     environment?: "dev" | "prod" | "demo" | "staging";
-    language?: "ko" | "en" | (string & {});
+    language?: "ko" | "en" | "ja" | (string & {});
     userId?: string;
     courseId?: string;
     clipId?: string;
@@ -477,13 +439,24 @@ interface TutorInfoMessage {
     tutorName: string;
 }
 /**
- * Feature Flags Update Message (iframe → parent)
- * Sent from edutap after tutor_setting API response with feature flags
- * Used to update feature flags store in tap-kit-core
+ * Host Context Message (parent → iframe)
+ * Generic channel for host application to send contextual data to the iframe.
+ * Uses contextType discriminator for different context kinds (quiz answers, reading progress, etc.)
+ *
+ * @example
+ * ```typescript
+ * // Passage answer submission
+ * messenger.post({
+ *   type: "host:context",
+ *   contextType: "passage:answer:submit",
+ *   payload: { passageId, question, selectedOptionId, isCorrect }
+ * });
+ * ```
  */
-interface FeatureFlagsUpdateMessage {
-    type: "featureFlags:update";
-    flags: FeatureFlags;
+interface HostContextMessage {
+    type: "host:context";
+    contextType: string;
+    payload: Record<string, unknown>;
 }
 
 /**
@@ -2326,6 +2299,11 @@ declare const TutorInfoSchema: ObjectSchema<{
     readonly type: LiteralSchema<"tutor:info", undefined>;
     readonly tutorName: StringSchema<undefined>;
 }, undefined>;
+declare const HostContextSchema: ObjectSchema<{
+    readonly type: LiteralSchema<"host:context", undefined>;
+    readonly contextType: StringSchema<undefined>;
+    readonly payload: RecordSchema<StringSchema<undefined>, AnySchema, undefined>;
+}, undefined>;
 declare const TapMessageSchema: UnionSchema<[ObjectSchema<{
     readonly type: LiteralSchema<"tap:ready", undefined>;
     readonly gaId: StringSchema<undefined>;
@@ -2434,6 +2412,10 @@ declare const TapMessageSchema: UnionSchema<[ObjectSchema<{
 }, undefined>, ObjectSchema<{
     readonly type: LiteralSchema<"tutor:info", undefined>;
     readonly tutorName: StringSchema<undefined>;
+}, undefined>, ObjectSchema<{
+    readonly type: LiteralSchema<"host:context", undefined>;
+    readonly contextType: StringSchema<undefined>;
+    readonly payload: RecordSchema<StringSchema<undefined>, AnySchema, undefined>;
 }, undefined>], undefined>;
 
 type TapMessageRecord = TapMessage;
@@ -2833,6 +2815,12 @@ interface TapKitInstance {
     setCourse(course: Partial<Course> & {
         courseId: string;
     }): void;
+    /**
+     * Send contextual data from host application to the iframe
+     * @param contextType - Discriminator for context kind (e.g., "passage:answer:submit")
+     * @param payload - Arbitrary data payload
+     */
+    sendContext(contextType: string, payload: Record<string, unknown>): void;
 }
 /** TapKit constructor type */
 type TapKitConstructor = new (config: TapKitConfig) => TapKitInstance;
@@ -3375,7 +3363,7 @@ interface TapKitElement extends HTMLElement {
   clipPlayHead?: number;
 
   /** Language (optional, default: "ko") */
-  language?: "ko" | "en";
+  language?: "ko" | "en" | "ja";
 
   /** TAP Frontend URL (optional, for testing) */
   tapUrl?: string;
@@ -3472,6 +3460,27 @@ interface TapKitElement extends HTMLElement {
    */
   setCourse(course: Partial<Course> & { courseId: string }): void;
 
+  /**
+   * Send contextual data from host application to the iframe (AI tutor)
+   *
+   * Generic channel for passing host context (quiz answers, reading progress, etc.)
+   * to the iframe. Uses contextType discriminator for different context kinds.
+   *
+   * @param contextType - Discriminator string (e.g., "passage:answer:submit")
+   * @param payload - Arbitrary data payload
+   *
+   * @example
+   * ```typescript
+   * kit.sendContext("passage:answer:submit", {
+   *   passageId: "p1",
+   *   question: "What is...?",
+   *   selectedOptionId: "A",
+   *   isCorrect: true,
+   * });
+   * ```
+   */
+  sendContext(contextType: string, payload: Record<string, unknown>): void;
+
   // ===== Delegate Properties (Read-only) =====
 
   /**
@@ -3587,7 +3596,7 @@ interface TapKitAttributes {
   "clip-play-head"?: number;
 
   /** Language setting */
-  language?: "ko" | "en";
+  language?: "ko" | "en" | "ja";
 
   /** TAP Frontend URL (for testing) */
   "tap-url"?: string;
@@ -3738,7 +3747,7 @@ interface MaterialViewConfig {
 
   /**
    * Feature flags for viewer behavior
-   * @example { "material.pdf.download": false } // Disable download button
+   * @example { "allow.pdf-download": false } // Disable download button
    */
   flags?: FeatureFlags;
 }
@@ -3921,7 +3930,7 @@ declare global {
       courseId?: string;
       clipId?: string;
       clipPlayHead?: number;
-      language?: "ko" | "en";
+      language?: "ko" | "en" | "ja";
       buttonId?: string;
       mode?: "inline" | "floating" | "sidebar";
       chatMode?: "NORMAL" | "EXAM" | "STUDY";
@@ -3950,4 +3959,4 @@ declare global {
   function cancelIdleCallback(handle: number): void;
 }
 
-export { ALARM_DURATION, type AlarmClickMessage, AlarmClickSchema, type AlarmElement, type AlarmElementProps, AlarmElementPropsSchema, AlarmElementSchema, type AlarmFadeInMessage, AlarmFadeInSchema, AlarmMessageInstanceSchema, type AlarmMessageInstanceType, type AlarmPayload, type AlarmType, type CSSStyle, CSSStyleSchema, type ChatMode, type ConfigRequestMessage, ConfigRequestSchema, type ConfigUpdateKey, type ConfigUpdateMessage, type ConfigUpdateOptions, type ConfigUpdatePayload, ConfigUpdateSchema, type ContainerConfig, type ContainerLayoutStateChangedMessage, ContainerLayoutStateChangedSchema, type ContainerModeChangeAckMessage, ContainerModeChangeAckSchema, type ContainerModeChangeMessage, ContainerModeChangeSchema, type ContainerVisibility, type Course, type DisplayMode, type EventManager, type FeatureFlagKey, type FeatureFlags, type FeatureFlagsUpdateMessage, type FloatingConfig, type GAEventMessage, GAEventSchema, type HtmlViewCloseMessage, HtmlViewCloseSchema, type HtmlViewConfig, type HtmlViewOpenMessage, HtmlViewOpenSchema, type ITapButtonElement, type ITapContainerElement, type ITapHtmlViewerElement, type ITapKitElement, type ITapMaterialViewerElement, TapKitInitializationError as InitializationError, type LayoutMode, type MaterialViewCloseMessage, MaterialViewCloseSchema, type MaterialViewConfig, type MaterialViewErrorMessage, MaterialViewErrorSchema, type MaterialViewOpenMessage, MaterialViewOpenSchema, MaterialViewerError, type PopUpCloseMessage, PopUpCloseSchema, type PopUpOpenMessage, PopUpOpenSchema, type PositionType, type SeekTimelineParamsType, type ShortcutKeyPropertiesType, type SidebarConfig, type SyncableConfigKey, TAP_BUTTON_CLICK_EVENT, TAP_ERROR_MARKER, type TapButtonAttributes, type TapButtonClickEventDetail, type TapCloseMessage, TapCloseSchema, type TapContainerAttributes, type TapErrorOptions, type TapHtmlViewerAttributes, type TapKitConfig, TapKitConfigurationError, type TapKitConstructor, type TapKitElement, type TapKitElementEventMap, TapKitError, TapKitIframeError, type TapKitInitParams, TapKitInitializationError, type TapKitInstance, TapKitLoaderError, TapKitMessageError, type TapMaterialViewerAttributes, type TapMessage, type TapMessageRecord, TapMessageSchema, type TapMessageType, type TapReadyMessage, TapReadySchema, type TimelineSeekMessage, TimelineSeekSchema, type TutorInfoMessage, TutorInfoSchema, type VideoController, type VideoPlayerAdapter, type VideoPlayerConfig, type ViewportResizeMessage, ViewportResizeSchema, isFeatureEnabled };
+export { ALARM_DURATION, type AlarmClickMessage, AlarmClickSchema, type AlarmElement, type AlarmElementProps, AlarmElementPropsSchema, AlarmElementSchema, type AlarmFadeInMessage, AlarmFadeInSchema, AlarmMessageInstanceSchema, type AlarmMessageInstanceType, type AlarmPayload, type AlarmType, type CSSStyle, CSSStyleSchema, type ChatMode, type ConfigRequestMessage, ConfigRequestSchema, type ConfigUpdateKey, type ConfigUpdateMessage, type ConfigUpdateOptions, type ConfigUpdatePayload, ConfigUpdateSchema, type ContainerConfig, type ContainerLayoutStateChangedMessage, ContainerLayoutStateChangedSchema, type ContainerModeChangeAckMessage, ContainerModeChangeAckSchema, type ContainerModeChangeMessage, ContainerModeChangeSchema, type ContainerVisibility, type Course, type DisplayMode, type EventManager, FLAG_DEFAULTS, type FeatureFlagKey, type FeatureFlags, type FloatingConfig, type GAEventMessage, GAEventSchema, type HostContextMessage, HostContextSchema, type HtmlViewCloseMessage, HtmlViewCloseSchema, type HtmlViewConfig, type HtmlViewOpenMessage, HtmlViewOpenSchema, type ITapButtonElement, type ITapContainerElement, type ITapHtmlViewerElement, type ITapKitElement, type ITapMaterialViewerElement, TapKitInitializationError as InitializationError, type LayoutMode, type MaterialViewCloseMessage, MaterialViewCloseSchema, type MaterialViewConfig, type MaterialViewErrorMessage, MaterialViewErrorSchema, type MaterialViewOpenMessage, MaterialViewOpenSchema, MaterialViewerError, type PopUpCloseMessage, PopUpCloseSchema, type PopUpOpenMessage, PopUpOpenSchema, type PositionType, type SeekTimelineParamsType, type ShortcutKeyPropertiesType, type SidebarConfig, type SyncableConfigKey, TAP_BUTTON_CLICK_EVENT, TAP_ERROR_MARKER, type TapButtonAttributes, type TapButtonClickEventDetail, type TapCloseMessage, TapCloseSchema, type TapContainerAttributes, type TapErrorOptions, type TapHtmlViewerAttributes, type TapKitConfig, TapKitConfigurationError, type TapKitConstructor, type TapKitElement, type TapKitElementEventMap, TapKitError, TapKitIframeError, type TapKitInitParams, TapKitInitializationError, type TapKitInstance, TapKitLoaderError, TapKitMessageError, type TapMaterialViewerAttributes, type TapMessage, type TapMessageRecord, TapMessageSchema, type TapMessageType, type TapReadyMessage, TapReadySchema, type TimelineSeekMessage, TimelineSeekSchema, type TutorInfoMessage, TutorInfoSchema, type VideoController, type VideoPlayerAdapter, type VideoPlayerConfig, type ViewportResizeMessage, ViewportResizeSchema, isFeatureEnabled };

package/dist/index.js

@@ -3,9 +3,20 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
 // src/feature-flags.ts
-function isFeatureEnabled(flags, key, defaultValue = true) {
-  if (!flags) return defaultValue;
-  return flags[key] ?? defaultValue;
+var FLAG_DEFAULTS = {
+  // Home screen (top → bottom, matches preview order)
+  "show.tutor-profile": true,
+  "show.streak": false,
+  "show.activity": true,
+  "show.quicktaps": true,
+  "show.flashcard": false,
+  "show.exam-activity": false,
+  "show.chat-mode-chip": false,
+  // Capabilities (not in preview)
+  "allow.pdf-download": true
+};
+function isFeatureEnabled(flags, key) {
+  return flags?.[key] ?? FLAG_DEFAULTS[key];
 }
 
 // src/errors.ts
@@ -897,6 +908,11 @@ var TutorInfoSchema = object({
   type: literal("tutor:info"),
   tutorName: string()
 });
+var HostContextSchema = object({
+  type: literal("host:context"),
+  contextType: string(),
+  payload: record(string(), any())
+});
 var TapMessageSchema = union([
   TapReadySchema,
   TapCloseSchema,
@@ -917,12 +933,13 @@ var TapMessageSchema = union([
   ConfigUpdateSchema,
   ConfigRequestSchema,
   GAEventSchema,
-  TutorInfoSchema
+  TutorInfoSchema,
+  HostContextSchema
 ]);
 
 // src/tap-button.d.ts
 var TAP_BUTTON_CLICK_EVENT = "tap-button:click";
 
-export { ALARM_DURATION, AlarmClickSchema, AlarmElementPropsSchema, AlarmElementSchema, AlarmFadeInSchema, AlarmMessageInstanceSchema, CSSStyleSchema, ConfigRequestSchema, ConfigUpdateSchema, ContainerLayoutStateChangedSchema, ContainerModeChangeAckSchema, ContainerModeChangeSchema, GAEventSchema, HtmlViewCloseSchema, HtmlViewOpenSchema, TapKitInitializationError as InitializationError, MaterialViewCloseSchema, MaterialViewErrorSchema, MaterialViewOpenSchema, MaterialViewerError, PopUpCloseSchema, PopUpOpenSchema, TAP_BUTTON_CLICK_EVENT, TAP_ERROR_MARKER, TapCloseSchema, TapKitConfigurationError, TapKitError, TapKitIframeError, TapKitInitializationError, TapKitLoaderError, TapKitMessageError, TapMessageSchema, TapReadySchema, TimelineSeekSchema, TutorInfoSchema, ViewportResizeSchema, isFeatureEnabled };
+export { ALARM_DURATION, AlarmClickSchema, AlarmElementPropsSchema, AlarmElementSchema, AlarmFadeInSchema, AlarmMessageInstanceSchema, CSSStyleSchema, ConfigRequestSchema, ConfigUpdateSchema, ContainerLayoutStateChangedSchema, ContainerModeChangeAckSchema, ContainerModeChangeSchema, FLAG_DEFAULTS, GAEventSchema, HostContextSchema, HtmlViewCloseSchema, HtmlViewOpenSchema, TapKitInitializationError as InitializationError, MaterialViewCloseSchema, MaterialViewErrorSchema, MaterialViewOpenSchema, MaterialViewerError, PopUpCloseSchema, PopUpOpenSchema, TAP_BUTTON_CLICK_EVENT, TAP_ERROR_MARKER, TapCloseSchema, TapKitConfigurationError, TapKitError, TapKitIframeError, TapKitInitializationError, TapKitLoaderError, TapKitMessageError, TapMessageSchema, TapReadySchema, TimelineSeekSchema, TutorInfoSchema, ViewportResizeSchema, isFeatureEnabled };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map