react-native-my-survey-sdk 2.0.6 → 2.0.8

package/src/core/XeboNetworkService.ts

@@ -0,0 +1,375 @@
+import {
+  XeboSurvey,
+  XeboQuestion,
+  XeboQuestionType,
+  XeboChoice,
+  XeboConditionalFollowUp,
+  XeboAnswer,
+  XeboEnvironment,
+} from '../models/XeboModels';
+import {
+  APICollectorResponse,
+  APISurveyResponse,
+  APIQuestion,
+  APIConfigScale,
+} from '../models/XeboAPIModels';
+
+// ─── URL helpers ──────────────────────────────────────────────────────────────
+
+export function resolveZoneAndEnv(zone: string, explicitEnv?: XeboEnvironment): { resolvedZone: string; environment: XeboEnvironment } {
+  if (zone.startsWith('uat-')) {
+    return { resolvedZone: zone.slice(4), environment: 'uat' };
+  }
+  return { resolvedZone: zone, environment: explicitEnv ?? 'production' };
+}
+
+export function buildBaseURL(resolvedZone: string, environment: XeboEnvironment): string {
+  return environment === 'uat'
+    ? `https://uat-${resolvedZone}-api.xebo.ai`
+    : `https://${resolvedZone}-api.xebo.ai`;
+}
+
+export function buildFeedbackBaseURL(resolvedZone: string, environment: XeboEnvironment): string {
+  return environment === 'uat'
+    ? `https://uat-${resolvedZone}-feedback-api.xebo.ai`
+    : `https://${resolvedZone}-feedback-api.xebo.ai`;
+}
+
+// ─── HTML stripping ───────────────────────────────────────────────────────────
+
+export function stripHTML(raw: string | undefined): string {
+  if (!raw) return '';
+  return raw
+    .replace(/<[^>]*>/g, '')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .trim();
+}
+
+// ─── Question type mapping ────────────────────────────────────────────────────
+
+function mapRatingStyle(apiType?: string): string {
+  switch (apiType?.toLowerCase()) {
+    case 'star':
+    case 'stars':    return 'star';
+    case 'heart':
+    case 'hearts':   return 'heart';
+    case 'circle':
+    case 'circles':  return 'circle';
+    case 'tile':
+    case 'tiles':    return 'tile';
+    case 'emoji':
+    case 'emojis':   return 'emoji';
+    default:         return 'star';
+  }
+}
+
+function mapQuestionType(apiType: string): XeboQuestionType {
+  switch (apiType) {
+    case 'single_choice':   return XeboQuestionType.singleChoice;
+    case 'multi_choice':    return XeboQuestionType.multipleChoice;
+    case 'dropdown':        return XeboQuestionType.dropdown;
+    case 'single_text':     return XeboQuestionType.singleTextBox;
+    case 'multi_text':      return XeboQuestionType.multipleTextBox;
+    case 'nps':
+    case 'nps_pro':         return XeboQuestionType.nps;
+    case 'multi_nps':       return XeboQuestionType.multiNps;
+    case 'rating':
+    case 'rating_pro':      return XeboQuestionType.rating;
+    case 'multi_rating':    return XeboQuestionType.multiRating;
+    default:                return XeboQuestionType.singleChoice;
+  }
+}
+
+// ─── Survey parsing ───────────────────────────────────────────────────────────
+
+export function parseSurvey(data: APISurveyResponse['data']): XeboSurvey {
+  // Collect all follow-up question IDs (from NPS Pro configScale)
+  const followUpQuestionIds = new Set<string>();
+  for (const block of data.blocks) {
+    for (const item of block.questions) {
+      const q = item.question;
+      const scales = q.settings?.configScale ?? [];
+      for (const scale of scales) {
+        for (const qid of scale.qId ?? []) {
+          followUpQuestionIds.add(qid);
+        }
+      }
+    }
+  }
+
+  const questions: XeboQuestion[] = [];
+
+  for (const block of data.blocks) {
+    for (const item of block.questions) {
+      const q = item.question;
+
+      // Skip follow-up questions (they're embedded inline)
+      if (followUpQuestionIds.has(q.uuid)) continue;
+
+      const type = mapQuestionType(q.quesType);
+      if (type === XeboQuestionType.dropdown) {
+        console.log('[Xebo] Dropdown raw options keys:', JSON.stringify(Object.keys(q.options ?? {})));
+        console.log('[Xebo] Dropdown options.row:', JSON.stringify(q.options?.row));
+        console.log('[Xebo] Full dropdown q.options:', JSON.stringify(q.options));
+      }
+      const rows: XeboChoice[] = (q.options?.row ?? []).map(r => ({
+        id: r.uuid,
+        text: stripHTML(r.text),
+        value: r.uuid,
+      }));
+      const cols: XeboChoice[] = (q.options?.col ?? []).map(c => ({
+        id: c.uuid,
+        text: stripHTML(c.text),
+        value: c.uuid,
+      }));
+
+      // Build conditional follow-ups for NPS Pro
+      const conditionalFollowUps: XeboConditionalFollowUp[] = [];
+      const scales: APIConfigScale[] = q.settings?.configScale ?? [];
+      for (const scale of scales) {
+        if (scale.enabled === false) continue;
+        const followUpQId = scale.qId?.[0];
+        if (!followUpQId) continue;
+
+        // Find the follow-up question in all blocks
+        let followUpApiQ: APIQuestion | undefined;
+        for (const b of data.blocks) {
+          for (const bi of b.questions) {
+            if (bi.question.uuid === followUpQId) {
+              followUpApiQ = bi.question;
+              break;
+            }
+          }
+          if (followUpApiQ) break;
+        }
+
+        const followUpOptions: XeboChoice[] = (followUpApiQ?.options?.row ?? []).map(r => ({
+          id: r.uuid,
+          text: stripHTML(r.text),
+          value: r.uuid,
+        }));
+
+        conditionalFollowUps.push({
+          minRating: Number(scale.scale.min),
+          maxRating: Number(scale.scale.max),
+          followUpQuestion: stripHTML(followUpApiQ?.title ?? ''),
+          followUpType: followUpApiQ ? mapQuestionType(followUpApiQ.quesType) : XeboQuestionType.singleTextBox,
+          followUpOptions,
+          questionId: followUpQId,
+        });
+      }
+
+      const npsSettings = q.settings?.nps;
+      const ratingSettings = q.settings?.rating;
+
+      const parsed: XeboQuestion = {
+        id: q.uuid,
+        type,
+        title: stripHTML(q.title),
+        subtitle: stripHTML(q.helperText?.text),
+        placeholder: stripHTML(q.placeholder?.text),
+        isRequired: q.required?.enabled ?? false,
+        options: rows.length > 0 ? rows : undefined,
+        columns: cols.length > 0 ? cols : undefined,
+        npsLabels: npsSettings
+          ? {
+              lower: npsSettings.leftLabel,
+              upper: npsSettings.rightLabel,
+              detractorColor: npsSettings.colors?.detractor,
+              passiveColor: npsSettings.colors?.passive,
+              promoterColor: npsSettings.colors?.promoter,
+            }
+          : undefined,
+        followUpQuestion: undefined,
+        conditionalFollowUps: conditionalFollowUps.length > 0 ? conditionalFollowUps : undefined,
+        ratingStyle: mapRatingStyle(ratingSettings?.type),
+        showColLabels: ratingSettings?.colLabel,
+        ratingColor: ratingSettings?.color,
+      };
+
+      questions.push(parsed);
+    }
+  }
+
+  // Append auto thank-you question
+  const tyPage = data.thankYouPage;
+  const tyTitle = tyPage?.enabled && tyPage.content
+    ? stripHTML(tyPage.content)
+    : 'Thank You!';
+  const tySubtitle = tyPage?.enabled && tyPage.content
+    ? undefined
+    : 'Your feedback is greatly appreciated.';
+
+  questions.push({
+    id: 'thank_you_auto',
+    type: XeboQuestionType.thankYou,
+    title: tyTitle,
+    subtitle: tySubtitle,
+    isRequired: false,
+    redirectURL: tyPage?.links,
+  });
+
+  const introPageRaw = data.introPage;
+  const thankYouPageRaw = data.thankYouPage;
+
+  const survey = {
+    id: data.uuid,
+    name: data.displayTitle,
+    projectId: data.projectId,
+    questions,
+    introPage: introPageRaw
+      ? {
+          enabled: introPageRaw.enabled ?? false,
+          content: stripHTML(introPageRaw.content),
+          buttonText: introPageRaw.buttonText,
+        }
+      : undefined,
+    thankYouPage: thankYouPageRaw
+      ? {
+          enabled: thankYouPageRaw.enabled ?? false,
+          content: stripHTML(thankYouPageRaw.content),
+          links: thankYouPageRaw.links,
+        }
+      : undefined,
+  };
+
+  console.log('[Xebo] Full parsed survey:', JSON.stringify(survey, null, 2));
+  return survey;
+}
+
+// ─── API calls ────────────────────────────────────────────────────────────────
+
+export interface CollectorInfo {
+  surveyId: string;
+  uuid: string;
+  mongoId: string;
+}
+
+export async function fetchCollector(
+  baseURL: string,
+  collectorId: string,
+  apiKey: string
+): Promise<CollectorInfo> {
+  const url = `${baseURL}/v3/collectors/collect/${collectorId}`;
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('[Xebo Step 1] Fetching collector');
+  console.log('URL:', url);
+  console.log('Collector ID:', collectorId);
+
+  const res = await fetch(url, { headers: { 'x-api-key': apiKey } });
+  const json: APICollectorResponse = await res.json();
+
+  // The API may return the collector object directly at the root OR wrapped in a `data` key
+  const payload = json?.data ?? (json as unknown as APICollectorResponse['data']);
+
+  if (!res.ok || !payload?.surveyId) {
+    throw new Error(
+      `[Xebo] fetchCollector failed — HTTP ${res.status}. ` +
+      `Check your apiKey, collectorId and zone. Response: ${JSON.stringify(json)}`
+    );
+  }
+
+  const info: CollectorInfo = {
+    surveyId: payload.surveyId,
+    uuid: payload.uuid,
+    mongoId: payload._id,
+  };
+
+  console.log('Collector UUID:', info.uuid);
+  console.log('Collector MongoId:', info.mongoId);
+  console.log('Survey ID:', info.surveyId);
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+  return info;
+}
+
+export async function fetchSurvey(
+  baseURL: string,
+  surveyId: string,
+  apiKey: string
+): Promise<XeboSurvey> {
+  const url = `${baseURL}/v3/survey-management/surveys/${surveyId}`;
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('[Xebo Step 2] Fetching survey');
+  console.log('URL:', url);
+
+  const res = await fetch(url, { headers: { 'x-api-key': apiKey } });
+  const json: APISurveyResponse = await res.json();
+
+  console.log('[Xebo] Survey HTTP status:', res.status);
+  console.log('[Xebo] Survey data keys:', Object.keys(json?.data ?? {}));
+  console.log('[Xebo] blocks:', JSON.stringify(json?.data?.blocks?.length));
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+  if (!json?.data) {
+    throw new Error(`[Xebo] fetchSurvey — no data in response. HTTP ${res.status}`);
+  }
+  if (!Array.isArray(json.data.blocks)) {
+    throw new Error(`[Xebo] fetchSurvey — 'blocks' missing. Keys: ${Object.keys(json.data)}`);
+  }
+
+  return parseSurvey(json.data);
+}
+
+export interface SubmitResult {
+  ok: boolean;
+  status: number;
+  responseJson: unknown;
+}
+
+export async function submitResponse(
+  feedbackBaseURL: string,
+  surveyId: string,
+  collectorUUID: string,
+  apiKey: string,
+  answers: XeboAnswer[]
+): Promise<SubmitResult> {
+  const url = `${feedbackBaseURL}/v3/survey-participation/${surveyId}/response/create-response`;
+
+  // Filter out auto thank-you answer
+  const filteredAnswers = answers.filter(a => a.questionId !== 'thank_you_auto');
+
+  const payload = {
+    collector_id: collectorUUID,
+    responses: [
+      {
+        response_status: 'complete',
+        questions: filteredAnswers.map(a => ({
+          uuid: a.questionId,
+          answer: a.value.map(v => ({
+            row_id: v.rowId,
+            col_id: v.colId ?? '',
+            text: v.text ?? '',
+          })),
+        })),
+      },
+    ],
+  };
+
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('[Xebo Step 3] Submitting response');
+  console.log('URL:', url);
+  console.log('Survey ID:', surveyId);
+  console.log('Collector ID:', collectorUUID);
+  console.log('Question count:', filteredAnswers.length);
+  console.log('Payload:', JSON.stringify(payload, null, 2));
+
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+
+  const responseJson = await res.json();
+
+  console.log('HTTP Status:', res.status);
+  console.log('Response JSON:', JSON.stringify(responseJson, null, 2));
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+  return { ok: res.ok, status: res.status, responseJson };
+}

package/src/core/XeboOfflineQueue.ts

@@ -0,0 +1,33 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { XeboQueuedResponse } from '../models/XeboModels';
+
+const STORAGE_KEY = 'com.xebo.offline_responses';
+
+export const XeboOfflineQueue = {
+  async enqueue(response: XeboQueuedResponse): Promise<void> {
+    const existing = await this.getAll();
+    existing.push(response);
+    await this.saveAll(existing);
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('[Xebo Offline Queue] Enqueued response:', response.responseId);
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  },
+
+  async getAll(): Promise<XeboQueuedResponse[]> {
+    try {
+      const raw = await AsyncStorage.getItem(STORAGE_KEY);
+      if (!raw) return [];
+      return JSON.parse(raw) as XeboQueuedResponse[];
+    } catch {
+      return [];
+    }
+  },
+
+  async saveAll(responses: XeboQueuedResponse[]): Promise<void> {
+    await AsyncStorage.setItem(STORAGE_KEY, JSON.stringify(responses));
+  },
+
+  async clear(): Promise<void> {
+    await AsyncStorage.removeItem(STORAGE_KEY);
+  },
+};

package/src/core/XeboSurveyManager.ts

@@ -0,0 +1,296 @@
+import NetInfo from '@react-native-community/netinfo';
+
+// Minimal inline event emitter — no external 'events' package needed
+type Listener = (...args: any[]) => void;
+class SimpleEventEmitter {
+  private _listeners: Map<string, Listener[]> = new Map();
+  emit(event: string, ...args: any[]): boolean {
+    const fns = this._listeners.get(event) ?? [];
+    fns.forEach(fn => fn(...args));
+    return fns.length > 0;
+  }
+  on(event: string, listener: Listener): this {
+    this._listeners.set(event, [...(this._listeners.get(event) ?? []), listener]);
+    return this;
+  }
+  off(event: string, listener: Listener): this {
+    this._listeners.set(event, (this._listeners.get(event) ?? []).filter(l => l !== listener));
+    return this;
+  }
+  removeAllListeners(event?: string): this {
+    event ? this._listeners.delete(event) : this._listeners.clear();
+    return this;
+  }
+}
+
+const uuidv4 = () =>
+  'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
+    const r = (Math.random() * 16) | 0;
+    return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+  });
+import {
+  XeboSurvey,
+  XeboAnswer,
+  XeboConfig,
+  XeboThemeConfig,
+  XeboEnvironment,
+  XeboQueuedResponse,
+} from '../models/XeboModels';
+import {
+  resolveZoneAndEnv,
+  buildBaseURL,
+  buildFeedbackBaseURL,
+  fetchCollector,
+  fetchSurvey,
+  submitResponse,
+} from './XeboNetworkService';
+import { XeboOfflineQueue } from './XeboOfflineQueue';
+import { configureTheme } from '../theme/XeboTheme';
+
+// ─── Event names ──────────────────────────────────────────────────────────────
+
+export const XEBO_EVENTS = {
+  SURVEY_LOADED: 'survey_loaded',
+  QUESTION_CHANGED: 'question_changed',
+  SURVEY_VISIBLE: 'survey_visible',
+  SURVEY_DISMISSED: 'survey_dismissed',
+} as const;
+
+// ─── Singleton class ──────────────────────────────────────────────────────────
+
+class XeboSurveyManagerClass extends SimpleEventEmitter {
+  // Config
+  private apiKey = '';
+  private collectorId = '';
+  private resolvedZone = '';
+  private environment: XeboEnvironment = 'production';
+  private baseURL = '';
+  private feedbackBaseURL = '';
+
+  // State
+  survey: XeboSurvey | null = null;
+  currentAnswers: XeboAnswer[] = [];
+  currentQuestionIndex = 0;
+  surveyStartTime = '';
+  resolvedCollectorUUID = '';
+  resolvedCollectorMongoId = '';
+  surveyVisible = false;
+
+  // Network monitoring unsubscribe handle
+  private netInfoUnsubscribe: (() => void) | null = null;
+
+  // ─── Configure ─────────────────────────────────────────────────────────────
+
+  configure(config: XeboConfig): void {
+    this.apiKey = config.apiKey;
+    this.collectorId = config.collectorId;
+
+    const { resolvedZone, environment } = resolveZoneAndEnv(config.zone, config.environment);
+    this.resolvedZone = resolvedZone;
+    this.environment = environment;
+    this.baseURL = buildBaseURL(resolvedZone, environment);
+    this.feedbackBaseURL = buildFeedbackBaseURL(resolvedZone, environment);
+
+    this._startNetworkMonitoring();
+    // Pre-fetch survey in background so it's ready instantly when button is tapped
+    this._prefetchSurvey();
+  }
+
+  configureTheme(config: XeboThemeConfig): void {
+    configureTheme(config);
+  }
+
+  // ─── Network monitoring ────────────────────────────────────────────────────
+
+  private _startNetworkMonitoring(): void {
+    if (this.netInfoUnsubscribe) {
+      this.netInfoUnsubscribe();
+    }
+
+    let wasOffline = false;
+
+    this.netInfoUnsubscribe = NetInfo.addEventListener(state => {
+      const isConnected = state.isConnected ?? false;
+      if (wasOffline && isConnected) {
+        console.log('[Xebo] Network restored — flushing offline queue');
+        this.flushQueue();
+      }
+      wasOffline = !isConnected;
+    });
+  }
+
+  // ─── Background pre-fetch ──────────────────────────────────────────────────
+
+  private async _prefetchSurvey(): Promise<void> {
+    try {
+      console.log('[Xebo] Pre-fetching survey in background...');
+      const collector = await fetchCollector(this.baseURL, this.collectorId, this.apiKey);
+      this.resolvedCollectorUUID = collector.uuid;
+      this.resolvedCollectorMongoId = collector.mongoId;
+      const survey = await fetchSurvey(this.baseURL, collector.surveyId, this.apiKey);
+      this.survey = survey;
+      this.emit(XEBO_EVENTS.SURVEY_LOADED, survey);
+      console.log('[Xebo] Pre-fetch done —', survey.questions.length, 'questions ready');
+    } catch (err) {
+      console.warn('[Xebo] Pre-fetch failed (will retry on fetchAndPresentSurvey):', err);
+    }
+  }
+
+  // ─── Main flow ─────────────────────────────────────────────────────────────
+
+  async fetchAndPresentSurvey(): Promise<void> {
+    try {
+      // If already pre-fetched, show instantly
+      if (this.survey && this.resolvedCollectorUUID) {
+        console.log('[Xebo] Survey already cached — showing instantly');
+        this.currentAnswers = [];
+        this.currentQuestionIndex = 0;
+        this.surveyStartTime = new Date().toISOString();
+        this.emit(XEBO_EVENTS.SURVEY_LOADED, this.survey);
+        this._setVisible(true);
+        return;
+      }
+
+      // Not cached yet — fetch now
+      console.log('[Xebo] Step 1: fetchCollector');
+      const collector = await fetchCollector(this.baseURL, this.collectorId, this.apiKey);
+      this.resolvedCollectorUUID = collector.uuid;
+      this.resolvedCollectorMongoId = collector.mongoId;
+
+      console.log('[Xebo] Step 2: fetchSurvey');
+      const survey = await fetchSurvey(this.baseURL, collector.surveyId, this.apiKey);
+      this.survey = survey;
+      this.currentAnswers = [];
+      this.currentQuestionIndex = 0;
+      this.surveyStartTime = new Date().toISOString();
+
+      this.emit(XEBO_EVENTS.SURVEY_LOADED, survey);
+      this._setVisible(true);
+    } catch (err) {
+      console.error('[Xebo] fetchAndPresentSurvey failed:', err);
+    }
+  }
+
+  // ─── Answer recording ──────────────────────────────────────────────────────
+
+  recordAnswer(answer: XeboAnswer): void {
+    const idx = this.currentAnswers.findIndex(a => a.questionId === answer.questionId);
+    if (idx >= 0) {
+      this.currentAnswers[idx] = answer;
+    } else {
+      this.currentAnswers.push(answer);
+    }
+  }
+
+  // ─── Navigation ────────────────────────────────────────────────────────────
+
+  nextQuestion(): void {
+    if (!this.survey) return;
+    const next = this.currentQuestionIndex + 1;
+    if (next < this.survey.questions.length) {
+      this.currentQuestionIndex = next;
+      this.emit(XEBO_EVENTS.QUESTION_CHANGED, this.currentQuestionIndex);
+
+      // If this is the thank-you question, submit in the background
+      const q = this.survey.questions[this.currentQuestionIndex];
+      if (q?.id === 'thank_you_auto') {
+        this._submitCurrentSession();
+      }
+    }
+  }
+
+  // ─── Submission ────────────────────────────────────────────────────────────
+
+  private async _submitCurrentSession(): Promise<void> {
+    if (!this.survey) return;
+
+    const endTime = new Date().toISOString();
+
+    try {
+      const result = await submitResponse(
+        this.feedbackBaseURL,
+        this.survey.id,
+        this.resolvedCollectorUUID,
+        this.apiKey,
+        this.currentAnswers
+      );
+
+      if (!result.ok) {
+        throw new Error(`HTTP ${result.status}`);
+      }
+
+      const respData = result.responseJson as { data?: { responseId?: string; created?: string } };
+      console.log('[Xebo] Response data:', {
+        responseId: respData?.data?.responseId,
+        created: respData?.data?.created,
+      });
+    } catch (err) {
+      console.error('[Xebo] Submission failed — queuing offline:', err);
+      await this._enqueueOffline(endTime);
+    }
+  }
+
+  private async _enqueueOffline(endTime: string): Promise<void> {
+    if (!this.survey) return;
+
+    const queued: XeboQueuedResponse = {
+      responseId: uuidv4(),
+      surveyId: this.survey.id,
+      collectorUUID: this.resolvedCollectorUUID,
+      mode: 'React Native SDK',
+      status: 'complete',
+      startTime: this.surveyStartTime,
+      endTime,
+      answers: [...this.currentAnswers],
+    };
+
+    await XeboOfflineQueue.enqueue(queued);
+  }
+
+  // ─── Flush queue ───────────────────────────────────────────────────────────
+
+  async flushQueue(): Promise<void> {
+    const all = await XeboOfflineQueue.getAll();
+    if (all.length === 0) return;
+
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log(`[Xebo Offline] Flushing ${all.length} queued response(s)`);
+
+    const failed: XeboQueuedResponse[] = [];
+
+    for (const queued of all) {
+      try {
+        const result = await submitResponse(
+          this.feedbackBaseURL,
+          queued.surveyId,
+          queued.collectorUUID,
+          this.apiKey,
+          queued.answers
+        );
+        if (!result.ok) throw new Error(`HTTP ${result.status}`);
+        console.log('[Xebo Offline] Flushed response:', queued.responseId);
+      } catch (err) {
+        console.error('[Xebo Offline] Retry failed for:', queued.responseId, err);
+        failed.push(queued);
+      }
+    }
+
+    await XeboOfflineQueue.saveAll(failed);
+    console.log(`[Xebo Offline] Flush complete — ${failed.length} still pending`);
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  }
+
+  // ─── Modal visibility ──────────────────────────────────────────────────────
+
+  private _setVisible(visible: boolean): void {
+    this.surveyVisible = visible;
+    this.emit(XEBO_EVENTS.SURVEY_VISIBLE, visible);
+  }
+
+  dismissSurvey(): void {
+    this._setVisible(false);
+    this.emit(XEBO_EVENTS.SURVEY_DISMISSED);
+  }
+}
+
+export const XeboSurveyManager = new XeboSurveyManagerClass();