@coxwave/tap-kit-types 2.1.1 → 2.6.0

package/dist/index.d.ts

@@ -178,6 +178,58 @@ type ContainerConfig = {
     sidebarConfig?: SidebarConfig;
 };
 
+/**
+ * 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";
+/**
+ * Feature flags object type
+ *
+ * All flags are optional - undefined means "use default behavior"
+ * false = explicitly disabled
+ * true = explicitly enabled
+ */
+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;
+
 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 {
@@ -223,6 +275,10 @@ interface MaterialViewOpenMessage {
     pageStart: number;
     pageEnd: number;
     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) */
+    flags?: FeatureFlags;
     nonce?: string | number;
 }
 /**
@@ -367,6 +423,8 @@ interface ConfigUpdateMessage {
             minViewportWidth?: number;
         };
     };
+    /** SDK source for deprecation tracking (temporary - remove after monitoring period) */
+    sdkSource?: "tap-kit" | "tap-sdk";
 }
 /**
  * Config Request Message (iframe → parent, call/handle pattern)
@@ -2226,6 +2284,7 @@ declare const ConfigUpdateSchema: ObjectSchema<{
             readonly minViewportWidth: OptionalSchema<NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
     }, undefined>, undefined>;
+    readonly sdkSource: OptionalSchema<UnionSchema<[LiteralSchema<"tap-kit", undefined>, LiteralSchema<"tap-sdk", undefined>], undefined>, undefined>;
 }, undefined>;
 declare const ConfigRequestSchema: ObjectSchema<{
     readonly type: LiteralSchema<"config:request", undefined>;
@@ -2336,6 +2395,7 @@ declare const TapMessageSchema: UnionSchema<[ObjectSchema<{
             readonly minViewportWidth: OptionalSchema<NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
     }, undefined>, undefined>;
+    readonly sdkSource: OptionalSchema<UnionSchema<[LiteralSchema<"tap-kit", undefined>, LiteralSchema<"tap-sdk", undefined>], undefined>, undefined>;
 }, undefined>, ObjectSchema<{
     readonly type: LiteralSchema<"config:request", undefined>;
     readonly nonce: OptionalSchema<UnionSchema<[StringSchema<undefined>, NumberSchema<undefined>], undefined>, undefined>;
@@ -3655,6 +3715,12 @@ interface MaterialViewConfig {
    * Optional title for the viewer header
    */
   title?: string;
+
+  /**
+   * Feature flags for viewer behavior
+   * @example { "material.pdf.download": false } // Disable download button
+   */
+  flags?: FeatureFlags;
 }
 
 /**
@@ -3866,4 +3932,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 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 };
+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 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

@@ -2,6 +2,12 @@ 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);
 
+// src/feature-flags.ts
+function isFeatureEnabled(flags, key, defaultValue = true) {
+  if (!flags) return defaultValue;
+  return flags[key] ?? defaultValue;
+}
+
 // src/errors.ts
 var TAP_ERROR_MARKER = "__tap_sdk_error__";
 var TapKitError = class _TapKitError extends Error {
@@ -878,7 +884,8 @@ var ConfigUpdateSchema = object({
         })
       )
     })
-  )
+  ),
+  sdkSource: optional(union([literal("tap-kit"), literal("tap-sdk")]))
 });
 var ConfigRequestSchema = object({
   type: literal("config:request"),
@@ -919,6 +926,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 };
+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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map