@zevra/support-widget 0.2.0

package/src/tampon-erreurs.ts

@@ -0,0 +1,211 @@
+// ============================================================================
+// Les vingt dernières erreurs de console. PUR (le tampon), impur (la pose).
+// ============================================================================
+//
+// POURQUOI UN TAMPON, ET PAS UNE LECTURE AU MOMENT DU CLIC : la console d'un
+// navigateur n'est pas lisible depuis JavaScript. Ce qui s'y est affiché avant
+// l'ouverture du widget est perdu — or c'est exactement ce qu'on veut : la
+// pile d'erreurs qui a précédé « ça ne marche pas ». On garde donc une copie,
+// bornée, posée le plus tôt possible.
+//
+// ⚠️ CE TAMPON EST BRANCHÉ SUR LA CONSOLE DE L'APP HÔTE. Il ne doit JAMAIS
+// jeter : une exception dans `console.error` casserait le journal de l'app, et
+// l'app, et personne ne soupçonnerait le bouton « Aide ». D'où le try/catch
+// autour de chaque formatage, et le repli « [argument illisible] » plutôt
+// qu'une erreur propagée.
+
+/** Vingt entrées (PLAN.md §7 lot 5). Au-delà, ce n'est plus un contexte. */
+export const TAILLE_TAMPON = 20
+
+/** Une entrée plus longue que ça est une pile complète : elle noie le reste. */
+export const LONGUEUR_ENTREE = 300
+
+export type NiveauConsole = 'error' | 'warn' | 'exception' | 'rejet'
+
+const MARQUE_ILLISIBLE = '[argument illisible]'
+
+/**
+ * Rend un argument de console en texte. PUR, TOTAL — ne jette jamais.
+ *
+ * Chaque branche existe pour une valeur qui a réellement fait tomber un
+ * formateur naïf :
+ *   - un `Symbol` : `` `${valeur}` `` lève un TypeError (il faut `String()`) ;
+ *   - un objet circulaire, un `BigInt`, un getter qui jette : `JSON.stringify`
+ *     lève ;
+ *   - `Object.create(null)` n'a pas de `toString` : `String()` lève.
+ */
+export function formaterArgument(valeur: unknown): string {
+  try {
+    if (valeur === null) return 'null'
+    if (valeur === undefined) return 'undefined'
+    if (typeof valeur === 'string') return valeur
+    if (typeof valeur === 'symbol') return String(valeur)
+    if (typeof valeur === 'function') {
+      const nom = (valeur as { name?: string }).name
+      return `[fonction ${nom && nom !== '' ? nom : 'anonyme'}]`
+    }
+    if (valeur instanceof Error) return formaterErreur(valeur)
+    if (typeof valeur === 'object') {
+      const rendu = JSON.stringify(valeur)
+      // `JSON.stringify` rend `undefined` sur certaines valeurs (une fonction
+      // dans un tableau, un objet de symboles seuls) sans jeter : le repli
+      // doit couvrir ce cas-là aussi.
+      return rendu === undefined ? '[objet non sérialisable]' : rendu
+    }
+    return String(valeur)
+  } catch {
+    // Circulaire, BigInt, getter qui jette, objet sans prototype : l'important
+    // est que l'entrée existe et que le tampon survive.
+    try {
+      return typeof valeur === 'object' ? '[objet non sérialisable]' : MARQUE_ILLISIBLE
+    } catch {
+      return MARQUE_ILLISIBLE
+    }
+  }
+}
+
+/**
+ * Une erreur en une ligne : son nom, son message, et la PREMIÈRE ligne de
+ * pile.
+ *
+ * La pile entière ferait 4 Ko par entrée — vingt entrées suffiraient alors à
+ * dépasser à elles seules la limite de corps de l'API. La première ligne
+ * suffit à savoir d'où ça vient ; le reste est dans le navigateur de la
+ * personne, si on le lui demande.
+ */
+function formaterErreur(erreur: Error): string {
+  const base = `${erreur.name}: ${erreur.message}`
+  const pile = typeof erreur.stack === 'string' ? erreur.stack : ''
+  const lignes = pile.split('\n').map((l) => l.trim())
+  const premiereTrame = lignes.find((l) => l.startsWith('at '))
+  return premiereTrame ? `${base} — ${premiereTrame}` : base
+}
+
+/** Formate une entrée complète, horodatée. PUR. */
+export function formaterEntree(
+  niveau: NiveauConsole,
+  args: readonly unknown[],
+  horodatage?: Date,
+): string {
+  const corps = args.map(formaterArgument).join(' ')
+  const heure = horodatage ? `${horodatage.toISOString().slice(11, 19)} ` : ''
+  const ligne = `${heure}[${niveau}] ${corps}`
+  return ligne.length <= LONGUEUR_ENTREE ? ligne : `${ligne.slice(0, LONGUEUR_ENTREE - 1)}…`
+}
+
+/**
+ * Le tampon circulaire. PUR (aucune I/O), et incassable par construction.
+ */
+export class TamponErreurs {
+  private readonly entrees: string[] = []
+
+  constructor(private readonly taille: number = TAILLE_TAMPON) {}
+
+  /** Ajoute une entrée. Ne jette jamais : le formatage est déjà total. */
+  ajouter(niveau: NiveauConsole, args: readonly unknown[], horodatage?: Date): void {
+    try {
+      this.entrees.push(formaterEntree(niveau, args, horodatage))
+      // La plus ANCIENNE part : ce qui vient de se passer explique mieux que
+      // ce qui s'est passé au chargement de la page.
+      while (this.entrees.length > this.taille) this.entrees.shift()
+    } catch {
+      // Rien. Un tampon qui jette casse la console de l'app hôte.
+    }
+  }
+
+  /** Les entrées, de la plus ancienne à la plus récente. Copie défensive. */
+  lire(): string[] {
+    return [...this.entrees]
+  }
+
+  vider(): void {
+    this.entrees.length = 0
+  }
+}
+
+/**
+ * Le tampon partagé du widget.
+ *
+ * ⚠️ UN SEUL, au niveau du module : deux tampons se partageraient les erreurs
+ * au hasard de l'ordre des poses, et chacun en aurait la moitié.
+ */
+export const tamponErreurs = new TamponErreurs()
+
+/* ─── La pose (impure) ──────────────────────────────────────────────── */
+
+interface ConsoleObservee {
+  error?: (...args: unknown[]) => void
+  warn?: (...args: unknown[]) => void
+}
+
+export interface PorteePose {
+  console?: ConsoleObservee
+  addEventListener?: (type: string, ecouteur: (evenement: unknown) => void) => void
+  removeEventListener?: (type: string, ecouteur: (evenement: unknown) => void) => void
+}
+
+let poseFaite = false
+
+/**
+ * Branche le tampon sur la console et sur les erreurs non rattrapées.
+ *
+ * ⚠️ À APPELER LE PLUS TÔT POSSIBLE dans l'app hôte, avant le rendu — pas
+ * seulement au montage du widget. Posé au montage, le tampon manque
+ * exactement les erreurs du démarrage : celles qu'on signale.
+ *
+ * Rend la fonction de dépose. Idempotent : deux appels ne doublent pas les
+ * entrées (c'est ce qui arriverait si l'app le pose ET que le widget se monte).
+ */
+export function installerTamponErreurs(
+  portee: PorteePose = globalThis as unknown as PorteePose,
+  tampon: TamponErreurs = tamponErreurs,
+): () => void {
+  if (poseFaite) return () => {}
+  const console_ = portee?.console
+  if (!console_) return () => {}
+
+  // ⚠️ On garde la référence ORIGINALE, pas une copie liée : c'est elle qu'on
+  // remettra à la dépose. Restaurer un `bind()` laisserait à l'app une
+  // fonction qui n'est plus la sienne — un autre outil posé par-dessus (une
+  // sonde d'erreurs, un test qui espionne la console) ne se retrouverait plus.
+  // L'appel, lui, passe par `apply` avec la console pour `this`.
+  const erreurOrigine = console_.error
+  const avertissementOrigine = console_.warn
+
+  if (erreurOrigine) {
+    console_.error = (...args: unknown[]) => {
+      tampon.ajouter('error', args, new Date())
+      erreurOrigine.apply(console_, args)
+    }
+  }
+  if (avertissementOrigine) {
+    console_.warn = (...args: unknown[]) => {
+      tampon.ajouter('warn', args, new Date())
+      avertissementOrigine.apply(console_, args)
+    }
+  }
+
+  // Une exception non rattrapée n'atteint PAS `console.error` du point de vue
+  // du code : le navigateur l'affiche lui-même. Sans ces deux écouteurs, le
+  // tampon serait vide précisément quand l'app vient de casser.
+  const surErreur = (evenement: unknown) => {
+    const e = evenement as { message?: string; error?: unknown }
+    tampon.ajouter('exception', [e?.error ?? e?.message ?? evenement], new Date())
+  }
+  const surRejet = (evenement: unknown) => {
+    const e = evenement as { reason?: unknown }
+    tampon.ajouter('rejet', [e?.reason ?? evenement], new Date())
+  }
+  portee.addEventListener?.('error', surErreur)
+  portee.addEventListener?.('unhandledrejection', surRejet)
+
+  poseFaite = true
+
+  return () => {
+    if (erreurOrigine) console_.error = erreurOrigine
+    if (avertissementOrigine) console_.warn = avertissementOrigine
+    portee.removeEventListener?.('error', surErreur)
+    portee.removeEventListener?.('unhandledrejection', surRejet)
+    poseFaite = false
+  }
+}

package/src/types.ts

@@ -0,0 +1,105 @@
+// ============================================================================
+// Ce que le widget voit passer. Le fil, vu du navigateur.
+// ============================================================================
+//
+// ⚠️ Ces types DOUBLENT ceux de `@zevra/support`, et c'est délibéré : le
+// widget ne doit avoir aucun lien, même de type, avec le SDK serveur. Un
+// `import type` suffirait à faire remonter le paquet serveur dans le graphe de
+// dépendances de l'app cliente — le typage disparaît à la compilation, mais
+// l'entrée dans `package.json`, elle, reste, et c'est par là qu'un jour
+// quelqu'un importera « juste une fonction ». Le paquet qui détient la clé
+// n'est pas installable dans un bundle de navigateur ; ce paquet-ci l'est.
+//
+// La forme vient de PLAN.md §4. Elle est rendue par les routes de relais, qui
+// transmettent la réponse de l'API v1 telle quelle.
+
+export type TypeDemande = 'bug' | 'question' | 'idee' | 'beta'
+
+export type StatutDemande =
+  | 'nouvelle'
+  | 'ouverte'
+  | 'en_attente_requerant'
+  | 'resolue'
+  | 'fermee'
+
+export type AuteurMessage = 'requerant' | 'equipe' | 'ia' | 'systeme'
+
+export const LIBELLES_TYPE: Record<TypeDemande, string> = {
+  bug: 'Un problème',
+  question: 'Une question',
+  idee: 'Une idée',
+  beta: 'Retour de bêta',
+}
+
+export const LIBELLES_STATUT: Record<StatutDemande, string> = {
+  nouvelle: 'Nouvelle',
+  ouverte: 'En cours',
+  en_attente_requerant: 'Votre réponse est attendue',
+  resolue: 'Résolue',
+  fermee: 'Fermée',
+}
+
+export interface ContexteReleve {
+  url?: string
+  user_agent?: string
+  version?: string
+  os?: string
+  viewport?: string
+  langue?: string
+  console?: string[]
+  extra?: Record<string, unknown>
+}
+
+export interface ResumeDemande {
+  id: string
+  reference: string
+  type: TypeDemande
+  statut: StatutDemande
+  titre: string
+  created_at: string
+  dernier_message_at: string
+}
+
+export interface MessageLu {
+  id: string
+  auteur: AuteurMessage
+  corps: string
+  created_at: string
+}
+
+export interface PieceLue {
+  id: string
+  nom: string
+  type_mime: string
+  octets: number
+  url?: string | null
+}
+
+export interface DemandeLue {
+  demande: ResumeDemande & { description: string }
+  messages: MessageLu[]
+  pieces: PieceLue[]
+}
+
+export interface ScenarioCampagne {
+  cle: string
+  titre: string
+  etapes: string[]
+}
+
+export interface ProgrammeActif {
+  programme?: { id: string; nom: string; description?: string | null } | null
+  campagne?: {
+    id: string
+    titre: string
+    consignes?: string | null
+    scenarios: ScenarioCampagne[]
+  } | null
+}
+
+/** L'enveloppe d'erreur, identique côté API v1 et côté relais. */
+export interface ErreurDuRelais {
+  code: string
+  message: string
+  champs?: Record<string, string>
+}

package/src/validation.ts

@@ -0,0 +1,113 @@
+// ============================================================================
+// Ce qu'un signalement doit contenir pour valoir la peine d'être envoyé. PUR.
+// ============================================================================
+//
+// Le serveur revérifie tout (c'est lui qui décide), et c'est bien pour ça que
+// cette validation-ci existe : elle ne protège pas la base, elle évite un
+// aller-retour et un message générique là où on peut dire précisément ce qui
+// manque, à côté du champ concerné.
+//
+// ⚠️ On rend TOUS les défauts d'un coup, comme `verifierDemandeEntrante` du
+// socle. Corriger un champ pour découvrir le suivant à chaque envoi est la
+// manière la plus sûre de faire abandonner quelqu'un qui voulait signaler un
+// bug.
+
+import type { TypeDemande } from './types'
+
+/** Le schéma borne `demande.titre` à 200 (PLAN.md §3). */
+export const LONGUEUR_TITRE = 200
+
+/** La description part dans un corps borné à 256 Ko, contexte compris. */
+export const LONGUEUR_DESCRIPTION = 5000
+
+/** Nombre minimal de caractères pour qu'une description diagnostique. */
+export const MINIMUM_DESCRIPTION = 10
+
+const TYPES: readonly string[] = ['bug', 'question', 'idee', 'beta']
+
+export interface SaisieSignalement {
+  type?: string | null
+  titre?: string | null
+  description?: string | null
+  /** Retour de bêta : 1 à 5, ou rien. */
+  score?: number | null
+}
+
+/**
+ * Rend un message par champ fautif. `{}` = rien à redire. PUR.
+ *
+ * Les messages sont écrits pour la personne qui remplit le formulaire, pas
+ * pour le journal : ils disent quoi faire, pas ce qui a échoué.
+ */
+export function verifierSignalement(saisie: SaisieSignalement): Record<string, string> {
+  const defauts: Record<string, string> = {}
+
+  // ⚠️ Type et titre FACULTATIFS : le formulaire ne demande plus qu'une
+  // phrase, et c'est le triage IA de Support qui les pose. Ils ne sont
+  // vérifiés que s'ils sont fournis (pré-remplissage d'un retour de bêta).
+  if (saisie.type !== null && saisie.type !== undefined && !TYPES.includes(saisie.type)) {
+    defauts.type = 'Choisissez de quoi il s’agit.'
+  }
+
+  const titre = (saisie.titre ?? '').trim()
+  if (titre.length > LONGUEUR_TITRE) {
+    // On DIT le dépassement plutôt que de tronquer en silence : un titre coupé
+    // au milieu d'un mot dans la boîte de l'équipe a l'air d'un bug du support.
+    defauts.titre = `Le titre dépasse ${LONGUEUR_TITRE} caractères (${titre.length}).`
+  }
+
+  const description = (saisie.description ?? '').trim()
+  if (description === '') {
+    defauts.description = 'Dites-nous en une phrase ce qui se passe.'
+  } else if (description.length < MINIMUM_DESCRIPTION) {
+    defauts.description = 'Quelques mots de plus aideraient beaucoup.'
+  } else if (description.length > LONGUEUR_DESCRIPTION) {
+    defauts.description = `La description dépasse ${LONGUEUR_DESCRIPTION} caractères (${description.length}). Une pièce jointe passe mieux qu’un copier-coller.`
+  }
+
+  // Le score est FACULTATIF : absent, il ne vaut pas zéro. Un zéro écrit à la
+  // place d'une absence ferait descendre la moyenne d'une campagne de bêta
+  // avec des notes que personne n'a données.
+  if (saisie.score !== null && saisie.score !== undefined) {
+    const score = Number(saisie.score)
+    if (!Number.isFinite(score) || score < 1 || score > 5 || !Number.isInteger(score)) {
+      defauts.score = 'La note va de 1 à 5.'
+    }
+  }
+
+  return defauts
+}
+
+/** `true` quand la saisie peut partir. PUR. */
+export function signalementValide(saisie: SaisieSignalement): boolean {
+  return Object.keys(verifierSignalement(saisie)).length === 0
+}
+
+/** Garde de type sur le vocabulaire fermé. PUR. */
+export function estTypeDemande(valeur: unknown): valeur is TypeDemande {
+  return typeof valeur === 'string' && TYPES.includes(valeur)
+}
+
+/**
+ * Les types à proposer dans la liste déroulante. PUR.
+ *
+ * ⚠️ Le type pré-rempli est AJOUTÉ s'il manque, et ce n'est pas du confort.
+ * `typesOfferts` vaut par défaut `['bug','question','idee']` — pas `beta` —
+ * alors que l'onglet Bêta pré-remplit justement `beta`. Un `<select>` contrôlé
+ * dont la valeur n'a aucune option correspondante s'affiche VIDE
+ * (`selectedIndex = -1`) : le champ « de quoi s'agit-il ? » paraît non rempli,
+ * et le premier geste de la personne — ouvrir la liste et choisir — remplace
+ * silencieusement `beta` par `bug` tout en gardant la campagne et le scénario.
+ * Le retour de bêta arrive alors dans la console sous un type qui n'est pas le
+ * sien, et la campagne compte un problème de moins.
+ *
+ * Rien de tout cela ne lève d'erreur : c'est un champ qui a l'air vide.
+ */
+export function typesAfficher(
+  typesOfferts: readonly TypeDemande[],
+  typePrefill: TypeDemande | undefined,
+): TypeDemande[] {
+  const liste = [...typesOfferts]
+  if (typePrefill && !liste.includes(typePrefill)) liste.unshift(typePrefill)
+  return liste
+}