@cognior/iap-sdk 0.1.0

package/src/experiences/types.ts

@@ -0,0 +1,395 @@
+// src/experiences/types.ts
+
+/** Shared placement type for tooltip/popover */
+export type CornerPlacement =
+  | "top-right" | "top-left" | "bottom-right" | "bottom-left"
+  | "right" | "left" | "top" | "bottom";
+
+/* ------------------ Enhanced Trigger System Types ------------------ */
+
+/** Logical operators for composite triggers */
+export type LogicalOperator = "And" | "Or";
+
+/** Rule operators for condition evaluation */
+export type RuleOperator =
+  | "Equals" | "NotEquals" | "Contains" | "NotContains"
+  | "StartsWith" | "EndsWith"
+  | "GreaterThan" | "LessThan"
+  | "GreaterThanOrEqual" | "LessThanOrEqual"
+  | "In" | "NotIn" | "Regex" | "Empty";
+
+/** Trigger types */
+export type TriggerType = "Single" | "Composite";
+
+/** Trigger condition kinds */
+export type TriggerConditionKind =
+  | "Dom" | "Lifecycle" | "Input" | "Time" | "Media" | "System";
+
+/** Flow execution modes */
+export type FlowExecutionMode = "Linear" | "AnyOrder";
+
+/** Flow frequency types */
+export type FlowFrequencyType = "OneTime" | "Recurring";
+
+/** Step types */
+export type StepType = "Mandatory" | "Optional";
+
+/** Branch types */
+export type BranchType = "Flow" | "Step" | "Continue";
+
+/** Individual trigger condition */
+export interface TriggerCondition {
+  kind: TriggerConditionKind;
+  event: string;
+  selector?: string;
+  operator?: RuleOperator;
+  value?: any;
+  debounceMs?: number;
+}
+
+/** Step-level trigger definition */
+export interface TriggerDefinition {
+  type: TriggerType;
+  operator: LogicalOperator;
+  once: boolean;
+  conditions: TriggerCondition[];
+}
+
+/** Runtime trigger evaluation context */
+export interface TriggerEvaluationContext {
+  stepId: string;
+  flowId: string;
+  element?: HTMLElement;
+  event?: Event;
+  userInput?: any;
+  pageState?: any;
+}
+
+/** Trigger evaluation result */
+export interface TriggerEvaluationResult {
+  triggered: boolean;
+  matchedConditions: number;
+  totalConditions: number;
+  evaluationTime: number;
+  debugInfo?: any;
+}
+
+/* ------------------ Step State Management for FlowRunner ------------------ */
+
+export type StepExecutionState = "idle" | "waiting-for-trigger" | "rendered" | "completed";
+
+export interface StepExecutionContext {
+  stepIndex: number;
+  stepId: string;
+  state: StepExecutionState;
+  hasElementTrigger: boolean;
+  targetElement?: HTMLElement;
+  triggerListeners?: (() => void)[];
+  lastTriggeredTime?: number;
+}
+
+export interface FlowRunnerState {
+  currentStepIndex: number;
+  stepContexts: Map<number, StepExecutionContext>;
+  isMultiStep: boolean;
+  pageLoadTriggersExecuted: Set<string>;
+}
+
+/* ------------------ Rule condition types for dynamic flow switching ------------------ */
+
+export type ConditionOperator = "Equals" | "NotEquals" | "Contains" | "NotContains" | "GreaterThan" | "LessThan";
+export type ConditionValueType = "String" | "Number" | "Boolean";
+
+export interface RuleCondition {
+  propertyName: string | null;
+  operator: ConditionOperator;
+  valueType: ConditionValueType;
+  value: string | number | boolean;
+}
+
+export interface ConditionRuleBlock {
+  ruleBlockId: string;
+  selector: string;
+  logicalOperator: LogicalOperator;
+  conditions: RuleCondition[];
+  nextFlowId: string;
+}
+
+/* ------------------ Rule step for flow sequences ------------------ */
+
+export interface RuleStep {
+  kind: "rule";
+  stepId: string;
+  inputSelector: string;
+  rules: ConditionRuleBlock[];
+}
+
+/* ------------------ Modal content blocks ------------------ */
+
+export type ModalText = { kind: "text"; html: string };
+export type ModalLink = { kind: "link"; href: string; label?: string };
+export type ModalImage = { kind: "image"; url: string; alt?: string };
+export type ModalVideoSource = { src: string; type?: string };
+export type ModalVideo = { kind: "video"; sources: ModalVideoSource[] };
+export type ModalYouTube = { kind: "youtube"; href: string; id?: string; title?: string; thumbnail?: string };
+export type ModalArticle = { kind: "article"; url: string; fileName?: string; mime?: string };
+
+/* ------------------ Knowledge Base blocks ------------------ */
+
+export type KBItemType = "link" | "youtube" | "video" | "image" | "article" | "pdf" | "doc" | "docx";
+
+export interface KBItem {
+  kind: "kb-item";
+  itemType: KBItemType;
+  title?: string;
+  description?: string;
+  url: string;            // presigned or absolute URL
+  fileName?: string;      // for articles
+  mime?: string;          // optional hint
+}
+
+export interface ModalKB {
+  kind: "kb";
+  title?: string;
+  items: KBItem[];
+  viewState?: "list" | "item";  // Internal view state
+  currentItem?: KBItem;         // Currently viewed item
+}
+
+/* ------------------ KB Item Viewer Content Types ------------------ */
+
+export interface ModalKBItemViewer {
+  kind: "kb-item-viewer";
+  item: KBItem;
+  kbTitle?: string;  // Parent KB title for breadcrumb
+}
+
+/* ------------------ Unions ------------------ */
+
+export type ModalContent =
+  | ModalText
+  | ModalLink
+  | ModalImage
+  | ModalVideo
+  | ModalYouTube
+  | ModalArticle
+  | ModalKB
+  | ModalKBItemViewer;
+
+/* ------------------ Modal Sequence (flows rendered by modalSequence) ------------------ */
+
+export interface TooltipPayload {
+  targetSelector: string;                 // CSS selector or XPath
+  text: string;
+  placement?: string;                     // "auto" | "top" | "bottom" | "left" | "right" | corners
+  trigger?: "hover" | "focus" | "click";
+  stepId?: string;                        // Unique step identifier for tracking
+  _completionTracker?: CompletionTracker;
+}
+
+/** Rich popover support (text/links/buttons/forms/images) */
+export type PopoverText = { kind: "text"; html: string };
+export type PopoverLink = { kind: "link"; href: string; label?: string };
+export type PopoverButton = {
+  kind: "button";
+  label: string;
+  action: string;                         // "btn_next" | "btn_close" | "custom:save" ...
+  variant?: "primary" | "secondary" | "danger";
+};
+export type PopoverImage = { kind: "image"; url: string; alt?: string; width?: number; height?: number };
+export type PopoverFormField =
+  | { type: "text" | "email" | "number"; name: string; label?: string; placeholder?: string; required?: boolean }
+  | { type: "textarea"; name: string; label?: string; placeholder?: string; required?: boolean; rows?: number }
+  | { type: "select"; name: string; label?: string; required?: boolean; options: Array<{ label: string; value: string }> }
+  | { type: "checkbox"; name: string; label: string; required?: boolean };
+export type PopoverForm = {
+  kind: "form";
+  id: string;
+  fields: PopoverFormField[];
+  submitLabel?: string;
+  cancelLabel?: string;
+};
+export type PopoverBlock = PopoverText | PopoverLink | PopoverButton | PopoverImage | PopoverForm;
+
+export interface PopoverPayload {
+  title?: string;
+  body?: string;                          // legacy HTML (sanitized)
+  bodyBlocks?: PopoverBlock[];            // preferred
+  targetSelector: string;
+  placement?: string;
+  trigger?: "hover" | "focus" | "click";
+  showArrow?: boolean;
+  stepId?: string;                        // Unique step identifier for tracking
+  _completionTracker?: CompletionTracker;
+}
+
+export interface ModalSequenceStep {
+  kind: "modal" | "tooltip" | "popover" | "survey" | "rule";
+  title?: string;
+  footerText?: string;
+  body?: ModalContent[];         // modal content blocks
+  size?: ModalSize;              // modal size variant
+  tooltip?: TooltipPayload;      // tooltip payload
+  popover?: PopoverPayload;      // popover payload
+  stepId?: string;               // Unique step identifier for tracking
+  survey?: any;                  // survey payload
+  rule?: RuleStep;               // rule payload for conditional flow switching
+  
+  // Trigger information for step-level triggering
+  elementSelector?: string;      // CSS/XPath selector for trigger element
+  elementTrigger?: string;       // Trigger type: "click", "hover", "on page load", etc.
+  elementLocation?: string;      // Location context for the trigger element
+}
+
+export interface CompletionTracker {
+  onComplete: () => void;
+  onStepAdvance?: (stepId: string) => void;
+}
+
+export interface ModalSequencePayload {
+  startAt?: number;
+  theme?: Record<string, string>;
+  steps: ModalSequenceStep[];
+  /** Total number of steps in the sequence - used for tracking completion */
+  stepsCount?: number;
+  _completionTracker?: CompletionTracker;
+}
+
+/* ------------------ Back-compat (for existing modal.ts using ModalPayload) ------------------ */
+export type ModalSize = "small" | "medium" | "large" | "fullscreen";
+
+export interface ModalPayload {
+  title?: string;
+  footerText?: string;
+  body?: ModalContent[];
+  size?: ModalSize;
+  theme?: Record<string, string>;
+  draggable?: boolean; // Enable/disable dragging behavior (default: true)
+  _completionTracker?: CompletionTracker;
+}
+
+/* ------------------ Banner Experience ------------------ */
+export interface BannerPayload {
+  message: string;
+  variant?: "info" | "warning" | "error" | "success";
+  position?: "top" | "bottom";
+  dismissible?: boolean;
+  autoHide?: number; // auto-hide after N seconds
+  actions?: Array<{
+    label: string;
+    action: "dismiss" | "navigate" | "custom";
+    href?: string; // for navigate action
+    customAction?: string; // for custom action
+  }>;
+  theme?: Record<string, string>;
+  _completionTracker?: CompletionTracker;
+}
+
+/* ------------------ Hotspots Experience ------------------ */
+export interface HotspotItem {
+  id: string;
+  selector: string; // CSS selector for target element
+  title: string;
+  description: string;
+  placement?: CornerPlacement;
+  pulseColor?: string;
+  required?: boolean; // if true, user must click this hotspot
+}
+
+export interface HotspotsPayload {
+  title?: string;
+  description?: string;
+  hotspots: HotspotItem[];
+  showProgress?: boolean;
+  allowSkip?: boolean;
+  theme?: Record<string, string>;
+  _completionTracker?: CompletionTracker;
+}
+
+/* ------------------ Hotspot Tour Experience ------------------ */
+export interface HotspotTourStep {
+  id: string;
+  selector: string; // CSS selector for target element
+  title: string;
+  description: string;
+  placement?: CornerPlacement;
+  action?: "next" | "close" | "custom";
+  customAction?: string; // for custom action
+}
+
+export interface HotspotTourPayload {
+  title?: string;
+  description?: string;
+  steps: HotspotTourStep[];
+  showProgress?: boolean;
+  allowSkip?: boolean;
+  autoAdvance?: number; // auto-advance after N seconds
+  theme?: Record<string, string>;
+  _completionTracker?: CompletionTracker;
+}
+
+/* ------------------ Task List Experience ------------------ */
+export interface TaskItem {
+  id: string;
+  title: string;
+  description?: string;
+  completed?: boolean;
+  required?: boolean;
+  action?: string; // custom action when completed
+}
+
+export interface TaskListPayload {
+  title?: string;
+  description?: string;
+  tasks: TaskItem[];
+  allowPartialCompletion?: boolean;
+  showProgress?: boolean;
+  theme?: Record<string, string>;
+  _completionTracker?: CompletionTracker;
+}
+
+/* ------------------ Walkthrough Experience ------------------ */
+export interface WalkthroughStep {
+  title: string;
+  content: string;
+  target?: string; // CSS selector
+  position?: 'top' | 'bottom' | 'left' | 'right';
+  autoAdvance?: boolean;
+  autoAdvanceDelay?: number; // ms
+  autoScroll?: boolean;
+  waitTimeout?: number; // ms
+}
+
+export interface WalkthroughPayload {
+  steps: WalkthroughStep[];
+  theme?: Record<string, string>;
+  _completionTracker?: CompletionTracker;
+}
+
+/* ------------------ Beacon Experience ------------------ */
+export interface BeaconPayload {
+  title?: string;
+  body?: string;
+  icon?: string;                          // emoji or icon character
+  position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' | 'center';
+  targetSelector?: string;                // CSS selector for element to attach beacon to
+  trigger?: 'hover' | 'focus' | 'click' | 'on hover' | 'on focus' | 'on click' | 'on page load';
+  autoDismiss?: number;                   // auto-dismiss after N seconds
+  action?: string;                        // custom action when clicked
+  beaconStyles?: {
+    enabled?: boolean;
+    color1?: string;                      // primary pulse color
+    color2?: string;                      // secondary pulse color  
+    duration?: string;                    // animation duration
+    padding?: string;                     // pulse padding
+    borderWidth?: string;                 // pulse border width
+    borderRadius?: string;                // pulse border radius
+    shadowSize?: string;                  // pulse shadow size
+  };
+  _completionTracker?: CompletionTracker;
+}
+
+/* ===================== Note =====================
+   MicroSurveyPayload has been merged into SurveyPayload in survey.ts
+   The unified survey system handles both modal and inline survey modes
+   ================================================ */