@zevra/support 0.2.0

package/src/requete.ts

@@ -0,0 +1,146 @@
+// ============================================================================
+// La construction d'une requête. PUR — aucune I/O, aucune horloge.
+// ============================================================================
+//
+// Tout ce que le client fait de discutable est ICI, pour que ce soit rejouable
+// dans un test : quel en-tête porte la clé, comment la base est normalisée,
+// comment une valeur multiple devient une query string, et à partir de quelle
+// taille on refuse d'envoyer.
+
+import { ErreurSupport } from './erreurs'
+
+/** L'en-tête d'authentification de l'API v1 (PLAN.md §4). */
+export const ENTETE_CLE = 'X-Support-Key'
+
+/** Idempotence des POST : même clé + même app dans les 24 h ⇒ même réponse. */
+export const ENTETE_IDEMPOTENCE = 'Idempotency-Key'
+
+/** Le chemin de base de l'API v1, sous l'URL de Support. */
+export const SEGMENT_API = '/api/v1'
+
+/**
+ * 256 Ko (PLAN.md §4), comptés en OCTETS UTF-8.
+ *
+ * ⚠️ Pas en caractères : « é » pèse 2 octets, un emoji 4, et un contexte de
+ * console plein d'accents passerait la vérification pour être refusé par le
+ * serveur après avoir traversé le réseau. C'est exactement le genre d'échec
+ * qu'on ne reproduit jamais en test avec des chaînes ASCII.
+ */
+export const TAILLE_MAX_CORPS_OCTETS = 256 * 1024
+
+export type ValeurQuery = string | number | boolean | readonly string[] | null | undefined
+
+export interface EntreeRequete {
+  /** L'URL de Support (`SUPPORT_URL`), avec ou sans `/api/v1`, avec ou sans `/`. */
+  base: string
+  cle: string
+  methode: 'GET' | 'POST'
+  /** Le chemin SOUS `/api/v1`, sans barre de tête : `demandes/<id>/messages`. */
+  chemin: string
+  requete?: Record<string, ValeurQuery>
+  corps?: unknown
+  cleIdempotence?: string | null
+}
+
+export interface RequetePreparee {
+  url: string
+  methode: 'GET' | 'POST'
+  entetes: Record<string, string>
+  corps?: string
+  /** La taille réelle du corps, en octets. Utile au journal d'incident. */
+  octets: number
+}
+
+/**
+ * Range l'URL de Support en base d'API. PUR.
+ *
+ * `SUPPORT_URL` est posée par l'admin Zevra et vaut l'URL de l'app
+ * (`https://support.zevra.tech`). Mais tout le monde ne la lit pas pareil :
+ * certains y collent déjà `/api/v1`, d'autres laissent une barre finale, un
+ * autre encore recopie `https://support.zevra.tech/api/v1/`. Les trois doivent
+ * marcher — sinon l'intégration échoue en 404 sur une faute d'URL, et le
+ * message d'erreur parle de « demande introuvable ».
+ */
+export function normaliserBase(brut: string): string {
+  const detoure = String(brut ?? '').trim()
+  if (detoure === '') return ''
+  const sansBarre = detoure.replace(/\/+$/, '')
+  if (sansBarre.endsWith(SEGMENT_API)) return sansBarre
+  return `${sansBarre}${SEGMENT_API}`
+}
+
+/**
+ * Sérialise la query string. PUR.
+ *
+ * ⚠️ Une valeur VIDE est omise, jamais envoyée. `?statut=` (un select au
+ * repos, une variable non remplie) est lu côté Support comme « pas de
+ * filtre » — mais `?email=` serait lu comme « les demandes de ⟨rien⟩ », que le
+ * socle traite en page vide. Ne rien envoyer est la seule écriture qui ait le
+ * même sens des deux côtés.
+ */
+export function serialiserQuery(requete: Record<string, ValeurQuery> | undefined): string {
+  if (!requete) return ''
+  const parametres = new URLSearchParams()
+  for (const [cle, valeur] of Object.entries(requete)) {
+    if (valeur === null || valeur === undefined) continue
+    const valeurs = Array.isArray(valeur) ? valeur : [valeur as string | number | boolean]
+    for (const une of valeurs) {
+      const texte = String(une).trim()
+      if (texte === '') continue
+      parametres.append(cle, texte)
+    }
+  }
+  const rendu = parametres.toString()
+  return rendu === '' ? '' : `?${rendu}`
+}
+
+/** Compte les octets UTF-8 d'une chaîne, sans dépendre de `Buffer`. */
+export function octetsUtf8(texte: string): number {
+  return new TextEncoder().encode(texte).length
+}
+
+/**
+ * Assemble tout. PUR — jette `validation` si le corps dépasse la borne.
+ *
+ * ⚠️ On refuse AVANT d'envoyer. Laisser partir 400 Ko pour récolter un 422
+ * coûte un aller-retour, du temps d'attente pour la personne qui a cliqué, et
+ * un message serveur qui ne dit pas quel champ est trop gros. Ici, on peut le
+ * dire : c'est presque toujours le contexte de console ou une capture collée
+ * en base64 dans la description.
+ */
+export function preparerRequete(entree: EntreeRequete): RequetePreparee {
+  const base = normaliserBase(entree.base)
+  const chemin = String(entree.chemin ?? '').replace(/^\/+/, '')
+  const url = `${base}/${chemin}${serialiserQuery(entree.requete)}`
+
+  const entetes: Record<string, string> = {
+    // ⚠️ JAMAIS `Authorization: Bearer` : sur support.dev.zevra.tech, la garde
+    // basicAuth de l'environnement de dev consomme cet en-tête (AGENTS.md), et
+    // les appels échouent sans la moindre explication utile.
+    [ENTETE_CLE]: entree.cle,
+    Accept: 'application/json',
+  }
+
+  let corps: string | undefined
+  let octets = 0
+  if (entree.corps !== undefined) {
+    corps = JSON.stringify(entree.corps)
+    octets = octetsUtf8(corps)
+    if (octets > TAILLE_MAX_CORPS_OCTETS) {
+      throw new ErreurSupport({
+        code: 'validation',
+        message: `Le corps de la requête pèse ${octets} octets ; la limite est de ${TAILLE_MAX_CORPS_OCTETS}. Le contexte technique (erreurs de console) ou une pièce collée dans la description en sont presque toujours la cause — une pièce se dépose par POST /pieces.`,
+        champs: { corps: 'trop volumineux' },
+      })
+    }
+    entetes['Content-Type'] = 'application/json'
+  }
+
+  // L'idempotence n'a de sens que sur une écriture : posée sur un GET, elle
+  // laisserait croire à une garantie que l'API ne donne pas.
+  if (entree.methode === 'POST' && entree.cleIdempotence) {
+    entetes[ENTETE_IDEMPOTENCE] = entree.cleIdempotence
+  }
+
+  return { url, methode: entree.methode, entetes, corps, octets }
+}

package/src/types.ts

@@ -0,0 +1,221 @@
+// ============================================================================
+// Les types du FIL — le contrat §4 de PLAN.md, recopié tel qu'il voyage.
+// ============================================================================
+//
+// ⚠️ Deux décisions de vocabulaire, qui expliquent tout ce fichier.
+//
+// 1. **On garde le `snake_case` du contrat** (`id_externe`, `curseur_suivant`,
+//    `type_mime`, `url_put`). Traduire en camelCase donnerait une deuxième
+//    nomenclature à tenir : le jour où l'API ajoute un champ, il arriverait
+//    dans le SDK sous un nom que personne n'a écrit, et la table de
+//    correspondance oubliée rendrait `undefined` sans la moindre erreur. Le
+//    fil est la source de vérité ; le SDK en est le calque typé.
+//
+// 2. **Les unions fermées sont RECOPIÉES ici**, alors qu'elles existent déjà
+//    dans `src/lib/domaine/types.ts` de l'app. C'est délibéré : ce paquet est
+//    publié et installé chez des apps qui n'ont pas le dépôt Support. Importer
+//    l'app depuis le SDK ferait dépendre un client de son serveur. Le prix de
+//    la copie est qu'une valeur ajoutée au vocabulaire doit être ajoutée ici —
+//    d'où le renvoi explicite, ci-dessous, vers le fichier à suivre.
+
+/** Source : `src/lib/domaine/types.ts` de Zevra Support (PLAN.md §2). */
+export type TypeDemande = 'bug' | 'question' | 'idee' | 'beta'
+
+/** Source : `src/lib/domaine/types.ts` de Zevra Support (PLAN.md §2). */
+export type StatutDemande =
+  | 'nouvelle'
+  | 'ouverte'
+  | 'en_attente_requerant'
+  | 'resolue'
+  | 'fermee'
+
+/** Source : `src/lib/domaine/types.ts` de Zevra Support (PLAN.md §2). */
+export type PrioriteDemande = 'basse' | 'normale' | 'haute' | 'critique'
+
+/** Source : `src/lib/domaine/types.ts` de Zevra Support (PLAN.md §2). */
+export type AuteurMessage = 'requerant' | 'equipe' | 'ia' | 'systeme'
+
+export const TYPES_DEMANDE: readonly TypeDemande[] = ['bug', 'question', 'idee', 'beta']
+
+/* ─── Le requérant ──────────────────────────────────────────────────── */
+
+/**
+ * Qui demande. C'est l'app hôte qui le sait — jamais le navigateur : voir
+ * `relais/corps.ts`, où cette identité est IMPOSÉE au corps reçu.
+ */
+export interface Requerant {
+  email: string
+  nom?: string | null
+  /** L'identifiant de la personne DANS l'app cliente, pour recoller les fils. */
+  id_externe?: string | null
+}
+
+/* ─── Le contexte technique ─────────────────────────────────────────── */
+
+/**
+ * Ce que le widget relève tout seul (PLAN.md §3, colonne `contexte` jsonb).
+ *
+ * Tous les champs sont optionnels : un contexte partiel vaut mieux qu'un
+ * contexte inventé. `console` porte au plus les 20 dernières erreurs.
+ */
+export interface ContexteDemande {
+  url?: string
+  user_agent?: string
+  version?: string
+  os?: string
+  viewport?: string
+  langue?: string
+  console?: string[]
+  extra?: Record<string, unknown>
+}
+
+/* ─── POST /demandes ────────────────────────────────────────────────── */
+
+export interface EntreeCreerDemande {
+  /** Facultatif : absent, le triage IA de Support le détermine. */
+  type?: TypeDemande | null
+  /** Facultatif : absent, le triage IA de Support le rédige d'après la description. */
+  titre?: string | null
+  description: string
+  requerant: Requerant
+  contexte?: ContexteDemande | null
+  /** Identifiants rendus par `POST /pieces`, jamais des noms de fichiers. */
+  pieces?: readonly string[]
+  campagne_id?: string | null
+  scenario?: string | null
+  /** Retour de bêta, 1 à 5. Hors bornes : 422. */
+  score?: number | null
+}
+
+export interface DemandeCreee {
+  id: string
+  /** La référence publique, déjà formatée : « SUP-412 ». */
+  reference: string
+  statut: StatutDemande
+  /** Le lien magique du portail requérant — à mettre dans VOTRE accusé. */
+  url_portail: string
+}
+
+/* ─── GET /demandes ─────────────────────────────────────────────────── */
+
+export interface EntreeListerDemandes {
+  email: string
+  statut?: StatutDemande | readonly StatutDemande[]
+  limite?: number
+  curseur?: string | null
+}
+
+/**
+ * Le résumé d'une demande en liste.
+ *
+ * ⚠️ Il n'y a NI description, NI contexte, NI extrait du dernier message, et
+ * ce n'est pas un oubli : le dernier message d'un fil peut être une note
+ * interne, et un extrait est la fuite la plus discrète qu'on puisse écrire.
+ * Pour le corps d'une demande, il faut la lire (`lireDemande`).
+ */
+export interface ResumeDemande {
+  id: string
+  reference: string
+  type: TypeDemande
+  statut: StatutDemande
+  priorite: PrioriteDemande
+  titre: string
+  created_at: string
+  dernier_message_at: string
+}
+
+export interface PageDemandes {
+  demandes: ResumeDemande[]
+  /** Absent ou `null` : c'était la dernière page. */
+  curseur_suivant?: string | null
+}
+
+/* ─── GET /demandes/:id ─────────────────────────────────────────────── */
+
+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 de LECTURE présignée, de courte durée. Jamais la clé S3 brute. */
+  url?: string | null
+}
+
+export interface DemandeLue {
+  demande: ResumeDemande & {
+    description: string
+    contexte?: ContexteDemande | null
+    resolue_at?: string | null
+    /**
+     * ⚠️ CE CHAMP EST LA GARDE D'APPARTENANCE DU RELAIS, pas un ornement.
+     *
+     * `GET /api/v1/demandes/:id` rend n'importe quelle demande DE L'APP : la
+     * clé suffit, l'adresse n'y entre pas. C'est donc `relais/routes.ts` qui
+     * compare cette adresse à celle de la session avant de rendre le fil.
+     *
+     * S'il manque de la réponse de l'API v1, `verifierAppartenance` rend
+     * `false` — fermé par défaut, donc sûr, mais TOUTE lecture et TOUTE
+     * réponse sont alors refusées en 404 et l'onglet « Mes demandes » devient
+     * inutilisable. C'est pour ça qu'il est typé ici plutôt que lu par un
+     * transtypage : le jour où le lot 1 change la forme de la réponse, la
+     * rupture se voit à la compilation et pas sur un écran vide.
+     */
+    requerant_email?: string | null
+  }
+  /** Les notes internes de l'équipe ne sont JAMAIS dans cette liste. */
+  messages: MessageLu[]
+  pieces: PieceLue[]
+}
+
+/* ─── POST /demandes/:id/messages ───────────────────────────────────── */
+
+export interface EntreeAjouterMessage {
+  corps: string
+  /** L'adresse du requérant : c'est elle qui prouve que le fil lui appartient. */
+  requerant_email: string
+  pieces?: readonly string[]
+}
+
+export interface MessageAjoute {
+  message: MessageLu
+}
+
+/* ─── POST /pieces ──────────────────────────────────────────────────── */
+
+export interface EntreeDeposerPiece {
+  nom: string
+  type_mime: string
+  octets: number
+}
+
+export interface DepotPiece {
+  id: string
+  /** URL présignée : le fichier part en PUT DIRECTEMENT vers S3, pas par ici. */
+  url_put: string
+  expire_at: string
+}
+
+/* ─── GET /programmes/actif ─────────────────────────────────────────── */
+
+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
+}