story-research-zapwall/features/technical-doc.md

Documentation technique – zapwall4science (Dec 2025)

1) Cartographie services/hooks/types (responsabilités, dépendances)

• Services Nostr
  • lib/nostr.ts : pool SimplePool, publish générique, clés locales; queries article.
  • lib/nostrEventParsing.ts : parsing events → Article/Series/Review (tags kind_type, series, media, banner).
  • lib/nostrTags.ts : construction des tags article/série/avis (site, type science-fiction/research, kind_type, media/bannière).
  • lib/seriesQueries.ts, lib/articleQueries.ts, lib/reviews.ts : fetch séries, articles par série, critiques.
  • lib/articlePublisher.ts, lib/articleMutations.ts : publication article/preview/presentation, update/delete, kind_type, séries, médias, bannière.
  • lib/seriesAggregation.ts, lib/reviewAggregation.ts, lib/zapAggregation.ts : agrégats sponsoring/achats/remerciements.
  • lib/zapVerification.ts : vérification zap receipts (verifyEvent).
  • lib/nostrconnect.ts : Nostr Connect (handler, sécurité).
  • lib/nostrRemoteSigner.ts : signature distante (pas de fallback silencieux).
  • lib/nip95.ts : upload médias NIP-95 (images ≤5Mo, vidéos ≤45Mo, types restreints).
• Paiement / Lightning
  • lib/alby.ts : WebLN (enable, makeInvoice, sendPayment).
  • lib/payment.ts, lib/paymentPolling.ts : statut paiements, polling.
  • lib/articleInvoice.ts : facture article (zapAmount, expiry), tags preview.
• Stockage
  • lib/storage/cryptoHelpers.ts : AES-GCM, dérivation/import clé, conversions b64.
  • lib/storage/indexedDB.ts : set/get/delete/clearExpired chiffré, TTL.
  • lib/articleStorage.ts : clé maître locale (base64), secret par article, persistance contenu privé + facture.
• Hooks
  • hooks/useArticles.ts, hooks/useUserArticles.ts : subscriptions articles, filtres catégorie, unsubscribe direct (pas de .then).
  • hooks/useArticleEditing.ts : édition/suppression article.
  • Autres : useNotificationCenter, useNostrConnect, etc.
• Types
  • types/nostr.ts : Article, Series, Review, MediaRef, KindType, catégories; exactOptionalPropertyTypes respecté.
  • types/nostr-tools-extended.ts : extensions SimplePool/Sub.
  • types/alby.ts : WebLNProvider, invoice types.

2) Guide Nostr (publication, update/delete, zap, remote signer)

• Publication générique : nostrService.publishEvent(eventTemplate) (signEvent, created_at contrôlé).
• Article : articlePublisher.publishArticle (preview + tags kind_type/site/category/series/banner/media), contenu privé chiffré stocké.
• Update article : publishArticleUpdate (lib/articleMutations.ts) tags e (original) + replace, publie preview + contenu privé chiffré.
• Delete article : deleteArticleEvent (kind 5, tag e) — erreurs remontées, pas de fallback.
• Série : publishSeries (kind 1, tags kind_type=series, cover, description).
• Avis : publishReview (kind 1, kind_type=review, article/series/author tags).
• Zap verification : lib/zapVerification.ts (verifyEvent).
• Agrégats : aggregateZapSats / getSeriesAggregates / getReviewTipsForArticle.
• Remote signer : lib/nostrRemoteSigner.ts (clé fournie), sans valeurs de repli implicites.

3) Guide Stockage

• Chiffrement : cryptoHelpers (AES-GCM), entrée BufferSource conforme Web Crypto.
• IndexedDB : storage/indexedDB.ts stocke { iv, ciphertext, expiresAt }, purge clearExpired.
• Secret : articleStorage génère clé maître (localStorage, base64, 32 bytes) puis secret <master>:<articleId>.
• Données : contenu privé + facture, TTL 30 jours, suppression via removeStoredPrivateContent.

4) Guide Paiements

• WebLN/Alby : lib/alby.ts (enable, makeInvoice, sendPayment).
• Facture article : createArticleInvoice (zapAmount, expiry).
• Publication article : articlePublisher gère preview event + stockage contenu privé.
• Polling / vérif : paymentPolling.ts, payment.ts; agrégats via zap receipts (zapAggregation.ts).
• Envoi contenu privé : via publisher/mutations après paiement confirmé.

5) Médias / NIP-95

• Upload via uploadMedia(file) (URL NEXT_PUBLIC_NIP95_UPLOAD_URL), validation type/taille.
• Utilisation dans MarkdownEditor (insertion markdown), bannière dans ArticleDraft.

6) Contrib (référence rapide)

• Lint/typage obligatoires (npm run lint, npm run type-check).
• Pas de tests/analytics ajoutés.
• Pas de fallback implicite, pas de ts-ignore/any non justifié.
• Accessibilité : ARIA/clavier/contraste.
• Documentation : corrections dans fixKnowledge/, features dans features/.