@coxwave/tap-kit-types 2.10.1 → 2.10.3

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";
+type TapMessage = TapReadyMessage | TapCloseMessage | TimelineSeekMessage | AlarmClickMessage | AlarmFadeInMessage | PopUpOpenMessage | PopUpCloseMessage | MaterialViewOpenMessage | MaterialViewCloseMessage | MaterialViewErrorMessage | HtmlViewOpenMessage | HtmlViewCloseMessage | ContainerModeChangeMessage | ContainerModeChangeAckMessage | ContainerLayoutStateChangedMessage | ViewportResizeMessage | ConfigUpdateMessage | ConfigRequestMessage | GAEventMessage | TutorInfoMessage;
 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;
 }
@@ -396,6 +358,7 @@ interface ViewportResizeMessage {
  * - This message protocol mirrors the structure for serialization
  * - When updating ContainerConfig, update this structure accordingly
  */
+type ChatMode = "NORMAL" | "EXAM" | "STUDY";
 interface ConfigUpdateMessage {
     type: "config:update";
     apiKey?: string;
@@ -403,12 +366,14 @@ 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;
     clipPlayHead?: number;
     mode?: DisplayMode;
+    /** Chat interaction mode (staging feature: per-message override) */
+    chatMode?: ChatMode;
     /**
      * Allow user to toggle between floating and sidebar layouts
      * @default true
@@ -473,15 +438,6 @@ interface TutorInfoMessage {
     type: "tutor:info";
     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
- */
-interface FeatureFlagsUpdateMessage {
-    type: "featureFlags:update";
-    flags: FeatureFlags;
-}
 
 /**
  * Fallback type.
@@ -2290,6 +2246,7 @@ declare const ConfigUpdateSchema: ObjectSchema<{
     readonly clipId: OptionalSchema<StringSchema<undefined>, undefined>;
     readonly clipPlayHead: OptionalSchema<NumberSchema<undefined>, undefined>;
     readonly mode: OptionalSchema<UnionSchema<[LiteralSchema<"inline", undefined>, LiteralSchema<"floating", undefined>, LiteralSchema<"sidebar", undefined>], undefined>, undefined>;
+    readonly chatMode: OptionalSchema<UnionSchema<[LiteralSchema<"NORMAL", undefined>, LiteralSchema<"EXAM", undefined>, LiteralSchema<"STUDY", undefined>], undefined>, undefined>;
     readonly allowLayoutToggle: OptionalSchema<BooleanSchema<undefined>, undefined>;
     readonly container: OptionalSchema<ObjectSchema<{
         readonly floatingConfig: OptionalSchema<ObjectSchema<{
@@ -2401,6 +2358,7 @@ declare const TapMessageSchema: UnionSchema<[ObjectSchema<{
     readonly clipId: OptionalSchema<StringSchema<undefined>, undefined>;
     readonly clipPlayHead: OptionalSchema<NumberSchema<undefined>, undefined>;
     readonly mode: OptionalSchema<UnionSchema<[LiteralSchema<"inline", undefined>, LiteralSchema<"floating", undefined>, LiteralSchema<"sidebar", undefined>], undefined>, undefined>;
+    readonly chatMode: OptionalSchema<UnionSchema<[LiteralSchema<"NORMAL", undefined>, LiteralSchema<"EXAM", undefined>, LiteralSchema<"STUDY", undefined>], undefined>, undefined>;
     readonly allowLayoutToggle: OptionalSchema<BooleanSchema<undefined>, undefined>;
     readonly container: OptionalSchema<ObjectSchema<{
         readonly floatingConfig: OptionalSchema<ObjectSchema<{
@@ -3370,7 +3328,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;
@@ -3582,7 +3540,7 @@ interface TapKitAttributes {
   "clip-play-head"?: number;
 
   /** Language setting */
-  language?: "ko" | "en";
+  language?: "ko" | "en" | "ja";
 
   /** TAP Frontend URL (for testing) */
   "tap-url"?: string;
@@ -3607,6 +3565,9 @@ interface TapKitAttributes {
    */
   mode?: "inline" | "floating" | "sidebar";
 
+  /** Chat interaction mode (staging feature: per-message override) */
+  "chat-mode"?: "NORMAL" | "EXAM" | "STUDY";
+
   /**
    * Allow user to toggle between floating and sidebar layouts
    * Only applies when mode is "floating" or "sidebar"
@@ -3730,7 +3691,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;
 }
@@ -3913,9 +3874,10 @@ 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";
       debug?: boolean;
       apiUrl?: string;
       tapUrl?: string;
@@ -3941,4 +3903,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 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 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
@@ -855,6 +866,7 @@ var ConfigUpdateSchema = object({
   clipId: optional(string()),
   clipPlayHead: optional(number()),
   mode: optional(union([literal("inline"), literal("floating"), literal("sidebar")])),
+  chatMode: optional(union([literal("NORMAL"), literal("EXAM"), literal("STUDY")])),
   allowLayoutToggle: optional(boolean()),
   container: optional(
     object({
@@ -922,6 +934,6 @@ var TapMessageSchema = union([
 // 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, 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