@cognior/iap-sdk 0.1.0

package/src/flow-sequence.ts

@@ -0,0 +1,177 @@
+import { DapConfig } from './config';
+import { TrackingAction } from "./utils/flowTrackingSystem";
+
+/**
+ * Interface representing flow context information
+ */
+export interface FlowContext {
+  /** The previous flow ID in a sequence */
+  previousFlowId: string;
+  /** The full sequence of flow IDs including the current one */
+  sequence: string[];
+  /** How the flow sequence was started */
+  entryPoint: string;
+  /** The step ID that triggered the transition to this flow */
+  referringStepId: string;
+  /** Timestamp when the sequence started */
+  startTime: number;
+  /** Total number of interactions across the flow sequence */
+  totalInteractions: number;
+}
+
+// Store active flow contexts by flow ID
+const activeFlowContexts = new Map<string, FlowContext>();
+
+/**
+ * Save the current flow context for transition to another flow
+ * @param currentFlowId - The ID of the current flow
+ * @param targetFlowId - The ID of the flow we're transitioning to
+ * @param referringStepId - The step ID that triggered the transition
+ */
+export function saveFlowTransitionContext(
+  currentFlowId: string, 
+  targetFlowId: string,
+  referringStepId: string
+): void {
+  // Get existing context or create new one
+  const existingContext = activeFlowContexts.get(currentFlowId) || {
+    previousFlowId: "",
+    sequence: [currentFlowId],
+    entryPoint: "direct",
+    referringStepId: "",
+    startTime: Date.now(),
+    totalInteractions: 0
+  };
+  
+  // Create context for the target flow
+  const targetContext: FlowContext = {
+    previousFlowId: currentFlowId,
+    sequence: [...existingContext.sequence, targetFlowId],
+    entryPoint: "flow_transition",
+    referringStepId: referringStepId,
+    startTime: existingContext.startTime, // Maintain original start time
+    totalInteractions: existingContext.totalInteractions
+  };
+  
+  // Store the context
+  activeFlowContexts.set(targetFlowId, targetContext);
+  
+  // Store in sessionStorage to persist across page loads
+  try {
+    sessionStorage.setItem(
+      `dap_flow_context_${targetFlowId}`, 
+      JSON.stringify(targetContext)
+    );
+    // Also store the last active flow ID for easy retrieval
+    sessionStorage.setItem('dap_last_active_flow', currentFlowId);
+    sessionStorage.setItem('dap_next_flow', targetFlowId);
+  } catch (e) {
+    console.error("[DAP] Failed to store flow context:", e);
+  }
+}
+
+/**
+ * Get flow context for a flow (if available)
+ * @param flowId - The ID of the flow
+ */
+export function getFlowContext(flowId: string): FlowContext | null {
+  // First check memory
+  if (activeFlowContexts.has(flowId)) {
+    return activeFlowContexts.get(flowId)!;
+  }
+  
+  // Then check sessionStorage
+  try {
+    const storedContext = sessionStorage.getItem(`dap_flow_context_${flowId}`);
+    if (storedContext) {
+      const context = JSON.parse(storedContext);
+      activeFlowContexts.set(flowId, context);
+      return context;
+    }
+  } catch (e) {
+    console.error("[DAP] Failed to retrieve flow context:", e);
+  }
+  
+  return null;
+}
+
+/**
+ * Track transition between flows
+ * @param config - DAP configuration
+ * @param fromFlowId - Source flow ID
+ * @param toFlowId - Target flow ID
+ * @param stepId - The step ID that triggered the transition
+ */
+export function trackFlowTransition(
+  config: DapConfig,
+  fromFlowId: string,
+  toFlowId: string,
+  stepId: string
+): void {
+  console.debug(`[DAP] Tracking flow transition from ${fromFlowId} to ${toFlowId} from step ${stepId}`);
+  
+  // Save context for the next flow
+  saveFlowTransitionContext(fromFlowId, toFlowId, stepId);
+  
+  // Track the transition event - legacy, now handled by step view system
+  console.debug('[DAP] Flow transition tracking - handled by step view system');
+}
+
+/**
+ * Track completion of a flow sequence
+ * @param config - DAP configuration 
+ * @param flowId - Current flow ID
+ * @param context - Flow context information
+ */
+export function trackSequenceCompletion(
+  config: DapConfig,
+  flowId: string,
+  context: FlowContext
+): void {
+  const now = Date.now();
+  const sequenceTotalTime = now - context.startTime;
+  
+  console.debug(`[DAP] Tracking sequence completion for flows: ${context.sequence.join(' → ')}`);
+  
+  // Legacy: Sequence completion tracking - now handled by step view system
+  console.debug('[DAP] Flow sequence completion tracking - handled by step view system');
+}
+
+/**
+ * Check if the current navigation appears to be part of a flow transition
+ * (to be called during page load)
+ */
+export function checkForFlowTransition(): { fromFlow: string, toFlow: string } | null {
+  try {
+    // Check if we have a stored transition
+    const lastActiveFlow = sessionStorage.getItem('dap_last_active_flow');
+    const nextFlow = sessionStorage.getItem('dap_next_flow');
+    
+    if (lastActiveFlow && nextFlow) {
+      // Clear the transition markers (they're one-time use)
+      sessionStorage.removeItem('dap_last_active_flow');
+      sessionStorage.removeItem('dap_next_flow');
+      
+      return {
+        fromFlow: lastActiveFlow,
+        toFlow: nextFlow
+      };
+    }
+    
+    // Check URL parameters for flow transition info
+    const urlParams = new URLSearchParams(window.location.search);
+    const fromFlowParam = urlParams.get('from_flow');
+    const toFlowParam = urlParams.get('to_flow') || urlParams.get('flow');
+    
+    if (fromFlowParam && toFlowParam) {
+      return {
+        fromFlow: fromFlowParam,
+        toFlow: toFlowParam
+      };
+    }
+  } catch (e) {
+    console.error("[DAP] Error checking for flow transition:", e);
+  }
+  
+  return null;
+}

package/src/flows.ts

@@ -0,0 +1,512 @@
+// src/flows.ts
+// Transport + server → client normalization (Modal, Tooltip, Popover, Knowledge Base, Survey)
+
+import type {
+  ModalContent,
+  ModalSequencePayload,
+  ModalSequenceStep,
+  TooltipPayload,
+  PopoverPayload,
+  KBItem,
+  KBItemType,
+  ModalKB,
+} from "./experiences/types";
+import type { SurveyPayload, SurveyQuestion } from "./experiences/survey";
+import { flowManager, type ContextualFlow } from "./services/flowManager";
+import { normalizeFlows, normalizeFlow as normalizeServerToContextualFlow } from "./services/flowNormalizer";
+import { normalizePlacement } from "./utils/normalize";
+import { normalizeTrigger as advancedNormalizeTrigger } from "./utils/triggerNormalizer";
+import { normalizeStepId } from "./utils/idGenerator";
+
+/**
+ * Convert advanced trigger normalization to legacy format for backward compatibility
+ * This ensures existing payload types work while supporting enhanced trigger events
+ */
+function normalizeTriggerToLegacyFormat(trigger: string | undefined): "hover" | "focus" | "click" {
+  const normalized = advancedNormalizeTrigger(trigger);
+  
+  // Map new event types to legacy format for type compatibility
+  switch (normalized.eventType) {
+    case 'mouseenter':
+    case 'hover':
+      return 'hover';
+    case 'focus':
+    case 'input':
+    case 'change':
+      return 'focus';
+    case 'click':
+    case 'keydown':
+    case 'keyup':
+    default:
+      return 'click';
+  }
+}
+
+import { http } from "./http";
+import type { DapConfig } from "./config";
+
+/* ------------ Public API used by index.ts ------------ */
+
+export async function fetchVisibleFlowIds(cfg: DapConfig, hostBase: string, page: string | null): Promise<string[]> {
+  const base = joinUrl(cfg.apiurl, `/iap-experience/${cfg.organizationid}/${cfg.siteid}/visible-flows`);
+
+  // Try POST with JSON body (works in demo/mock). If server rejects (405), retry GET with ?hostname=...
+  try {
+    const res = await http(cfg, base, {
+      method: "POST",
+      hostBase,
+      includeHostHeader: true,
+      body: { hostname: hostBase, page: null },
+    });
+    return Array.isArray(res) ? (res as string[]) : [];
+  } catch (e: any) {
+    if (e && e.status === 405) {
+      const url = `${base}?hostname=${encodeURIComponent(hostBase)}`;
+      const res = await http(cfg, url, {
+        method: "GET",
+        hostBase,
+        includeHostHeader: true,
+      });
+      return Array.isArray(res?.flowIds) ? (res.flowIds as string[]) : [];
+    }
+    throw e;
+  }
+}
+
+export async function fetchFlowById(cfg: DapConfig, hostBase: string, flowId: string): Promise<any> {
+  const url = joinUrl(cfg.apiurl, `/iap-experience/${cfg.organizationid}/${cfg.siteid}/flows/${flowId}`);
+  return http(cfg, url, { method: "GET", hostBase, includeHostHeader: true });
+}
+
+/** Normalize a raw server flow JSON to a client-side modalSequence payload */
+export function normalizeServerFlow(serverFlow: any): ModalSequencePayload {
+  console.debug("[DAP] === NORMALIZING SERVER FLOW ===");
+  console.debug("[DAP] Raw server flow data:", serverFlow);
+  console.debug("[DAP] Flow ID:", serverFlow?.flowId);
+  console.debug("[DAP] Flow Name:", serverFlow?.flowName);
+  console.debug("[DAP] Steps count:", serverFlow?.steps?.length);
+
+  // Get contextual properties from the first step for flow manager
+  let hasContextualProperties = false;
+  let elementSelector: string | undefined;
+  let elementTrigger: string | undefined;
+  let elementLocation: string | undefined;
+  
+  const firstStep = serverFlow?.steps?.[0];
+  if (firstStep?.uxExperience) {
+    const ux = firstStep.uxExperience;
+    elementSelector = ux.elementSelector;
+    elementTrigger = ux.elementTrigger;
+    elementLocation = ux.elementLocation;
+    
+    hasContextualProperties = !!(elementSelector || elementLocation);
+  }
+  
+  // Standard payload for modal sequence
+  const out: ModalSequencePayload = { steps: [], startAt: 0 };
+
+  const steps = Array.isArray(serverFlow?.steps) ? serverFlow.steps : [];
+  console.debug(`[DAP] Processing flow with ${steps.length} steps`);
+  
+  for (const step of steps) {
+    console.debug(`[DAP] Processing step:`, {
+      stepId: step?.stepId,
+      stepName: step?.stepName,
+      hasUxExperience: !!step?.uxExperience,
+      hasConditionRuleBlocks: !!(step?.conditionRuleBlocks && step.conditionRuleBlocks.length > 0),
+      conditionRuleBlocksLength: step?.conditionRuleBlocks?.length || 0
+    });
+    
+    // -------- Rule Step (conditionRuleBlocks) --------
+    // Check if this step has conditionRuleBlocks and should be a rule step
+    if (step?.conditionRuleBlocks && Array.isArray(step.conditionRuleBlocks) && step.conditionRuleBlocks.length > 0) {
+      console.debug(`[DAP] Processing rule step:`, step);
+      
+      const stepId = normalizeStepId(step.stepId, "step", out.steps.length + 1);
+      
+      // Use userInputSelector if available, otherwise use selector from first rule block
+      const inputSelector = step.userInputSelector || 
+                           (step.conditionRuleBlocks[0]?.selector) || "";
+      
+      console.debug(`[DAP] Rule step input selector: ${inputSelector}`);
+      console.debug(`[DAP] Rule step has ${step.conditionRuleBlocks.length} rule blocks`);
+      
+      if (!inputSelector) {
+        console.warn(`[DAP] Rule step ${step.stepId} has no input selector, skipping`);
+        continue;
+      }
+      
+      const ruleStep = {
+        kind: "rule" as const,
+        stepId: stepId,
+        inputSelector: inputSelector,
+        rules: step.conditionRuleBlocks
+      };
+      
+      console.debug(`[DAP] Created rule step:`, ruleStep);
+      
+      out.steps.push({
+        kind: "rule",
+        rule: ruleStep,
+        stepId: stepId
+      });
+      
+      console.debug(`[DAP] Added rule step to modal sequence. Total steps: ${out.steps.length}`);
+      continue;
+    }
+    
+    const ux = step?.uxExperience;
+    if (!ux) {
+      console.debug(`[DAP] Skipping step ${step?.stepId} - no uxExperience and no conditionRuleBlocks`);
+      continue;
+    }
+
+    const uxType = String(ux.uxExperienceType || "").toLowerCase();
+
+    // -------- Tooltip --------
+    if (uxType === "tooltip" || ux?.content?.componentType === "Tooltip") {
+      // Always normalize and guarantee uniqueness
+      const stepId = normalizeStepId(step.stepId, "step", out.steps.length + 1);
+      const t: TooltipPayload = {
+        targetSelector: ux.elementSelector || "",
+        text: ux?.content?.text || "",
+        placement: normalizePlacement(ux?.content?.placement),
+        trigger: normalizeTriggerToLegacyFormat(ux.elementTrigger),
+        stepId: stepId
+      };
+      out.steps.push({ 
+        kind: "tooltip", 
+        tooltip: t, 
+        title: ux?.name || "Tip",
+        stepId: stepId,
+        // Preserve trigger information at step level
+        elementSelector: ux.elementSelector,
+        elementTrigger: ux.elementTrigger,
+        elementLocation: ux.elementLocation
+      });
+      continue;
+    }
+
+    // -------- Popover --------
+    if (uxType === "popover" || ux?.content?.componentType === "Popover") {
+      const stepId = normalizeStepId(step.stepId, "step", out.steps.length + 1);
+      const p: PopoverPayload = {
+        title: ux?.content?.title || ux?.name || "Info",
+        body: ux?.content?.body || "",
+        bodyBlocks: Array.isArray(ux?.content?.bodyBlocks) ? ux.content.bodyBlocks : undefined,
+        targetSelector: ux?.elementSelector || "",
+        placement: normalizePlacement(ux?.content?.placement),
+        trigger: normalizeTriggerToLegacyFormat(ux.elementTrigger),
+        showArrow: ux?.content?.showArrow !== false,
+        stepId: stepId
+      };
+      out.steps.push({ 
+        kind: "popover", 
+        popover: p, 
+        title: p.title,
+        stepId: stepId,
+        // Preserve trigger information at step level
+        elementSelector: ux.elementSelector,
+        elementTrigger: ux.elementTrigger,
+        elementLocation: ux.elementLocation
+      });
+      continue;
+    }
+
+    // -------- Modal (incl. Knowledge Base) --------
+    if (uxType === "modal" || ux?.content?.componentType === "Modal") {
+      const blocks: ModalContent[] = [];
+      
+      console.debug("[DAP] Processing modal content for step:", step.stepName);
+      console.debug("[DAP] ux.content:", ux?.content);
+      console.debug("[DAP] ux.modalContent:", ux?.modalContent);
+
+      // For Knowledge Base modals, skip body text and only process KB content
+      const contentType = String(ux?.modalContent?.contentType || "").toLowerCase();
+      const isKnowledgeBase = contentType === "knowledgebase";
+      console.log("[DAP] Processing Knowledge Base content:", isKnowledgeBase);
+      console.debug("[DAP] Is Knowledge Base modal:", isKnowledgeBase);
+      console.debug("[DAP] modalContent.contentType:", ux?.modalContent?.contentType);
+      console.debug("[DAP] modalContent full object:", ux?.modalContent);
+      console.log("[DAP] ux.content.body:", ux?.content?.body);
+      if (ux?.content?.body && !isKnowledgeBase) {
+        console.debug("[DAP] Adding text block with body:", typeof ux.content.body, ux.content.body);
+        
+        // Safety check: if body is an array (KB items), don't add it as text
+        if (Array.isArray(ux.content.body)) {
+          console.warn("[DAP] Body content is an array, likely KB items incorrectly assigned to body:", ux.content.body);
+          // Create KB block instead of text block
+          const kbItems = toKbItems(ux.content.body);
+          console.debug("[DAP] Creating KB block from body array:", kbItems);
+          const kb: ModalKB = {
+            kind: "kb",
+            title: ux?.content?.header || ux?.name || "Knowledge Base",
+            items: kbItems,
+          };
+          blocks.push(kb);
+          console.debug("[DAP] Added KB block from body array:", kb);
+        } else {
+          blocks.push({ kind: "text", html: String(ux.content.body) });
+        }
+      } else if (ux?.content?.body && isKnowledgeBase) {
+        console.debug("[DAP] Skipping body text for Knowledge Base modal, body content:", ux.content.body);
+      }
+
+      // Knowledge Base block
+      if (contentType === "knowledgebase") {
+        console.debug("[DAP] Processing Knowledge Base content:", ux?.modalContent);
+        const kbItems = toKbItems(ux?.modalContent?.contentData);
+        console.debug("[DAP] Generated KB items:", kbItems);
+        
+        const kb: ModalKB = {
+          kind: "kb",
+          title: ux?.content?.header || ux?.name || "Knowledge Base",
+          items: kbItems,
+        };
+        blocks.push(kb);
+        console.debug("[DAP] Added KB block:", kb);
+      } else {
+        // Single-content modal
+        const c = ux?.modalContent;
+        if (c) {
+          const url = c.presignedUrl || c.contentData || "";
+          const ctype = String(c.contentType || "").toLowerCase();
+          if (ctype === "link") {
+            if (isYouTube(url)) {
+              blocks.push({ kind: "youtube", href: url, title: c.contentName || "YouTube" });
+            } else if (isHttp(url)) {
+              blocks.push({ kind: "link", href: url, label: c.contentName || url });
+            }
+          } else if (ctype === "video") {
+            if (isHttp(url)) blocks.push({ kind: "video", sources: [{ src: url }] });
+          } else if (ctype === "image") {
+            if (isHttp(url)) blocks.push({ kind: "image", url, alt: c.contentName || "" });
+          } else if (ctype === "article") {
+            if (isHttp(url)) {
+              blocks.push({
+                kind: "article",
+                url,
+                fileName: c.contentData || undefined,
+                mime: /\.pdf(\?|#|$)/i.test(url)
+                  ? "application/pdf"
+                  : /\.docx(\?|#|$)/i.test(url)
+                  ? "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+                  : undefined,
+              });
+            }
+          }
+        }
+      }
+
+      console.debug("[DAP] Final blocks array for modal:", blocks);
+      console.debug("[DAP] Block kinds:", blocks.map(b => b.kind));
+
+      const stepId = normalizeStepId(step.stepId, "step", out.steps.length + 1);
+      out.steps.push({
+        kind: "modal",
+        title: ux?.content?.header || ux?.name || "Info",
+        footerText: ux?.content?.footer || "",
+        body: blocks,
+        stepId: stepId,
+        // Preserve trigger information at step level
+        elementSelector: ux.elementSelector,
+        elementTrigger: ux.elementTrigger,
+        elementLocation: ux.elementLocation
+      });
+      continue;
+    }
+
+    // -------- Survey --------
+    if (uxType === "survey" || ux?.content?.componentType === "MicroSurvey") {
+      const stepId = normalizeStepId(step.stepId, "step", out.steps.length + 1);
+      const survey: SurveyPayload = {
+        header: ux?.content?.header || ux?.name || "Survey",
+        body: ux?.content?.body || "",
+        questions: Array.isArray(ux?.content?.questions) 
+          ? ux.content.questions.map((q: any) => ({
+            questionId: q.questionId || `q${Math.random().toString(36).substring(2, 10)}`,
+            question: q.question || "",
+            type: q.type || "SingleChoice",
+            options: Array.isArray(q.options) ? q.options : undefined,
+            scaleMin: q.scaleMin !== undefined ? q.scaleMin : undefined,
+            scaleMax: q.scaleMax !== undefined ? q.scaleMax : undefined,
+            labelMin: q.labelMin || undefined,
+            labelMax: q.labelMax || undefined,
+            criteria: Array.isArray(q.criteria) ? q.criteria : undefined,
+          } as SurveyQuestion))
+          : [],
+        flowId: serverFlow.flowId,
+        organizationId: serverFlow.organizationId,
+        siteId: serverFlow.siteId,
+        stepId: stepId
+      };
+      out.steps.push({ 
+        kind: "survey",
+        survey: survey,
+        title: survey.header || "Survey",
+        stepId: stepId,
+        // Preserve trigger information at step level
+        elementSelector: ux.elementSelector,
+        elementTrigger: ux.elementTrigger,
+        elementLocation: ux.elementLocation
+      });
+      continue;
+    }
+  }
+
+  // Normalize all step IDs using our utility
+  out.steps.forEach(step => {
+    if (step.stepId) {
+      step.stepId = normalizeStepId(step.stepId);
+      
+      // Also update in the nested payload if present
+      if (step.tooltip && step.tooltip.stepId) {
+        step.tooltip.stepId = step.stepId;
+      } else if (step.popover && step.popover.stepId) {
+        step.popover.stepId = step.stepId;
+      } else if (step.survey && step.survey.stepId) {
+        step.survey.stepId = step.stepId;
+      }
+    }
+  });
+
+  // Store the total steps in the payload for tracking
+  if (out.steps.length > 0) {
+    // Add a steps-count attribute to the payload for total steps tracking
+    out.stepsCount = out.steps.length;
+  }
+  
+  // All flows are now handled directly by modalSequence
+  // modalSequence is responsible for handling all triggers and step transitions
+  // FlowManager is not used for flow registration in this architecture
+
+  console.debug("[DAP] === NORMALIZATION COMPLETE ===");
+  console.debug("[DAP] Total steps created:", out.steps.length);
+  console.debug("[DAP] Final modal sequence payload:", out);
+  out.steps.forEach((step, index) => {
+    console.debug(`[DAP] Step ${index + 1}:`, {
+      kind: step.kind,
+      stepId: step.stepId,
+      hasRule: step.kind === 'rule',
+      ruleData: step.kind === 'rule' ? step.rule : undefined
+    });
+  });
+  console.debug("[DAP] === END NORMALIZATION ===");
+
+  return out;
+}
+
+/**
+ * Convert server flow to contextual flow format
+ */
+function convertToContextualFlow(serverFlow: any): ContextualFlow {
+  let elementSelector: string | undefined = undefined;
+  let elementTrigger: string | undefined = undefined;
+  let elementLocation: string | undefined = undefined;
+  
+  // Create an empty modal sequence payload
+  const payload: ModalSequencePayload = { steps: [], startAt: 0 };
+  
+  // Extract contextual properties from the first step's UX experience
+  const steps = Array.isArray(serverFlow?.steps) ? serverFlow.steps : [];
+  if (steps.length > 0) {
+    const step = steps[0];
+    const ux = step?.uxExperience;
+    
+    if (ux) {
+      elementSelector = ux.elementSelector;
+      elementTrigger = ux.elementTrigger;
+      elementLocation = ux.elementLocation;
+    }
+  }
+  
+  return {
+    id: serverFlow.id || serverFlow.flowId || `flow-${Math.random().toString(36).substring(2, 10)}`,
+    type: "modalSequence",
+    payload,
+    elementSelector,
+    elementTrigger,
+    elementLocation,
+    originalData: serverFlow
+  };
+}
+
+/* ------------ helpers ------------ */
+
+export type NormalizedFlow = ModalSequencePayload; // for index.ts legacy imports
+
+function toTrigger(t: string | undefined | null): "hover" | "focus" | "click" {
+  // Use the enhanced trigger normalization with backward compatibility
+  return normalizeTriggerToLegacyFormat(t || undefined);
+}
+
+function isHttp(url: string): boolean {
+  try { const u = new URL(url, location.origin); return /^https?:$/i.test(u.protocol); } catch { return false; }
+}
+
+function isYouTube(url: string): boolean {
+  try {
+    const u = new URL(url, location.origin);
+    const h = u.hostname.toLowerCase();
+    return /(^|\.)youtube\.com$/.test(h) || /(^|\.)youtu\.be$/.test(h) || /(^|\.)youtube-nocookie\.com$/.test(h);
+  } catch { return false; }
+}
+
+function mapItemType(t: string, url: string): KBItemType {
+  const v = (t || "").toLowerCase();
+  if (v === "link") return isYouTube(url) ? "youtube" : "link";
+  if (v === "video") return "video";
+  if (v === "image") return "image";
+  if (v === "article") return "article";
+  return "link";
+}
+
+function toKbItems(arr: any[] | null | undefined): KBItem[] {
+  console.debug("[DAP] toKbItems input:", arr);
+  if (!Array.isArray(arr)) return [];
+  const items: KBItem[] = [];
+  for (const it of arr) {
+    // Extract data from the KB item structure from flow.json
+    const url = it?.presignedUrl || "";
+    const title = it?.contentName || "";
+    const description = it?.contentDescription || "";
+    const contentType = it?.contentType || "";
+    const fileName = it?.contentData || "";
+    
+    console.debug("[DAP] Processing KB item:", { 
+      raw: it, 
+      extracted: { url, title, description, contentType, fileName } 
+    });
+    
+    if (!url || !title) {
+      console.warn("[DAP] KB item missing required fields (url or title), skipping:", it);
+      continue;
+    }
+    
+    const kbItem = {
+      kind: "kb-item" as const,
+      itemType: mapItemType(contentType, url),
+      title,
+      description,
+      url,
+      fileName: fileName || undefined,
+      mime:
+        /\.pdf(\?|#|$)/i.test(url)
+          ? "application/pdf"
+          : /\.docx(\?|#|$)/i.test(url)
+          ? "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+          : undefined,
+    };
+    console.debug("[DAP] Generated KB item:", kbItem);
+    items.push(kbItem);
+  }
+  console.debug("[DAP] Final KB items array:", items);
+  return items;
+}
+
+/** Join URLs safely: trims duplicate slashes */
+function joinUrl(base: string, tail: string): string {
+  const b = (base || "").replace(/\/+$/, "");
+  const t = (tail || "").replace(/^\/+/, "");
+  return `${b}/${t}`;
+}