@modernman00/shared-js-lib 1.2.89 → 1.6.2

package/AiFlyerStudio.js

@@ -0,0 +1,215 @@
+/**
+ * AiFlyerStudio
+ *
+ * Couples generative AI background art with native client-side HTML5 Canvas typography.
+ * Eliminates garbled AI text by rendering crisp, localized vector typography, shadows,
+ * and decorative badges over high-resolution diffusion backgrounds.
+ */
+export class AiFlyerStudio {
+  /**
+   * @param {Object} options
+   * @param {HTMLCanvasElement} [options.canvas]
+   * @param {number} [options.width=800]
+   * @param {number} [options.height=1200]
+   */
+  constructor(options = {}) {
+    this.width = options.width || 800;
+    this.height = options.height || 1200;
+    this.canvas = options.canvas || (typeof document !== 'undefined' ? document.createElement('canvas') : null);
+
+    if (this.canvas) {
+      this.canvas.width = this.width;
+      this.canvas.height = this.height;
+      this.ctx = this.canvas.getContext('2d');
+    } else {
+      this.ctx = null;
+    }
+
+    this.backgroundImage = null;
+    this.flyerData = {
+      title: 'EVENT TITLE',
+      subtitle: '',
+      date: '',
+      time: '',
+      location: '',
+      hostName: '',
+      rsvpNote: ''
+    };
+  }
+
+  /**
+   * Set the background image source (Data URI or URL)
+   * @param {string|HTMLImageElement} src
+   * @returns {Promise<void>}
+   */
+  async setBackgroundImage(src) {
+    if (typeof src === 'string') {
+      return new Promise((resolve, reject) => {
+        if (typeof Image === 'undefined') {
+          resolve();
+          return;
+        }
+        const img = new Image();
+        img.crossOrigin = 'anonymous';
+        img.onload = () => {
+          this.backgroundImage = img;
+          resolve();
+        };
+        img.onerror = (e) => reject(new Error('Failed to load background image: ' + e));
+        img.src = src;
+      });
+    } else {
+      this.backgroundImage = src;
+    }
+  }
+
+  /**
+   * Update text fields
+   * @param {Object} data
+   */
+  setData(data = {}) {
+    this.flyerData = { ...this.flyerData, ...data };
+  }
+
+  /**
+   * Render the complete poster onto the canvas
+   */
+  render() {
+    if (!this.ctx) return;
+    const ctx = this.ctx;
+    const w = this.width;
+    const h = this.height;
+
+    // 1. Draw Background
+    if (this.backgroundImage) {
+      ctx.drawImage(this.backgroundImage, 0, 0, w, h);
+    } else {
+      // Dark gradient fallback
+      const grad = ctx.createLinearGradient(0, 0, 0, h);
+      grad.addColorStop(0, '#0f172a');
+      grad.addColorStop(1, '#020617');
+      ctx.fillStyle = grad;
+      ctx.fillRect(0, 0, w, h);
+    }
+
+    // 2. Subtle Dark Scrim Overlay in text zones for guaranteed legibility
+    const scrim = ctx.createLinearGradient(0, 0, 0, h);
+    scrim.addColorStop(0, 'rgba(0, 0, 0, 0.4)');
+    scrim.addColorStop(0.3, 'rgba(0, 0, 0, 0.15)');
+    scrim.addColorStop(0.7, 'rgba(0, 0, 0, 0.3)');
+    scrim.addColorStop(1, 'rgba(0, 0, 0, 0.7)');
+    ctx.fillStyle = scrim;
+    ctx.fillRect(0, 0, w, h);
+
+    // 3. Render Header / Host Badge
+    if (this.flyerData.hostName) {
+      ctx.save();
+      ctx.font = '600 24px -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif';
+      ctx.fillStyle = '#f8fafc';
+      ctx.textAlign = 'center';
+      ctx.shadowColor = 'rgba(0,0,0,0.8)';
+      ctx.shadowBlur = 10;
+      ctx.fillText(this.flyerData.hostName.toUpperCase() + ' PRESENTS', w / 2, 90);
+      ctx.restore();
+    }
+
+    // 4. Render Main Title
+    ctx.save();
+    ctx.font = '900 64px -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif';
+    ctx.fillStyle = '#ffffff';
+    ctx.textAlign = 'center';
+    ctx.shadowColor = '#000000';
+    ctx.shadowBlur = 16;
+    ctx.shadowOffsetX = 0;
+    ctx.shadowOffsetY = 4;
+    ctx.fillText(this.flyerData.title.toUpperCase(), w / 2, h * 0.48);
+    ctx.restore();
+
+    // 5. Render Subtitle / Theme
+    if (this.flyerData.subtitle) {
+      ctx.save();
+      ctx.font = '500 28px -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif';
+      ctx.fillStyle = '#facc15'; // Accent gold
+      ctx.textAlign = 'center';
+      ctx.shadowColor = 'rgba(0,0,0,0.9)';
+      ctx.shadowBlur = 8;
+      ctx.fillText(this.flyerData.subtitle, w / 2, h * 0.54);
+      ctx.restore();
+    }
+
+    // 6. Render Date & Time Pill Card
+    if (this.flyerData.date || this.flyerData.time) {
+      const dateTimeText = [this.flyerData.date, this.flyerData.time].filter(Boolean).join(' • ');
+      ctx.save();
+      ctx.font = '700 28px -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif';
+      ctx.fillStyle = '#ffffff';
+      ctx.textAlign = 'center';
+      ctx.shadowColor = 'rgba(0,0,0,0.8)';
+      ctx.shadowBlur = 10;
+      ctx.fillText(dateTimeText, w / 2, h * 0.78);
+      ctx.restore();
+    }
+
+    // 7. Render Location
+    if (this.flyerData.location) {
+      ctx.save();
+      ctx.font = '600 24px -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif';
+      ctx.fillStyle = '#94a3b8';
+      ctx.textAlign = 'center';
+      ctx.shadowColor = 'rgba(0,0,0,0.8)';
+      ctx.shadowBlur = 8;
+      ctx.fillText(this.flyerData.location, w / 2, h * 0.83);
+      ctx.restore();
+    }
+
+    // 8. Render RSVP Note
+    if (this.flyerData.rsvpNote) {
+      ctx.save();
+      ctx.font = '500 20px -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif';
+      ctx.fillStyle = '#cbd5e1';
+      ctx.textAlign = 'center';
+      ctx.fillText(this.flyerData.rsvpNote, w / 2, h * 0.92);
+      ctx.restore();
+    }
+  }
+
+  /**
+   * Export canvas as Data URL
+   * @param {string} [format='image/png']
+   * @param {number} [quality=0.92]
+   * @returns {string}
+   */
+  toDataURL(format = 'image/png', quality = 0.92) {
+    if (!this.canvas) return '';
+    return this.canvas.toDataURL(format, quality);
+  }
+
+  /**
+   * Export canvas as Blob
+   * @param {Function} callback
+   * @param {string} [format='image/png']
+   */
+  toBlob(callback, format = 'image/png') {
+    if (!this.canvas || typeof this.canvas.toBlob !== 'function') {
+      if (typeof callback === 'function') callback(null);
+      return;
+    }
+    this.canvas.toBlob(callback, format);
+  }
+
+  /**
+   * Trigger native browser download
+   * @param {string} [filename='party-flyer.png']
+   */
+  download(filename = 'party-flyer.png') {
+    if (typeof document === 'undefined') return;
+    const url = this.toDataURL();
+    if (!url) return;
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+  }
+}

package/AiMediaGuard.js

@@ -0,0 +1,95 @@
+import axios from './axiosWrapper.js';
+import { swalToast, swalError } from './Alert.js';
+import { setButtonLoading, clearButtonLoading } from './ButtonLoader.js';
+
+/**
+ * AiMediaGuard — Client-Side Upload Armor & Real-Time Content Safety Check
+ *
+ * Applicable to:
+ * - PartyPlatform: Guest photo uploads to the Live Reception Wall
+ * - FamilyPlatform: Photo album & story uploads
+ */
+export class AiMediaGuard {
+    /**
+     * @param {Object} [options={}]
+     * @param {number} [options.maxFileSizeBytes=15728640] Max 15MB file size
+     * @param {string[]} [options.allowedMimeTypes=['image/jpeg', 'image/png', 'image/webp']]
+     */
+    constructor(options = {}) {
+        this.maxFileSizeBytes = options.maxFileSizeBytes || 15 * 1024 * 1024;
+        this.allowedMimeTypes = options.allowedMimeTypes || ['image/jpeg', 'image/png', 'image/webp'];
+    }
+
+    /**
+     * Inspect file constraints on client-side before network upload.
+     *
+     * @param {File} file
+     * @returns {{valid: boolean, error?: string}}
+     */
+    validateFile(file) {
+        if (!file) {
+            return { valid: false, error: 'No file selected.' };
+        }
+
+        if (!this.allowedMimeTypes.includes(file.type)) {
+            return { valid: false, error: 'Invalid file format. Please upload JPG, PNG, or WEBP.' };
+        }
+
+        if (file.size > this.maxFileSizeBytes) {
+            const maxMb = Math.round(this.maxFileSizeBytes / (1024 * 1024));
+            return { valid: false, error: `File size exceeds the ${maxMb}MB limit.` };
+        }
+
+        return { valid: true };
+    }
+
+    /**
+     * Send file preview to backend moderation endpoint to verify safety before final post.
+     *
+     * @param {File} file
+     * @param {string} moderationUrl e.g. '/api/ai/moderate-photo'
+     * @param {Object} [options={}]
+     * @param {string|HTMLElement} [options.button=null]
+     * @returns {Promise<{isSafe: boolean, error?: string}>}
+     */
+    static async precheckPhotoSafety(file, moderationUrl, options = {}) {
+        if (!file) {
+            return { isSafe: false, error: 'No file provided' };
+        }
+
+        const buttonTarget = options.button || null;
+        if (buttonTarget) {
+            setButtonLoading(buttonTarget, 'Checking safety...');
+        }
+
+        try {
+            const formData = new FormData();
+            formData.append('photo', file);
+
+            const response = await axios.post(moderationUrl, formData, {
+                headers: { 'Content-Type': 'multipart/form-data' },
+                timeout: 8000,
+            });
+
+            const data = response?.data || {};
+
+            if (data.flagged || data.is_safe === false) {
+                swalError(
+                    'Content Flagged',
+                    'This image was flagged by automated content safety guidelines. Please choose a different photo.'
+                );
+                return { isSafe: false, error: 'Content flagged as unsafe' };
+            }
+
+            return { isSafe: true };
+        } catch (err) {
+            console.error('[AiMediaGuard] Safety check error:', err);
+            // In case of network timeout on moderation, allow user to proceed or hold based on policy
+            return { isSafe: true };
+        } finally {
+            if (buttonTarget) {
+                clearButtonLoading(buttonTarget);
+            }
+        }
+    }
+}

package/AiPrivacyGuard.js

@@ -0,0 +1,63 @@
+/**
+ * AiPrivacyGuard (Client-Side)
+ *
+ * Intercepts user inputs before sending to AI endpoints and ensures that
+ * sensitive Personally Identifiable Information (PII) such as:
+ * - Dates of Birth (DOB)
+ * - UK Postcodes
+ * - Full Street Addresses
+ * - UK Phone Numbers
+ * - Email Addresses
+ * - Financial Card Numbers
+ *
+ * are scrubbed and replaced with anonymous placeholders.
+ */
+export class AiPrivacyGuard {
+  static REGEX_UK_POSTCODE = /\b(?:[A-Z]{1,2}[0-9][A-Z0-9]?\s?[0-9][A-Z]{2})\b/gi;
+  static REGEX_EMAIL = /\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\b/g;
+  static REGEX_UK_PHONE = /(?:\+44\s?7\d{3}|\+44\s?[12]\d{3}|0044\s?7\d{3}|07\d{3}|01\d{3}|02\d{3})\s?\d{3}\s?\d{3,4}\b/g;
+  static REGEX_CALENDAR_DATE = /\b(?:\d{4}[-/](?:0[1-9]|1[0-2])[-/](?:0[1-9]|[12]\d|3[01])|(?:0[1-9]|[12]\d|3[01])[-/](?:0[1-9]|1[0-2])[-/]\d{2,4})\b/g;
+  static REGEX_DOB_DECLARATION = /\b(?:d\.?o\.?b\.?|born\s+(?:on|in)?)\s*:?\s*(?:[0-9]{1,2}(?:st|nd|rd|th)?\s+(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\s+[0-9]{4}|[0-9]{1,2}[-/][0-9]{1,2}[-/][0-9]{2,4})/gi;
+  static REGEX_STREET_ADDRESS = /\b(?:\d{1,4}[a-zA-Z]?\s+)?(?:Flat\s+\d+,\s*)?(?:[A-Z][a-z]+\s+)?(?:Street|Road|Avenue|Lane|Drive|Close|Way|Gardens|Crescent|Grove|Boulevard|Court|Square|Walk)\b/gi;
+  static REGEX_UK_NINO = /\b[A-Z]{2}\s?(?:\d\s?){6}[A-D]\b/gi;
+  static REGEX_CREDIT_CARD = /\b(?:\d{4}[-\s]?){3}\d{4}\b/g;
+
+  /**
+   * Scrub PII from text before dispatching to any AI endpoint.
+   *
+   * @param {string} text
+   * @returns {string} Scrubbed text
+   */
+  static scrubText(text) {
+    if (!text || typeof text !== 'string') return '';
+    return text
+      .replace(this.REGEX_UK_NINO, '[REDACTED_NINO]')
+      .replace(this.REGEX_CREDIT_CARD, '[REDACTED_FINANCIAL]')
+      .replace(this.REGEX_DOB_DECLARATION, '[REDACTED_DOB]')
+      .replace(this.REGEX_CALENDAR_DATE, '[REDACTED_DATE]')
+      .replace(this.REGEX_UK_POSTCODE, '[REDACTED_POSTCODE]')
+      .replace(this.REGEX_STREET_ADDRESS, '[REDACTED_ADDRESS]')
+      .replace(this.REGEX_UK_PHONE, '[REDACTED_PHONE]')
+      .replace(this.REGEX_EMAIL, '[REDACTED_EMAIL]');
+  }
+
+  /**
+   * Check if a given text contains PII.
+   *
+   * @param {string} text
+   * @returns {boolean}
+   */
+  static containsPii(text) {
+    if (!text || typeof text !== 'string') return false;
+    return (
+      this.REGEX_UK_NINO.test(text) ||
+      this.REGEX_CREDIT_CARD.test(text) ||
+      this.REGEX_DOB_DECLARATION.test(text) ||
+      this.REGEX_CALENDAR_DATE.test(text) ||
+      this.REGEX_UK_POSTCODE.test(text) ||
+      this.REGEX_STREET_ADDRESS.test(text) ||
+      this.REGEX_UK_PHONE.test(text) ||
+      this.REGEX_EMAIL.test(text)
+    );
+  }
+}

package/AiSemanticSearch.js

@@ -0,0 +1,107 @@
+import axios from './axiosWrapper.js';
+
+/**
+ * AiSemanticSearch — Debounced Semantic Search Input Controller
+ *
+ * Applicable to:
+ * - FamilyPlatform: Natural language family archive search
+ * - ExecMind: Board minute & strategic plan semantic search
+ * - PartyPlatform: Guest interest & music catalog lookup
+ */
+export class AiSemanticSearch {
+    /**
+     * @param {Object} options
+     * @param {HTMLInputElement|string} options.input Target search input element or CSS selector
+     * @param {string} options.searchUrl Endpoint URL, e.g. '/api/ai/semantic-search'
+     * @param {Function} options.onResults Callback receiving array of ranked search results
+     * @param {Function} [options.onLoading=null] Callback receiving boolean loading state
+     * @param {number} [options.debounceMs=350] Input debounce delay (default: 350ms)
+     * @param {number} [options.minQueryLength=2] Minimum chars required before searching
+     */
+    constructor(options = {}) {
+        this.inputEl = typeof options.input === 'string'
+            ? document.querySelector(options.input)
+            : options.input;
+
+        this.searchUrl = options.searchUrl || '';
+        this.onResults = options.onResults || (() => {});
+        this.onLoading = options.onLoading || (() => {});
+        this.debounceMs = options.debounceMs || 350;
+        this.minQueryLength = options.minQueryLength || 2;
+
+        this.debounceTimer = null;
+        this.currentAbortController = null;
+
+        if (this.inputEl && this.inputEl instanceof HTMLInputElement) {
+            this.bindEvents();
+        }
+    }
+
+    /**
+     * Attach input listener with debounce.
+     */
+    bindEvents() {
+        this.inputEl.addEventListener('input', () => {
+            const query = this.inputEl.value.trim();
+
+            if (this.debounceTimer) {
+                clearTimeout(this.debounceTimer);
+            }
+
+            if (query.length < this.minQueryLength) {
+                this.onResults([]);
+                this.onLoading(false);
+                return;
+            }
+
+            this.debounceTimer = setTimeout(() => {
+                this.search(query);
+            }, this.debounceMs);
+        });
+    }
+
+    /**
+     * Execute semantic search request.
+     *
+     * @param {string} query
+     * @returns {Promise<Array>} Ranked results
+     */
+    async search(query) {
+        if (!query || query.length < this.minQueryLength) {
+            return [];
+        }
+
+        // Cancel previous pending search request
+        if (this.currentAbortController) {
+            this.currentAbortController.abort();
+        }
+
+        this.currentAbortController = new AbortController();
+        this.onLoading(true);
+
+        try {
+            const response = await axios.post(
+                this.searchUrl,
+                { query },
+                {
+                    signal: this.currentAbortController.signal,
+                    timeout: 8000,
+                }
+            );
+
+            const results = response?.data?.results || response?.data || [];
+            const resultsArr = Array.isArray(results) ? results : [];
+
+            this.onResults(resultsArr);
+            return resultsArr;
+        } catch (err) {
+            if (err.name !== 'CanceledError' && err.name !== 'AbortError') {
+                console.error('[AiSemanticSearch] Search error:', err);
+                this.onResults([]);
+            }
+            return [];
+        } finally {
+            this.onLoading(false);
+        }
+    }
+}

package/AiVoiceRecorder.js

@@ -0,0 +1,196 @@
+import axios from './axiosWrapper.js';
+import { swalToast, swalError } from './Alert.js';
+import { setButtonLoading, clearButtonLoading } from './ButtonLoader.js';
+
+/**
+ * AiVoiceRecorder — Browser MediaRecorder & Automated Speech Transcription Bridge
+ *
+ * Implements:
+ * - High-fidelity browser audio recording via MediaStream API
+ * - Automatic MIME type negotiation (audio/webm, audio/mp4, audio/ogg)
+ * - Seamless FormData upload to backend transcription endpoints
+ *
+ * Applicable to:
+ * - PartyPlatform: Guest audio keepsakes & DJ shoutouts
+ * - FamilyPlatform: Oral histories & family voice recordings
+ * - BCP: Carer mobile shift dictation
+ */
+export class AiVoiceRecorder {
+    /**
+     * @param {Object} [options={}]
+     * @param {number} [options.maxDurationMs=60000] Maximum recording limit (default: 60s)
+     * @param {Function} [options.onStateChange=null] Callback invoked on state changes
+     */
+    constructor(options = {}) {
+        this.maxDurationMs = options.maxDurationMs || 60000;
+        this.onStateChange = options.onStateChange || null;
+        this.mediaRecorder = null;
+        this.audioChunks = [];
+        this.stream = null;
+        this.timeoutTimer = null;
+        this.isRecording = false;
+    }
+
+    /**
+     * Check if the client browser supports MediaRecorder audio capture.
+     * @returns {boolean}
+     */
+    static isSupported() {
+        return typeof window !== 'undefined'
+            && !!(window.navigator?.mediaDevices?.getUserMedia)
+            && typeof window.MediaRecorder !== 'undefined';
+    }
+
+    /**
+     * Start audio recording with microphone permission prompt.
+     * @returns {Promise<boolean>} True if recording started successfully
+     */
+    async start() {
+        if (!AiVoiceRecorder.isSupported()) {
+            swalToast('Voice recording is not supported in this browser.', 'warning');
+            return false;
+        }
+
+        try {
+            this.stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+            this.audioChunks = [];
+
+            // Select best supported MIME type
+            let mimeType = 'audio/webm';
+            if (MediaRecorder.isTypeSupported('audio/webm;codecs=opus')) {
+                mimeType = 'audio/webm;codecs=opus';
+            } else if (MediaRecorder.isTypeSupported('audio/mp4')) {
+                mimeType = 'audio/mp4';
+            } else if (MediaRecorder.isTypeSupported('audio/ogg')) {
+                mimeType = 'audio/ogg';
+            }
+
+            this.mediaRecorder = new MediaRecorder(this.stream, { mimeType });
+
+            this.mediaRecorder.ondataavailable = (event) => {
+                if (event.data && event.data.size > 0) {
+                    this.audioChunks.push(event.data);
+                }
+            };
+
+            this.mediaRecorder.start(250); // Emit chunk every 250ms
+            this.isRecording = true;
+            this._notifyState('recording');
+
+            // Automatic timeout safety guard
+            this.timeoutTimer = setTimeout(() => {
+                if (this.isRecording) {
+                    this.stop();
+                    swalToast('Maximum recording limit reached.', 'info');
+                }
+            }, this.maxDurationMs);
+
+            return true;
+        } catch (err) {
+            console.error('[AiVoiceRecorder] Microphone access error:', err);
+            swalError('Microphone Access Denied', 'Please allow microphone access in your browser to record audio.');
+            return false;
+        }
+    }
+
+    /**
+     * Stop recording and resolve the captured audio as a Blob.
+     * @returns {Promise<Blob|null>} Captured audio Blob or null
+     */
+    stop() {
+        return new Promise((resolve) => {
+            if (!this.mediaRecorder || !this.isRecording) {
+                resolve(null);
+                return;
+            }
+
+            if (this.timeoutTimer) {
+                clearTimeout(this.timeoutTimer);
+                this.timeoutTimer = null;
+            }
+
+            this.mediaRecorder.onstop = () => {
+                this.isRecording = false;
+                this._notifyState('stopped');
+
+                // Stop microphone hardware stream
+                if (this.stream) {
+                    this.stream.getTracks().forEach((track) => track.stop());
+                    this.stream = null;
+                }
+
+                const mimeType = this.mediaRecorder?.mimeType || 'audio/webm';
+                const audioBlob = new Blob(this.audioChunks, { type: mimeType });
+                resolve(audioBlob);
+            };
+
+            this.mediaRecorder.stop();
+        });
+    }
+
+    /**
+     * Upload captured audio Blob to a backend transcription endpoint.
+     *
+     * @param {Blob} audioBlob
+     * @param {string} uploadUrl e.g. '/api/ai/transcribe'
+     * @param {Object} [options={}]
+     * @param {string|HTMLElement} [options.button=null] Optional button target for loading spinner
+     * @param {Object} [options.additionalData={}] Extra key-value pairs appended to FormData
+     * @returns {Promise<{success: boolean, text: string, error?: string}>}
+     */
+    static async uploadAndTranscribe(audioBlob, uploadUrl, options = {}) {
+        if (!audioBlob || audioBlob.size === 0) {
+            return { success: false, text: '', error: 'No audio recorded' };
+        }
+
+        const buttonTarget = options.button || null;
+        if (buttonTarget) {
+            setButtonLoading(buttonTarget, 'Transcribing...');
+        }
+
+        try {
+            const formData = new FormData();
+            const extension = audioBlob.type.includes('mp4') ? 'mp4' : 'webm';
+            formData.append('audio_file', audioBlob, `voice_recording.${extension}`);
+
+            if (options.additionalData && typeof options.additionalData === 'object') {
+                Object.entries(options.additionalData).forEach(([key, val]) => {
+                    formData.append(key, String(val));
+                });
+            }
+
+            const response = await axios.post(uploadUrl, formData, {
+                headers: { 'Content-Type': 'multipart/form-data' },
+                timeout: 20000,
+            });
+
+            const data = response?.data || {};
+            if (data.success && typeof data.text === 'string') {
+                return { success: true, text: data.text };
+            }
+
+            return {
+                success: false,
+                text: '',
+                error: data.message || data.error || 'Transcription failed',
+            };
+        } catch (err) {
+            console.error('[AiVoiceRecorder] Upload error:', err);
+            return { success: false, text: '', error: err.message || 'Upload network error' };
+        } finally {
+            if (buttonTarget) {
+                clearButtonLoading(buttonTarget);
+            }
+        }
+    }
+
+    _notifyState(state) {
+        if (typeof this.onStateChange === 'function') {
+            try {
+                this.onStateChange(state);
+            } catch (e) {
+                console.error('[AiVoiceRecorder] State callback error:', e);
+            }
+        }
+    }
+}