@zevra/support 0.2.0

package/README.md

@@ -0,0 +1,65 @@
+# @zevra/support — le client SERVEUR de Zevra Support
+
+Client typé de l'API v1 (`PLAN.md` §4), **sans aucune dépendance**, et le
+relais `/api/support/*` que le navigateur appelle à sa place.
+
+> **La clé `sk_support_…` ne va jamais dans un navigateur.**
+> `creerClientSupport()` jette si `window` et `document` existent. Ce n'est pas
+> une précaution : la clé authentifie l'app entière, elle est lisible en clair
+> dans un bundle, et le chemin qui l'y amène ne commence jamais par une
+> mauvaise intention (voir `src/garde-serveur.ts`, qui le raconte en entier).
+
+Le guide d'intégration complet — installation, exemple de bout en bout, pièges
+— vit dans **`docs/integration.md`** du dépôt et sur
+**https://support.zevra.tech/integration**.
+
+## En trente secondes
+
+```ts
+// app/api/support/[...chemin]/route.ts  — le relais, côté serveur
+import { creerRoutesSupport } from '@zevra/support'
+
+export const { GET, POST } = creerRoutesSupport({
+  identifier: async (requete) => {
+    const session = await maSession(requete)
+    return session ? { email: session.email, idExterne: session.id } : null
+  },
+})
+```
+
+```ts
+// n'importe où au serveur
+import { creerClientSupport } from '@zevra/support'
+const client = creerClientSupport()          // lit SUPPORT_URL / SUPPORT_API_KEY / SUPPORT_APP
+await client.creerDemande({ type: 'bug', titre, description, requerant: { email } })
+```
+
+## Ce qu'il y a dedans
+
+| Module | Rôle | Pur ? |
+|---|---|---|
+| `garde-serveur.ts` | refuse le chargement dans un navigateur | la décision l'est |
+| `configuration.ts` | ce qui manque, et comment le dire | oui |
+| `requete.ts` | URL, en-têtes, corps, borne des 256 Ko | oui |
+| `reessai.ts` | 429 / 5xx, `Retry-After`, budget de temps | oui |
+| `erreurs.ts` | la liste FERMÉE des codes | oui |
+| `client.ts` | la boucle d'appel | non (réseau) |
+| `relais/chemins.ts` | la liste blanche des six routes | oui |
+| `relais/corps.ts` | l'identité imposée, les champs acceptés | oui |
+| `relais/routes.ts` | les gestionnaires Next | non |
+
+## Tests
+
+Le paquet a sa propre chaîne — la configuration vitest de la racine ne ramasse
+que les tests de l'app. Depuis la racine du dépôt :
+
+```bash
+npx vitest run --config packages/sdk/vitest.config.ts
+```
+
+Ce qui est couvert : la clé dans `X-Support-Key` et jamais dans
+`Authorization`, la borne de corps comptée en octets UTF-8, le `Retry-After`
+illisible qui rend `null` et non `0`, l'attente qui ne tient pas dans le budget,
+la liste blanche face à `/admin/apps` et aux segments de remontée, l'identité du
+corps reçu qui est ignorée, le fil d'autrui qui rend 404, `url_portail` retiré,
+et `Cache-Control: no-store` sur toutes les réponses.

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@zevra/support",
+  "version": "0.2.0",
+  "description": "Client serveur et relais /api/support de Zevra Support.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/client.ts

@@ -0,0 +1,354 @@
+// ============================================================================
+// Le client de l'API v1. IMPUR — c'est lui qui parle au réseau.
+// ============================================================================
+//
+// Tout ce qu'il DÉCIDE est ailleurs (`requete.ts`, `reessai.ts`, `erreurs.ts`,
+// `configuration.ts`) ; ici on ne fait qu'appeler, attendre et transmettre.
+// C'est ce qui permet de tester le comportement sans monter un serveur.
+
+import { lireConfiguration, type EtatConfiguration } from './configuration'
+import { ErreurSupport, interpreterEchec } from './erreurs'
+import { exigerServeur } from './garde-serveur'
+import {
+  preparerRequete,
+  type EntreeRequete,
+  type ValeurQuery,
+} from './requete'
+import {
+  BUDGET_MS_DEFAUT,
+  DELAI_REQUETE_MS_DEFAUT,
+  MAX_TENTATIVES_DEFAUT,
+  analyserRetryApres,
+  deciderReessai,
+} from './reessai'
+import type {
+  DemandeCreee,
+  DemandeLue,
+  DepotPiece,
+  EntreeAjouterMessage,
+  EntreeCreerDemande,
+  EntreeDeposerPiece,
+  EntreeListerDemandes,
+  MessageAjoute,
+  PageDemandes,
+  ProgrammeActif,
+} from './types'
+
+export interface OptionsClientSupport {
+  /** Défaut : `SUPPORT_URL`. */
+  base?: string | null
+  /** Défaut : `SUPPORT_API_KEY`. NE DOIT JAMAIS venir d'un `NEXT_PUBLIC_*`. */
+  cle?: string | null
+  /** Défaut : `SUPPORT_APP`. Sert à repérer une clé recopiée d'une autre app. */
+  app?: string | null
+  /** Injectable pour les tests et pour un runtime sans `fetch` global. */
+  fetch?: typeof fetch
+  /** Délai d'une requête isolée. */
+  delaiMs?: number
+  /** Budget total, réessais et attentes compris. */
+  budgetMs?: number
+  maxTentatives?: number
+  /** Injectables : sans eux, un test de réessai dure réellement 500 ms. */
+  attendre?: (ms: number) => Promise<void>
+  horloge?: () => number
+  alea?: () => number
+  /** Appelé à chaque échec, avant réessai. Pour brancher VOTRE journal. */
+  journaliser?: (evenement: EvenementClient) => void
+}
+
+export interface EvenementClient {
+  chemin: string
+  methode: string
+  statut: number | null
+  tentative: number
+  reessai: boolean
+  dureeMs: number
+  message?: string
+}
+
+export interface ClientSupport {
+  /** L'état de la configuration : `pret`, et les phrases à afficher sinon. */
+  readonly etat: EtatConfiguration
+  creerDemande(entree: EntreeCreerDemande, options?: OptionsAppel): Promise<DemandeCreee>
+  listerDemandes(entree: EntreeListerDemandes): Promise<PageDemandes>
+  lireDemande(id: string): Promise<DemandeLue>
+  ajouterMessage(
+    demandeId: string,
+    entree: EntreeAjouterMessage,
+    options?: OptionsAppel,
+  ): Promise<MessageAjoute>
+  demanderDepotPiece(entree: EntreeDeposerPiece): Promise<DepotPiece>
+  programmeActif(): Promise<ProgrammeActif>
+}
+
+export interface OptionsAppel {
+  /** `Idempotency-Key` : même clé + même app sous 24 h ⇒ même réponse. */
+  cleIdempotence?: string | null
+}
+
+/**
+ * Crée le client. NE JETTE JAMAIS — sauf dans un navigateur (garde de clé).
+ *
+ * Il se crée même mal configuré : `client.etat.pret` dit si les appels
+ * peuvent aboutir, et chaque appel échoue alors en `configuration` avec la
+ * phrase exacte à corriger. Voir `configuration.ts` pour le pourquoi.
+ */
+export function creerClientSupport(options: OptionsClientSupport = {}): ClientSupport {
+  // ⚠️ Première ligne exécutée du chemin qui lit la clé. Dans un navigateur,
+  // on s'arrête ici, au chargement, avec la marche à suivre — et pas plus tard
+  // sur un 401 qui ferait chercher au mauvais endroit.
+  exigerServeur()
+
+  const env = lireEnvironnement()
+  const base = options.base ?? env.SUPPORT_URL ?? ''
+  const cle = options.cle ?? env.SUPPORT_API_KEY ?? ''
+  const app = options.app ?? env.SUPPORT_APP ?? ''
+  const etat = lireConfiguration({ base, cle, app })
+
+  const appelFetch = options.fetch ?? globalThis.fetch
+  const delaiMs = options.delaiMs ?? DELAI_REQUETE_MS_DEFAUT
+  const budgetMs = options.budgetMs ?? BUDGET_MS_DEFAUT
+  const maxTentatives = options.maxTentatives ?? MAX_TENTATIVES_DEFAUT
+  const horloge = options.horloge ?? (() => Date.now())
+  const alea = options.alea ?? Math.random
+  const attendre =
+    options.attendre ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)))
+
+  async function appeler<T>(
+    methode: 'GET' | 'POST',
+    chemin: string,
+    extra: { requete?: Record<string, ValeurQuery>; corps?: unknown; cleIdempotence?: string | null } = {},
+  ): Promise<T> {
+    if (!etat.pret) {
+      throw new ErreurSupport({
+        code: 'configuration',
+        message: `Support n'est pas branché sur cette app. ${etat.problemes.join(' ')}`,
+      })
+    }
+    if (typeof appelFetch !== 'function') {
+      throw new ErreurSupport({
+        code: 'configuration',
+        message:
+          "Aucun `fetch` disponible dans ce runtime : passez-en un à creerClientSupport({ fetch }).",
+      })
+    }
+
+    const entree: EntreeRequete = {
+      base,
+      cle,
+      methode,
+      chemin,
+      requete: extra.requete,
+      corps: extra.corps,
+      cleIdempotence: extra.cleIdempotence,
+    }
+    // Préparée UNE fois, hors de la boucle : elle ne dépend pas de la
+    // tentative, et la refaire ferait payer la sérialisation du corps à chaque
+    // réessai — sur un contexte de 200 Ko, ce n'est pas gratuit.
+    const preparee = preparerRequete(entree)
+
+    const debut = horloge()
+    let tentative = 1
+
+    for (;;) {
+      const resultat = await tenter(appelFetch, preparee, delaiMs)
+      const dureeMs = horloge() - debut
+
+      if (resultat.genre === 'reponse' && resultat.ok) {
+        options.journaliser?.({
+          chemin,
+          methode,
+          statut: resultat.statut,
+          tentative,
+          reessai: false,
+          dureeMs,
+        })
+        return resultat.donnees as T
+      }
+
+      const statut = resultat.genre === 'reponse' ? resultat.statut : null
+      const retryApres = resultat.genre === 'reponse' ? resultat.retryApres : null
+      const decision = deciderReessai({
+        statut,
+        retryApres,
+        tentative,
+        maxTentatives,
+        ecouleMs: dureeMs,
+        budgetMs,
+        maintenant: new Date(horloge()),
+        gigue: alea(),
+      })
+
+      options.journaliser?.({
+        chemin,
+        methode,
+        statut,
+        tentative,
+        reessai: decision.reessayer,
+        dureeMs,
+        message: resultat.genre === 'echec' ? resultat.message : undefined,
+      })
+
+      if (!decision.reessayer) {
+        throw composerErreur(resultat, statut, retryApres, decision.raison, horloge)
+      }
+
+      await attendre(decision.attendreMs)
+      tentative += 1
+    }
+  }
+
+  return {
+    etat,
+    creerDemande: (entree, opts) =>
+      appeler<DemandeCreee>('POST', 'demandes', {
+        corps: entree,
+        cleIdempotence: opts?.cleIdempotence,
+      }),
+    // ⚠️ `async` et pas une simple flèche : la garde ci-dessous JETTE, et la
+    // signature promet une promesse. Un `throw` synchrone dans une méthode
+    // déclarée `Promise<…>` remonte hors de tout `.catch()` — l'appelant qui a
+    // écrit le branchement correct se prend quand même une exception non
+    // rattrapée, et, dans un gestionnaire de route, un 500 au lieu de son
+    // message.
+    listerDemandes: async (entree) => {
+      // ⚠️ LA CEINTURE DE `?email=`. `serialiserQuery` omet les valeurs vides
+      // — c'est ce qu'il faut pour un statut au repos, et c'est exactement ce
+      // qu'il ne faut pas ici : une adresse vide ne produit pas « les demandes
+      // de personne », elle produit une requête SANS filtre, et l'API rend
+      // alors toutes les demandes de l'app. Servie par le relais, c'est la
+      // boîte entière dans le navigateur d'un visiteur, sous la forme d'une
+      // réponse parfaitement valide que rien ne signale.
+      //
+      // On refuse donc AVANT le réseau. « On ne sait pas de qui » ne vaut pas
+      // « de tout le monde ».
+      const email = String(entree.email ?? '').trim()
+      if (email === '') {
+        throw new ErreurSupport({
+          code: 'validation',
+          message:
+            "Lister des demandes exige l'adresse du requérant : sans elle, l'API rendrait toutes les demandes de l'app.",
+          champs: { email: 'requise' },
+        })
+      }
+      return appeler<PageDemandes>('GET', 'demandes', {
+        requete: {
+          email,
+          statut: entree.statut as ValeurQuery,
+          limite: entree.limite,
+          curseur: entree.curseur,
+        },
+      })
+    },
+    lireDemande: (id) => appeler<DemandeLue>('GET', `demandes/${encodeURIComponent(id)}`),
+    ajouterMessage: (demandeId, entree, opts) =>
+      appeler<MessageAjoute>('POST', `demandes/${encodeURIComponent(demandeId)}/messages`, {
+        corps: entree,
+        cleIdempotence: opts?.cleIdempotence,
+      }),
+    demanderDepotPiece: (entree) => appeler<DepotPiece>('POST', 'pieces', { corps: entree }),
+    programmeActif: () => appeler<ProgrammeActif>('GET', 'programmes/actif'),
+  }
+}
+
+/* ─── Le détail mécanique ───────────────────────────────────────────── */
+
+type Resultat =
+  | { genre: 'reponse'; ok: boolean; statut: number; donnees: unknown; retryApres: string | null }
+  | { genre: 'echec'; message: string; delai: boolean }
+
+async function tenter(
+  appelFetch: typeof fetch,
+  preparee: ReturnType<typeof preparerRequete>,
+  delaiMs: number,
+): Promise<Resultat> {
+  // ⚠️ `AbortSignal.timeout` plutôt qu'une course de promesses : sans
+  // annulation, la requête abandonnée continue de tenir une connexion. Sur un
+  // support momentanément lent, l'app cliente épuise son pool et tombe pour
+  // une raison qui n'a plus rien à voir avec le support.
+  const signal =
+    typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function'
+      ? AbortSignal.timeout(delaiMs)
+      : undefined
+
+  let reponse: Response
+  try {
+    reponse = await appelFetch(preparee.url, {
+      method: preparee.methode,
+      headers: preparee.entetes,
+      body: preparee.corps,
+      signal,
+    })
+  } catch (erreur) {
+    const message = erreur instanceof Error ? erreur.message : String(erreur)
+    const delai =
+      erreur instanceof Error && (erreur.name === 'TimeoutError' || erreur.name === 'AbortError')
+    return { genre: 'echec', message, delai }
+  }
+
+  const retryApres = reponse.headers?.get?.('Retry-After') ?? null
+  const donnees = await lireCorps(reponse)
+  return { genre: 'reponse', ok: reponse.ok, statut: reponse.status, donnees, retryApres }
+}
+
+/**
+ * Lit le corps SANS jamais jeter.
+ *
+ * Un 502 rendu par un proxy est du HTML ; un 204 n'a pas de corps. Dans les
+ * deux cas, `response.json()` jette, et l'exception remplacerait l'erreur
+ * réelle (« 502 ») par une erreur de syntaxe JSON — on chercherait alors un
+ * bug de sérialisation qui n'existe pas.
+ */
+async function lireCorps(reponse: Response): Promise<unknown> {
+  let texte: string
+  try {
+    texte = await reponse.text()
+  } catch {
+    return null
+  }
+  if (texte.trim() === '') return null
+  try {
+    return JSON.parse(texte)
+  } catch {
+    return texte
+  }
+}
+
+function composerErreur(
+  resultat: Resultat,
+  statut: number | null,
+  retryApres: string | null,
+  raisonAbandon: string,
+  horloge: () => number,
+): ErreurSupport {
+  if (resultat.genre === 'echec') {
+    return new ErreurSupport({
+      code: resultat.delai ? 'delai' : 'reseau',
+      message: resultat.delai
+        ? "Le support n'a pas répondu dans le délai imparti."
+        : `Le support est injoignable : ${resultat.message}`,
+      detail: raisonAbandon,
+    })
+  }
+  const donnees = interpreterEchec({
+    statut: resultat.statut,
+    corps: resultat.donnees,
+    retryApresMs: analyserRetryApres(retryApres, new Date(horloge())),
+  })
+  return new ErreurSupport({ ...donnees, detail: donnees.detail ?? raisonAbandon })
+}
+
+/**
+ * Lit l'environnement sans supposer que `process` existe.
+ *
+ * ⚠️ L'indirection par `globalThis` n'est pas du style : ce paquet doit
+ * s'installer dans une app qui tourne sur un runtime edge, où `process` peut
+ * ne pas être défini. Écrit `process.env.SUPPORT_URL` en clair, le module
+ * lèverait un `ReferenceError` à l'import — donc au démarrage, donc avant
+ * qu'aucune requête n'ait lieu, pour une capacité qui n'était peut-être même
+ * pas utilisée sur ce runtime.
+ */
+function lireEnvironnement(): Record<string, string | undefined> {
+  const global = globalThis as { process?: { env?: Record<string, string | undefined> } }
+  return global.process?.env ?? {}
+}

package/src/configuration.ts

@@ -0,0 +1,106 @@
+// ============================================================================
+// Ce que cette app sait faire avec Support — et ce qui lui manque. PUR.
+// ============================================================================
+//
+// Trois variables sont posées par l'admin Zevra lors de la liaison (PLAN.md
+// §6) : `SUPPORT_URL`, `SUPPORT_API_KEY`, `SUPPORT_APP`. Tant qu'elles ne sont
+// pas là, la capacité est ÉTEINTE — elle ne jette pas.
+//
+// ⚠️ C'est la règle du dépôt Support, et elle vaut encore plus chez l'app
+// cliente : un `throw` à la création du client se déclenche à l'import du
+// module, donc au démarrage du serveur, donc AVANT la première requête. Une
+// app entière refuserait de démarrer parce que le bouton « Aide » n'est pas
+// branché. Ici : le client se crée toujours, il annonce ce qui lui manque, et
+// chaque appel échoue proprement en `configuration` avec la phrase à lire.
+
+/** Le préfixe de toute clé de Support (`src/lib/cles/format.ts`). */
+export const PREFIXE_CLE = 'sk_support_'
+
+export interface EntreeConfiguration {
+  base?: string | null
+  cle?: string | null
+  app?: string | null
+}
+
+export interface EtatConfiguration {
+  pret: boolean
+  /** Une phrase par problème, prête à afficher. Vide quand tout va bien. */
+  problemes: string[]
+  /** Le slug LU dans la clé, quand elle est bien formée. */
+  slugDeLaCle: string | null
+}
+
+/**
+ * Extrait le slug d'une clé `sk_support_<slug>_<32 hex>`. PUR, total.
+ *
+ * ⚠️ Ceci ne VÉRIFIE rien : la vérification exige le sha256 stocké côté
+ * Support. On lit seulement une étiquette, pour pouvoir dire « cette clé est
+ * celle de lexform, pas de cockpit » — la confusion la plus banale quand on
+ * copie des variables d'une app à l'autre, et celle qui coûte le plus cher à
+ * diagnostiquer : Support répond 401 « clé invalide », ce qui est vrai et ne
+ * dit rien.
+ *
+ * Le slug peut contenir des tirets (`lexform-beta`) ; l'aléatoire, non. On
+ * découpe donc sur le DERNIER souligné, pas sur le premier.
+ */
+export function slugDeCle(cle: string | null | undefined): string | null {
+  if (typeof cle !== 'string') return null
+  const detoure = cle.trim()
+  if (!detoure.startsWith(PREFIXE_CLE)) return null
+  const reste = detoure.slice(PREFIXE_CLE.length)
+  const dernierSouligne = reste.lastIndexOf('_')
+  if (dernierSouligne <= 0) return null
+  const slug = reste.slice(0, dernierSouligne)
+  const aleatoire = reste.slice(dernierSouligne + 1)
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(slug)) return null
+  if (!/^[0-9a-f]{32}$/.test(aleatoire)) return null
+  return slug
+}
+
+/**
+ * Dresse l'état de la configuration. PUR.
+ *
+ * ⚠️ Un slug qui ne correspond pas à `SUPPORT_APP` est un AVERTISSEMENT, pas
+ * un refus : c'est presque toujours une erreur de copie, mais pas toujours —
+ * une app peut légitimement écrire au support d'une autre pendant une
+ * migration. Refuser sur cette base transformerait une gêne en panne.
+ */
+export function lireConfiguration(entree: EntreeConfiguration): EtatConfiguration {
+  const problemes: string[] = []
+  const base = (entree.base ?? '').trim()
+  const cle = (entree.cle ?? '').trim()
+  const app = (entree.app ?? '').trim()
+
+  if (base === '') {
+    problemes.push(
+      "SUPPORT_URL n'est pas définie : l'admin Zevra la pose en même temps que la clé, à la liaison de l'app au Support.",
+    )
+  } else if (!/^https?:\/\//i.test(base)) {
+    problemes.push(
+      `SUPPORT_URL doit commencer par http:// ou https:// (lu : « ${base} »).`,
+    )
+  }
+
+  const slug = slugDeCle(cle)
+  if (cle === '') {
+    problemes.push(
+      "SUPPORT_API_KEY n'est pas définie : demandez la liaison au Support depuis l'admin Zevra.",
+    )
+  } else if (slug === null) {
+    problemes.push(
+      `SUPPORT_API_KEY ne ressemble pas à une clé de Support (attendu : ${PREFIXE_CLE}<app>_<32 caractères>). Une clé tronquée à la copie donne exactement cette forme.`,
+    )
+  }
+
+  // `pret` se fige AVANT l'avertissement de slug : ce qui suit est une
+  // discordance à signaler, pas un empêchement d'appeler.
+  const pret = problemes.length === 0
+
+  if (app !== '' && slug !== null && slug !== app) {
+    problemes.push(
+      `SUPPORT_APP vaut « ${app} » mais la clé est celle de « ${slug} ». Les demandes seront classées sous ${slug}.`,
+    )
+  }
+
+  return { pret, problemes, slugDeLaCle: slug }
+}