ComuniTEA AI: Magic Expand, Insights, and ElevenLabs TTS

{
  pictogramLabels: string[];                              // Labels in selection order
  vocabularyLevel?: "BASICO" | "INTERMEDIO" | "AVANZADO"; // Defaults to "INTERMEDIO"
  timeOfDay?: "mañana" | "tarde" | "noche";               // Optional context
  lastRoutine?: string;                                    // Label of last completed routine
  phraseIntent?: "formador" | "tablero";                   // Optional style modifier
}

{ expandedText: string }

// Model configured via OPENAI_FRASE_MODEL secret (default: "gpt-5.4-nano")
model: OPENAI_FRASE_MODEL
temperature: 0.35
max_tokens: phraseIntent === "tablero" ? 90 : 70

// From features/vocabulario/hooks/useMagicExpand.ts

const labels = sentence.map(item => item.speechText || item.label);
const timeOfDay = getTimeOfDay();       // "mañana" | "tarde" | "noche"
const lastRoutine = rutinas.filter(r => r.completed).slice(-1)[0]?.label;

// Refresh session token if expired
let { data: { session } } = await supabase.auth.getSession();
if (!session?.access_token) {
  const { data: refreshed } = await supabase.auth.refreshSession();
  session = refreshed.session;
}

const res = await fetch(`${supabaseUrl}/functions/v1/ai-expand`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${session.access_token}`,
  },
  body: JSON.stringify({
    pictogramLabels: labels,
    vocabularyLevel: profile?.level ?? 'INTERMEDIO',
    timeOfDay,
    lastRoutine,
  }),
});

const { expandedText } = await res.json();
if (expandedText) {
  await speakFreeText(expandedText);
  logEvent('ai_expand', { latencyMs: Date.now() - startedAt, sentenceLength: sentence.length });
  logSentence(sentence.map(s => s.id));
}

{
  vocabularyLevel: "BASICO" | "INTERMEDIO" | "AVANZADO";
  sublevel: number;                   // Current game sub-level (1–5)
  avgSentenceLength: number;          // Average pictogram count per sentence (last 30 days)
  totalSentences: number;             // Total sentences logged in last 30 days
  topPictogramLabels: string[];       // Top 5 most-used pictogram labels
  unusedCategoryLabels: string[];     // Category labels with no use in >14 days
}

{ suggestions: string[] }

model: "gpt-4o-mini"
temperature: 0.7
max_tokens: 300

// System prompt excerpt:
// "Respond ONLY with a JSON array of 3 strings. No additional explanations. Example:
// ["Suggestion 1.", "Suggestion 2.", "Suggestion 3."]"

{
  text: string;      // Text to synthesize (non-empty)
  voiceId?: string;  // ElevenLabs voice ID — defaults to the "Samanta" feminine voice
  speed?: number;    // Playback speed multiplier — clamped to [0.5, 2.0], defaults to 1.0
}

Content-Type: audio/mpeg
Body: <MP3 audio buffer>

{ error: string }

{
  model_id: "eleven_multilingual_v2",
  voice_settings: {
    stability: 0.5,
    similarity_boost: 0.75,
    style: 0.0,
    use_speaker_boost: true,
    speed: ttsSpeed,    // From request body
  }
}

// From features/vocabulario/hooks/useSpeech.ts

const { data: { session } } = await supabase.auth.getSession();
const token = session?.access_token || process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY;
const edgeUrl = `${process.env.EXPO_PUBLIC_SUPABASE_URL}/functions/v1/elevenlabs-tts`;

const response = await fetch(edgeUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`,
  },
  body: JSON.stringify({ text, voiceId, speed: ttsSpeed }),
});

if (!response.ok) {
  // Falls through to expo-speech system TTS
  return new Promise((resolve) => fallbackSpeech(text, resolve));
}

// Write MP3 to a temp file, play with expo-audio
const arrayBuffer = await response.arrayBuffer();
const base64 = btoa(String.fromCharCode(...new Uint8Array(arrayBuffer)));
const fileUri = FileSystem.documentDirectory + `temp_speech_${Date.now()}.mp3`;
await FileSystem.writeAsStringAsync(fileUri, base64, { encoding: FileSystem.EncodingType.Base64 });

const newSound = createAudioPlayer(normalizeFileUriForAudio(fileUri));
await playAudioPlayerUntilDone(newSound, 120_000);
FileSystem.deleteAsync(fileUri, { idempotent: true }).catch(() => {});

1. Bundled MP3 clip (getAudioAssets — fastest, offline-safe)
      ↓ no clip found
2. elevenlabs-tts Edge Function (neural voice)
      ↓ no network OR HTTP error OR ELEVENLABS_API_KEY missing
3. expo-speech (system TTS, es-MX, pitch adjusted per voice profile)

// Success
{ success: true }

// Error
{ error: "Failed to delete user data" }  // HTTP 500
{ error: "Unauthorized" }                 // HTTP 401

// lib/offlineQueue.ts

export type QueuedEvent =
  | {
      type: 'stat';
      user_id: string;
      event_type: string;    // e.g. "ai_expand", "pictogram_tap"
      created_at: string;    // ISO timestamp captured at event time
      category_id?: string;
      sentence_length?: number;
      response_latency_ms?: number;
    }
  | {
      type: 'sentence';
      user_id: string;
      pictogram_ids: string[];
      created_at: string;
    };

/** Appends an event to the AsyncStorage queue. Fire-and-forget safe. */
export async function enqueueEvent(event: QueuedEvent): Promise<void>;

/** Flushes all pending events to Supabase. Clears the queue only on full success. */
export async function flushQueue(): Promise<void>;

const results = await Promise.allSettled([
  stats.length > 0
    ? supabase.from('usage_stats').insert(stats)
    : Promise.resolve(),
  sentences.length > 0
    ? supabase.from('sentence_log').insert(sentences)
    : Promise.resolve(),
]);

if (results.every(r => r.status === 'fulfilled')) {
  await AsyncStorage.removeItem(QUEUE_KEY);
}

// lib/auditLog.ts

export async function auditLog(
  userId: string,
  field: string,    // The setting or action name (e.g. "vocabulary_pictogram_toggle")
  oldValue: string, // Previous value as a string
  newValue: string, // New value as a string
): Promise<void>

config_audit_log (
  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id     uuid REFERENCES auth.users,
  field_name  text,
  old_value   text,
  new_value   text,
  created_at  timestamptz DEFAULT now()
)

import { auditLog } from '@/lib/auditLog';

// Inside a mutation function:
await auditLog(
  user.id,
  'vocabulary_pictogram_toggle',
  'enabled',   // old value
  'disabled',  // new value
);