pearcord/pearcord-delivery-receipts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
1 Commit 1 Branch 0 Tags
3911aaa2efd2f0b76541673751a8460be540d59a
T
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE

README.md

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.

v0.8.690 (Phase 714): listSessionActivityJsonExports, listAvatarDecorationExportJsonExports, buildSessionActivityJsonBody, buildAvatarDecorationExportJsonBody, signed JSON ingest. Bundle: test:ci-phase714. See 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.

v0.8.666 (Phase 691): listHookFailureDigestJsonExports, clearHookFailureDigestJsonExports, digest JSON ingest duplicate flag. Bundle: test:ci-phase691. See 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.

v0.8.664 (Phase 689): clearDigestRelayHandoffs(); ingest duplicate handoff flag; health dashboard rows via buildAutomationHealthDashboard. Bundle: test:ci-phase689. See 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.

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.

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.

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.

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.

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

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

Reference in New Issue View Git Blame Copy Permalink
S
Description
Pearcord module: pearcord-delivery-receipts
Readme
1.2 MiB
Languages
JavaScript 100%