chore: publish pearcord-delivery-receipts from pearcord workspace

2026-07-12 23:40:44 -04:00
commit 3911aaa2ef
5 changed files with 6373 additions and 0 deletions
@@ -0,0 +1 @@
+node_modules/
@@ -0,0 +1,145 @@
+# pearcord-delivery-receipts
+
+Automation hook dispatch, delivery receipts, failure alerts, scheduled audit/digest exports, and archive mesh health. P2P-local; optional signed JSON stubs.
+
+**v0.8.691 (Phase 715):** `listDeviceSyncJsonExports`, `listDiscoveryListingExportJsonExports`, `buildDeviceSyncJsonBody`, `buildDiscoveryListingExportJsonBody`, signed JSON ingest. Bundle: `test:ci-phase715`. See [DEVICE_DISCOVERY_JSON.md](../../docs/DEVICE_DISCOVERY_JSON.md).
+
+**v0.8.690 (Phase 714):** `listSessionActivityJsonExports`, `listAvatarDecorationExportJsonExports`, `buildSessionActivityJsonBody`, `buildAvatarDecorationExportJsonBody`, signed JSON ingest. Bundle: `test:ci-phase714`. See [SESSION_ACTIVITY_JSON.md](../../docs/SESSION_ACTIVITY_JSON.md).
+
+**v0.8.667 (Phase 692):** `listDigestRelayHandoffJsonExports`, `listArchivePeerExportJsonExports`, relay/archive JSON ingest duplicate flags. Bundle: `test:ci-phase692`. See [DIGEST_RELAY_HANDOFF_JSON.md](../../docs/DIGEST_RELAY_HANDOFF_JSON.md).
+
+**v0.8.666 (Phase 691):** `listHookFailureDigestJsonExports`, `clearHookFailureDigestJsonExports`, digest JSON ingest duplicate flag. Bundle: `test:ci-phase691`. See [HOOK_FAILURE_DIGEST_JSON.md](../../docs/HOOK_FAILURE_DIGEST_JSON.md).
+
+**v0.8.665 (Phase 690):** `listAuditExportJsonExports`, `clearModDigestNotifyPrefs`, JSON ingest duplicate flag. Bundle: `test:ci-phase690`. See [AUDIT_JSON_MESH.md](../../docs/AUDIT_JSON_MESH.md).
+
+**v0.8.664 (Phase 689):** `clearDigestRelayHandoffs()`; ingest duplicate handoff flag; health dashboard rows via `buildAutomationHealthDashboard`. Bundle: `test:ci-phase689`. See [AUTOMATION_HEALTH.md](../../docs/AUTOMATION_HEALTH.md).
+
+**v0.8.663 (Phase 688):** Registry modal UX in `delivery-ui.js`; platform `delivery-mixin.js` gossip dedupe + partition heal; `DeliveryReceiptStore.clearAll()`; view slice `deliveryReceiptRows` (256); deep link `?receipts=1`. Bundle: `test:ci-phase688` (app repo). See [DELIVERY_METRICS.md](../../docs/DELIVERY_METRICS.md).
+
+**v0.8.566 (Phase 603):** Compliance panel live region `#compliance-panel-live`; compliance hub `aria-busy`; **compliance-errors** filter tighten; clipboard `compliancePanelLiveBusy`; platform `compliance.export` span; agentctl archive fetch/digest schedule refreshView re-verify. Bundle: `test:phase603-compliance` (app repo).
+
+**v0.8.565 (Phase 602):** Audit panel live region `#audit-panel-live`; audit hub `aria-busy`; **audit-errors** filter tighten; clipboard `auditPanelLiveBusy`; agentctl setAuditExportSchedule + export/filter refreshView re-verify. Bundle: `test:phase602-audit` (app repo).
+
+**v0.8.537 (Phase 574):** Platform `compliance.archive` span on `appendAuditExportArchive`; `digest.schedule` span on `setDigestExportSchedule`; compliance hub live region in app UI. Bundle: `test:phase574-compliance` (app repo). See [COMPLIANCE.md](../../docs/COMPLIANCE.md).
+
+**v0.8.536 (Phase 573):** Platform `audit.schedule` span + error logging on `setAuditExportSchedule`; audit hub live region in app UI. Bundle: `test:phase573-audit` (app repo). See [AUDIT.md](../../docs/AUDIT.md).
+
+**v0.8.450 (Phase 487):** Audit export archives and signed JSON metadata surfaced in UI compliance compositor + dev-log clipboard (`auditExportArchiveCount`, `auditExportSigned`). Bundle: `test:phase487-compliance` (app repo). See [COMPLIANCE.md](../../docs/COMPLIANCE.md).
+
+## Mission
+
+When `AppEventBridge` delivers an event, match enabled hooks, run actions (`log`, `notify`, `fanout-local`, `digest-relay`), record per-hook receipts, aggregate metrics, and support moderator dashboards (hook failure digests, audit export schedules, digest relay handoffs).
+
+## When to use / not
+
+**Use when:**
+
+- Dispatching automation hooks and persisting `DELIVERY_STATUS` rows.
+- Dry-running hooks (`dryRunHook`, `buildSampleAppEvent`).
+- Managing receipt retention, failure prefs, or export schedules.
+
+**Do not use when:**
+
+- You only define hooks — use `pearcord-automation-export`.
+- You only sign relay handoffs — use `pearcord-digest-relay-plugin`.
+
+## Public API (core)
+
+| Export | Role |
+|--------|------|
+| `AutomationHookDispatcher` | `dispatch(hooks, eventPayload)` → receipts |
+| `DeliveryReceiptStore` | Receipts, retention, schedules, digest snapshots, relay prefs |
+| `HookFailureAlertStore` | Recent failed-hook alerts (gossip) |
+| `hookMatchesEvent`, `createDeliveryReceipt` | Matching + row builder |
+| `buildDeliveryMetrics`, `buildHookFailureDigest` | Dashboard rollups |
+| `dryRunHook`, `dryRunHooks`, `buildSampleAppEvent` | Settings dry-run |
+| `DELIVERY_STATUS` | `delivered`, `skipped`, `failed` |
+
+## Public API (exports & dashboards)
+
+| Export | Role |
+|--------|------|
+| `formatAuditExport`, `filterAuditEntries`, `AUDIT_FILTER` | JSON/JSON audit bundles |
+| `formatHookFailureDigestExport`, `signHookFailureDigestJson`, `verifyHookFailureDigestJson` | Digest JSON |
+| `signAuditExportJson`, `verifyAuditExportJson` | Audit JSON signing stub |
+| `buildAutomationScheduleDashboard`, `buildAutomationHealthDashboard` | Overdue tasks + mesh health |
+| `buildDigestRelayHandoff` | P2P email-style handoff bundle |
+| `formatAutomationScheduleDigestExport` | Schedule + failure bundle |
+| `computeArchivePeerHealthScore`, `applyArchivePeerHealthDecay` | Peer scores 0–100 |
+| `formatHookFailureDigestDmSummary` | Mod DM text |
+| `mergeHookFailureDigests` | Local vs mesh merge |
+
+## Storage collections (selected)
+
+`@pearcord/delivery-receipts`, `hook-failure-alerts`, audit/digest export schedules, automation digest snapshots, digest relay handoffs, JSON export blobs, archive peer seen rows. Stored under `{storagePath}/delivery-receipts` via `JsonStore`.
+
+Defaults: max 256 receipts/guild (configurable 32–512), 7-day age prune.
+
+## P2P surface
+
+| Mechanism | Purpose |
+|-----------|---------|
+| `APP_EVENT_RECEIPT` gossip | Receipt replication |
+| Mesh slices | Retention prefs, failure prefs, schedules, JSON exports, handoffs |
+| Archive fetch | Pull audit archives / digest snapshots from peers with backoff |
+
+Pearcord core does not send SMTP or HTTP; `digest-relay` actions build handoffs for external bridges.
+
+## Platform integration
+
+`pearcord-platform` constructs `DeliveryReceiptStore`, `HookFailureAlertStore`, and `AutomationHookDispatcher` per guild, wiring `onLog` / `onNotify` / `onDigestRelay` to UI and `pearcord-digest-relay-plugin`.
+
+```javascript
+const { AutomationHookDispatcher, DeliveryReceiptStore } = require('pearcord-delivery-receipts')
+
+const dispatcher = new AutomationHookDispatcher({
+  store: receiptStore,
+  deliveredBy: userId,
+  onDigestRelay: async ({ hook, event }) => platform._buildDigestRelayHandoff(event)
+})
+await dispatcher.dispatch(hooks, appEventPayload)
+```
+
+## UI / IPC (selected)
+
+`dry-run-automation-hook`, `export-audit-log`, `sync-audit-export-json`, `export-hook-failure-digest`, `get-automation-schedule-dashboard`, `get-automation-health-dashboard`, `get-digest-relay-handoff`, `set-automation-receipt-retention`, schedule runners (`run-audit-export-now`, etc.).
+
+## Hook matching
+
+1. Hook enabled
+2. `categoryAllows(hook.categories, event.type)`
+3. If `filter.eventTypes` non-empty, type must be listed
+
+Skipped hooks still get a `skipped` receipt.
+
+## Code example
+
+```javascript
+const {
+  AutomationHookDispatcher,
+  DeliveryReceiptStore,
+  buildSampleAppEvent,
+  dryRunHook
+} = require('pearcord-delivery-receipts')
+const { APP_EVENTS } = require('pearcord-app-events')
+
+const sample = buildSampleAppEvent('g1', APP_EVENTS.MESSAGE_CREATE)
+const preview = dryRunHook(hook, sample)
+
+const store = new DeliveryReceiptStore({ storagePath: './pearcord-storage' })
+await store.ready()
+store.setGuild('g1')
+const dispatcher = new AutomationHookDispatcher({ store })
+await dispatcher.dispatch([hook], sample)
+```
+
+## Related modules
+
+- `pearcord-app-events` — event source
+- `pearcord-automation-export` — hook definitions
+- `pearcord-digest-relay-plugin` — relay signing + webhook dry-run
+- `pearcord-integration-worker` — headless webhook POST
+
+## Tests
+
+Extensive platform smokes for schedules, JSON verify, archive fetch, dry-run hooks
@@ -0,0 +1,89 @@
+{
+  "name": "pearcord-delivery-receipts",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "pearcord-delivery-receipts",
+      "version": "0.1.0",
+      "dependencies": {
+        "bare-path": "^3.0.0",
+        "pearcord-app-events": "file:../pearcord-app-events",
+        "pearcord-db": "file:../pearcord-db",
+        "pearcord-digest-relay-plugin": "file:../pearcord-digest-relay-plugin",
+        "pearcord-shared": "file:../pearcord-shared"
+      }
+    },
+    "../pearcord-app-events": {
+      "version": "0.1.0",
+      "dependencies": {
+        "bare-events": "^2.8.0",
+        "pearcord-bot-events": "file:../pearcord-bot-events",
+        "pearcord-shared": "file:../pearcord-shared"
+      }
+    },
+    "../pearcord-db": {
+      "version": "0.1.0",
+      "dependencies": {
+        "bare-fs": "^4.0.0",
+        "bare-path": "^3.0.0"
+      },
+      "optionalDependencies": {
+        "hyperdb": "^5.0.0",
+        "hyperschema": "^1.0.0"
+      }
+    },
+    "../pearcord-digest-relay-plugin": {
+      "version": "0.1.0",
+      "dependencies": {
+        "b4a": "^1.6.7",
+        "bare-fetch": "^3.0.0",
+        "hypercore-crypto": "^3.4.1",
+        "pearcord-shared": "file:../pearcord-shared"
+      }
+    },
+    "../pearcord-shared": {
+      "version": "0.1.0",
+      "dependencies": {
+        "b4a": "^1.6.7",
+        "compact-encoding": "^2.0.0",
+        "hypercore-crypto": "^3.0.0"
+      }
+    },
+    "node_modules/bare-os": {
+      "version": "3.9.1",
+      "resolved": "https://registry.npmjs.org/bare-os/-/bare-os-3.9.1.tgz",
+      "integrity": "sha512-6M5XjcnsygQNPMCMPXSK379xrJFiZ/AEMNBmFEmQW8d/789VQATvriyi5r0HYTL9TkQ26rn3kgdTG3aisbrXkQ==",
+      "license": "Apache-2.0",
+      "engines": {
+        "bare": ">=1.14.0"
+      }
+    },
+    "node_modules/bare-path": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/bare-path/-/bare-path-3.0.0.tgz",
+      "integrity": "sha512-tyfW2cQcB5NN8Saijrhqn0Zh7AnFNsnczRcuWODH0eYAXBsJ5gVxAUuNr7tsHSC6IZ77cA0SitzT+s47kot8Mw==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "bare-os": "^3.0.1"
+      }
+    },
+    "node_modules/pearcord-app-events": {
+      "resolved": "../pearcord-app-events",
+      "link": true
+    },
+    "node_modules/pearcord-db": {
+      "resolved": "../pearcord-db",
+      "link": true
+    },
+    "node_modules/pearcord-digest-relay-plugin": {
+      "resolved": "../pearcord-digest-relay-plugin",
+      "link": true
+    },
+    "node_modules/pearcord-shared": {
+      "resolved": "../pearcord-shared",
+      "link": true
+    }
+  }
+}
@@ -0,0 +1,14 @@
+{
+  "name": "pearcord-delivery-receipts",
+  "version": "0.1.0",
+  "main": "index.js",
+  "type": "commonjs",
+  "description": "P2P automation hook dispatch and APP_EVENT delivery receipts",
+  "dependencies": {
+    "bare-path": "^3.0.0",
+    "pearcord-digest-relay-plugin": "git+https://git.ssh.surf/pearcord/pearcord-digest-relay-plugin.git#main",
+    "pearcord-app-events": "git+https://git.ssh.surf/pearcord/pearcord-app-events.git#main",
+    "pearcord-db": "git+https://git.ssh.surf/pearcord/pearcord-db.git#main",
+    "pearcord-shared": "git+https://git.ssh.surf/pearcord/pearcord-shared.git#main"
+  }
+}