discovery-media-player 0.1.133 → 0.1.134

package/README.md

@@ -16,6 +16,7 @@ to a third-party SaaS.
 [![CI](https://github.com/Juli1artha/discovery-media-player/actions/workflows/ci.yml/badge.svg)](https://github.com/Juli1artha/discovery-media-player/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/Juli1artha/discovery-media-player/actions/workflows/codeql.yml/badge.svg)](https://github.com/Juli1artha/discovery-media-player/actions/workflows/codeql.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Juli1artha/discovery-media-player/badge)](https://scorecard.dev/viewer/?uri=github.com/Juli1artha/discovery-media-player)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14197/badge)](https://www.bestpractices.dev/projects/14197)
 [![npm](https://img.shields.io/npm/v/discovery-media-player?logo=npm&color=cb3837)](https://www.npmjs.com/package/discovery-media-player)
 [![Container](https://img.shields.io/badge/ghcr.io-discovery--media--player-2496ed?logo=docker&logoColor=white)](https://github.com/Juli1artha/discovery-media-player/pkgs/container/discovery-media-player)
 [![Node](https://img.shields.io/node/v/discovery-media-player?logo=node.js&color=5fa04e)](package.json)

package/docs/HOST-CONTRACT.md

@@ -391,13 +391,63 @@ The rule underneath, safer than the list: **never fall back on a refusal of *acc
 back on an inability to *reach*.** And "do not fall back" applies to what you **offer** — an
 "Open ↗" button left in place is falling back one second later.
 
-## Two things that will bite
+## Four things that will bite
 
 **Your document-opening doors reappear.** A host has more than one place that opens a file, and new
 ones get written. Keep the list and hunt it periodically — and note that **your search criteria
 decide what you find**: search by what the user *obtains* (a document opens), not by the technique
 you expect to see.
 
+**A row written on behalf of a session also carries the document.** The player hands every bot
+plugin call both the `sessionId` and the `share`. If your plugin stores only the session, then the
+day a session-binding defect is found — one was in 0.1.131, and four more actions in 0.1.133 — you
+cannot say whether anything crossed. The honest answer is not *"nothing found"*, it is **"not
+measurable"**, and those are different sentences to give a client.
+
+Measured on a production host the day the second defect was fixed:
+
+| table | what it records beside the session | verdict |
+| --- | --- | --- |
+| leads (`bot-contact`, `bot-book`) | the share **and** the document | 46 leads, 21 carrying contact details — **none crossed** |
+| messages (`bot-say`) | the session alone | 1 693 messages — **not measurable** |
+
+Same incident, same instance, two verdicts — decided months earlier by one column. It costs nothing
+at write time, and it decides what you are able to say afterwards.
+
+⚠️ **The expectation is answerability, not a column name** — and this paragraph earned that sentence
+the hard way, one day after it was written. The same host then swept all eight of their tables
+carrying a session: seven already recorded the document, under four different names (`doc_id`,
+`share_slug`, `link_id`, `xp_id`). **One** did not. The discipline was everywhere and written
+nowhere, which is exactly why it gave way at the single place nobody thought about.
+
+Their first sweep looked for the two names this page happens to use, and would have accused three
+correct tables. So when you check your own schema, write the check from **what your code stores**,
+not from a list of column names borrowed from someone else's — a coarse check has no false
+positives to excuse, it has a pattern to derive. The question each row must be able to answer is
+*which document was this written for*; the key that answers it is yours to name.
+
+**A database error carries its status as a number, not inside its message.** Set `statusCode` (or
+`status`) on whatever `db.request` throws. Both contexts shipped here already do; a host that
+implements the seam itself may not, and the player then has to guess from the text.
+
+Guessing was the state until 24/08, at six call sites: `message.includes("409")` — the digits
+anywhere in the string. But the message carries the **path**, so it carries the slug, the id, the
+page number. Measured on the real shapes:
+
+```
+Supabase POST  /doc_presentation_attendees                  → 409   conflict   ✅
+Supabase POST  /doc_presentation_attendees?slug=eq.demo409  → 500   conflict   ❌
+Supabase PATCH /doc_bot_sessions?id=eq.sess-409abc          → 500   conflict   ❌
+Supabase GET   /doc_pages?page=eq.409                       → 503   conflict   ❌
+```
+
+Three in four. And every site reads `if (!conflict) throw`, so a genuine 500 was **swallowed** and
+the code carried on as though the row already existed. One document whose slug contains `409` —
+a reference number, a date — was enough.
+
+The fallback that remains accepts `409` only **after the arrow**, where a status lives and a slug
+cannot. Setting the number spares you that reasoning entirely.
+
 **Configured is not served.** When a diagnosis is disputed, the useful question is not who is right
 but *did you measure exactly what fails*. Two true statements about the same instance can describe
 different responses.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discovery-media-player",
-  "version": "0.1.133",
+  "version": "0.1.134",
   "description": "Self-hosted document viewer: per-recipient tracked links, reading analytics, live presentation. The core knows nothing about the application hosting it — everything it borrows arrives through an injected context.",
   "keywords": [
     "pdf-viewer",

package/server/erreurs-base.js

@@ -0,0 +1,58 @@
+// LE FAIT, PAS LE LIBELLÉ — COMMENT ON RECONNAÎT UN CONFLIT D'UNICITÉ.
+//
+// ⚠️ CE QUE FAISAIENT LES SIX SITES, ET CE QUE ÇA COÛTAIT.
+//
+//     if (!String((erreur && erreur.message) || "").includes("409")) throw erreur;
+//
+// Le message que `context/standalone.js` compose est `Supabase POST /chemin?… → 409`, et le CHEMIN
+// contient le slug, l'identifiant, le numéro de page. Chercher « 409 » n'importe où dans cette
+// chaîne confond donc le statut avec les DONNÉES. Mesuré le 24/08 sur les formes réelles :
+//
+//     Supabase POST  /doc_presentation_attendees                  → 409   conflit    ✅
+//     Supabase POST  /doc_presentation_attendees?slug=eq.demo409  → 500   conflit    ❌
+//     Supabase PATCH /doc_bot_sessions?id=eq.sess-409abc          → 500   conflit    ❌
+//     Supabase GET   /doc_pages?page=eq.409                       → 503   conflit    ❌
+//
+// Trois sur quatre. Et l'usage est toujours `if (!conflit) throw` : une vraie panne 500 était donc
+// AVALÉE, et le code continuait comme si la ligne existait déjà. Il suffit d'un document dont le
+// slug porte « 409 » — un numéro de référence, une date — pour qu'une erreur de base disparaisse.
+//
+// ⚠️ LE FAIT EXISTE DÉJÀ. `context/standalone.js` pose `erreur.statusCode = r.status` depuis la
+// correction de PGRST202, et son commentaire dit que le studio expose la même chose : « les deux
+// formes convergent enfin ». Six sites lisaient encore le texte à côté.
+//
+// La leçon vient d'un exploitant, qui l'a payée sur son propre outillage : un tri sur un LIBELLÉ
+// s'est renversé le jour où il a trouvé un meilleur mot. Un test sur un libellé a la même
+// fragilité, en pire — il ne se renverse pas, il se trompe en silence.
+//
+// ⚠️ POURQUOI IL RESTE UN REPLI TEXTUEL. Un hôte tiers implémente `db.request` lui-même et peut
+// n'avoir jamais posé `statusCode`. Le repli existe donc, mais il ne cherche plus « 409 » n'importe
+// où : il ne l'accepte QU'À LA PLACE DU STATUT, en fin de message, là où le contrat le met. Un slug
+// ne peut pas s'y trouver.
+
+/** Le statut HTTP d'une erreur de base, ou `null` si personne ne l'a posé. */
+const statutDe = (erreur) => {
+  const s = erreur && (erreur.statusCode ?? erreur.status);
+  return Number.isInteger(s) ? s : null;
+};
+
+/**
+ * Vrai si cette erreur EST un conflit d'unicité (409).
+ *
+ * ⚠️ L'ordre compte : le fait d'abord, le texte seulement à défaut. Inverser reviendrait à
+ * consulter le libellé même quand le statut est là — c'est-à-dire à garder le défaut avec une
+ * façade.
+ */
+function estConflit(erreur) {
+  const statut = statutDe(erreur);
+  if (statut !== null) return statut === 409;
+  // ⚠️ REPLI : « 409 » EN POSITION DE STATUT, c'est-à-dire APRÈS la flèche — jamais ailleurs.
+  // Un premier essai exigeait la fin de message ou un tiret de détail : c'était se caler sur le
+  // format d'UN contexte, et quatre bancs l'ont refusé en lançant « → 409 duplicate key … ». Ce
+  // qu'on peut affirmer sans connaître l'hôte, c'est la POSITION : ce qui suit la flèche est le
+  // statut. Un slug, lui, vit dans le chemin — avant elle. C'est ce qui distingue ce repli du
+  // défaut qu'il remplace : « 409 » n'importe où, contre « 409 » là où le statut se trouve.
+  return /→\s*409\b/.test(String((erreur && erreur.message) || ""));
+}
+
+module.exports = { estConflit };

package/server/presentations.js

@@ -589,7 +589,7 @@ async function addMessage(slug, { name, email, avatar, isPresenter, isMember, bo
     // attendu n'est pas un incident — mais rien ne distinguait « je sais ce que je rattrape » de
     // « j'avale tout ». On le dit donc : ce qui n'est pas le conflit attendu remonte, et le conflit
     // attendu est journalisé une fois, en clair, parce qu'un renvoi fréquent est une information.
-    const conflit = cle && String((erreur && erreur.message) || "").includes("409");
+    const conflit = cle && estConflit(erreur);
     if (!conflit) throw erreur;
     try { PLAYER.errors.capture(new Error("message déjà enregistré (renvoi) : " + String(slug)), { route: "present-chat", benin: true }); } catch { /* jamais bloquant */ }
     const deja = await PLAYER.db.request(
@@ -1163,7 +1163,7 @@ async function recordAttendance(slug, participant, { presentation = null, ipHash
         // simultanés (deux onglets ouverts ensemble), et le second recevait un 409 que personne ne
         // rattrapait — un 500 pour un battement, bénin mais faux. Le conflit dit « la ligne existe
         // maintenant » : on la relit et on continue en mise à jour. Tout autre échec remonte.
-        if (!String((erreur && erreur.message) || "").includes("409")) throw erreur;
+        if (!estConflit(erreur)) throw erreur;
         // Journalisé comme bénin : deux onglets qui arrivent ensemble sont une information, pas
         // une panne — et la garde des écritures muettes exige que tout rattrapage parle.
         try { PLAYER.errors.capture(new Error("présence déjà ouverte (second onglet) : " + String(slug)), { route: "present-attend", benin: true }); } catch { /* jamais bloquant */ }
@@ -1284,6 +1284,7 @@ async function switchPresentationDoc(slug, email, isAdmin, { fileUrl, fileName,
 // Il traverse trois frontières (présentateur → serveur → audience) : deux implémentations
 // finissaient par diverger, et une audience qui ne voit pas la bonne carte n'émet aucune erreur.
 const { sanitizeContent } = require("./shared.generated.js");
+const { estConflit } = require("./erreurs-base.js");
 
 /**
  * Une présentation close ne se pilote plus par le chemin PROPRIÉTAIRE.

package/server/routes-liens.js

@@ -2,6 +2,7 @@
 // Reste à PLAT dans server/ (les gardes de forge ciblent server/*.js).
 
 const { adresseAppelant } = require("./appelant");
+const { estConflit } = require("./erreurs-base.js");
 const { createShare, createReshare, sendReshareEmail, revokeShare, setShareAuth, listSharesForDoc, listSessionsForDoc, internalStatsForDoc, cleIdempotence, getShareBySlug, logView, upsertSession, upsertInternalSession, overview: docOverview } = require("./shares");
 const { SESSION_QUOTA_PER_HOUR, VIEW_QUOTA_PER_HOUR } = require("./shared.generated.js");
 
@@ -142,7 +143,7 @@ async function traiter(req, res, body, slug) {
                   body: { doc_title: body.docTitle || null, file_url: String(body.fileUrl), file_name: body.fileName || null, revoked: false, ...(cleDispo ? { idem_key: cleHote } : {}) },
                 });
               } catch (erreur) {
-                if (!String((erreur && erreur.message) || "").includes("409")) throw erreur;
+                if (!estConflit(erreur)) throw erreur;
                 try { PLAYER.errors.capture(new Error("backfill hôte : la clé était déjà posée ailleurs — " + docId), { route: "hostshare", benin: true }); } catch { /* jamais bloquant */ }
                 const gagnant = await PLAYER.db.request(`commercial_doc_shares?idem_key=eq.${encodeURIComponent(cleHote)}&select=slug&limit=1`);
                 if (!Array.isArray(gagnant) || !gagnant[0]) throw erreur;
@@ -169,7 +170,7 @@ async function traiter(req, res, body, slug) {
               });
               return jd(200, { ok: true, slug: neuf.slug, reused: false });
             } catch (erreur) {
-              if (!String((erreur && erreur.message) || "").includes("409")) throw erreur;
+              if (!estConflit(erreur)) throw erreur;
               try { PLAYER.errors.capture(new Error("lien hôte déjà créé par une demande simultanée : " + docId), { route: "hostshare", benin: true }); } catch { /* jamais bloquant */ }
               const gagnant = await PLAYER.db.request(`commercial_doc_shares?idem_key=eq.${encodeURIComponent(cleHote)}&select=slug&limit=1`);
               if (!Array.isArray(gagnant) || !gagnant[0]) throw erreur;   // 409 d'autre chose : on ne l'invente pas
@@ -219,7 +220,7 @@ async function traiter(req, res, body, slug) {
             try {
               await PLAYER.db.request(`commercial_doc_shares?slug=eq.${encodeURIComponent(ex[0].slug)}`, { method: "PATCH", headers: { Prefer: "return=minimal" }, body: { doc_title: body.docTitle || null, file_url: String(body.fileUrl), file_name: body.fileName || null, bot_enabled: true, bot_guided: true, bot_profile_id: (body.profileId || "").trim() || null, revoked: false, ...(cleDispo ? { idem_key: cleTest } : {}) } });
             } catch (erreur) {
-              if (!String((erreur && erreur.message) || "").includes("409")) throw erreur;
+              if (!estConflit(erreur)) throw erreur;
               try { PLAYER.errors.capture(new Error("backfill répétition : la clé était déjà posée ailleurs — " + docId), { route: "docshare-test", benin: true }); } catch { /* jamais bloquant */ }
               const gagnant = await PLAYER.db.request(`commercial_doc_shares?idem_key=eq.${encodeURIComponent(cleTest)}&select=slug&limit=1`);
               if (!Array.isArray(gagnant) || !gagnant[0]) throw erreur;
@@ -232,7 +233,7 @@ async function traiter(req, res, body, slug) {
             const t = await createShare({ docId, docTitle: body.docTitle, fileUrl: body.fileUrl, fileName: body.fileName, recipientName: "Répétition (test)", createdBy: u.email, bot: true, guided: true, profileId: body.profileId, isTest: true, idemKey: cleTest });
             return jd(200, { ok: true, slug: t.slug });
           } catch (erreur) {
-            if (!String((erreur && erreur.message) || "").includes("409")) throw erreur;
+            if (!estConflit(erreur)) throw erreur;
             try { PLAYER.errors.capture(new Error("lien de répétition déjà créé par une demande simultanée : " + docId), { route: "docshare-test", benin: true }); } catch { /* jamais bloquant */ }
             const gagnant = await PLAYER.db.request(`commercial_doc_shares?idem_key=eq.${encodeURIComponent(cleTest)}&select=slug&limit=1`);
             if (!Array.isArray(gagnant) || !gagnant[0]) throw erreur;