refactor: centralize nostr event schemas

docs/nostr-event-schemas.md

@@ -0,0 +1,56 @@
+# Nostr event schemas
+
+BitVid now centralizes every note that it publishes to Nostr in
+[`js/nostrEventSchemas.js`](../js/nostrEventSchemas.js). The module defines the
+kind, required tags, and content format for each note type so troubleshooting
+no longer requires hunting through the codebase. It also exposes helpers for
+building events and for overriding the schema at runtime when you need to
+experiment.
+
+## Runtime helpers
+
+```js
+import {
+  NOTE_TYPES,
+  getNostrEventSchema,
+  setNostrEventSchemaOverrides,
+  buildVideoPostEvent,
+} from "./nostrEventSchemas.js";
+
+// Inspect the current schema
+console.log(getNostrEventSchema(NOTE_TYPES.VIDEO_POST));
+
+// Temporarily override the kind while debugging
+setNostrEventSchemaOverrides({
+  [NOTE_TYPES.VIDEO_POST]: { kind: 30000 },
+});
+
+// Build an event with the active schema
+const event = buildVideoPostEvent({
+  pubkey,
+  created_at: Math.floor(Date.now() / 1000),
+  dTagValue: "debug-video",
+  content: { version: 3, title: "Test", videoRootId: "debug" },
+});
+```
+
+In the browser you can call the same helpers from DevTools via
+`window.BitVidNostrEvents` and `window.BitVidNostrEventOverrides`.
+
+## Event catalogue
+
+| Note | Kind (default) | Tags | Content format |
+| --- | --- | --- | --- |
+| Video post (`NOTE_TYPES.VIDEO_POST`) | `30078` | `['t','video']`, `['d', <stable video identifier>]` plus optional schema append tags | JSON payload using Content Schema v3 (`version`, `title`, optional `url`, `magnet`, `thumbnail`, `description`, `mode`, `videoRootId`, `deleted`, `isPrivate`, `enableComments`, `ws`, `xs`) |
+| NIP-94 mirror (`NOTE_TYPES.VIDEO_MIRROR`) | `1063` | Tags forwarded from `publishVideo` (URL, mime type, thumbnail, alt text, magnet) | Plain text alt description |
+| View counter (`NOTE_TYPES.VIEW_EVENT`) | `WATCH_HISTORY_KIND` (default `30078`) | `['t','view']`, `['video', <pointer id>]`, pointer tag (`['a', ...]` or `['e', ...]`), optional dedupe `['d', <scope>]`, optional `['session','true']` when a session actor signs, plus any extra debugging tags | Optional plaintext message |
+| Watch history chunk (`NOTE_TYPES.WATCH_HISTORY_CHUNK`) | `WATCH_HISTORY_KIND` | `['d', <chunk identifier>]`, `['encrypted','nip04']`, `['snapshot', <id>]`, `['chunk', <index>, <total>]`, pointer tags for each entry, `['head','1']` + `['a', <address>]` pointers on the first chunk | NIP-04 encrypted JSON chunk (`{ version, snapshot, chunkIndex, totalChunks, items[] }`) |
+| Subscription list (`NOTE_TYPES.SUBSCRIPTION_LIST`) | `30002` | `['d', 'subscriptions']` | NIP-04 encrypted JSON `{ subPubkeys: string[] }` |
+| User block list (`NOTE_TYPES.USER_BLOCK_LIST`) | `30002` | `['d', 'user-blocks']` | NIP-04 encrypted JSON `{ blockedPubkeys: string[] }` |
+| Admin moderation list (`NOTE_TYPES.ADMIN_MODERATION_LIST`) | `30000` | `['d', 'bitvid:admin:editors']`, repeated `['p', <pubkey>]` entries | Empty content |
+| Admin blacklist (`NOTE_TYPES.ADMIN_BLACKLIST`) | `30000` | `['d', 'bitvid:admin:blacklist']`, repeated `['p', <pubkey>]` entries | Empty content |
+| Admin whitelist (`NOTE_TYPES.ADMIN_WHITELIST`) | `30000` | `['d', 'bitvid:admin:whitelist']`, repeated `['p', <pubkey>]` entries | Empty content |
+
+If you introduce a new Nostr feature, add its schema to
+`js/nostrEventSchemas.js` so that the catalogue stays complete and so existing
+builders inherit the same debugging knobs.