diff --git a/NOTIFICATION_PAYLOAD_SCHEMA.md b/NOTIFICATION_PAYLOAD_SCHEMA.md index bb842c3..15bdaf0 100644 --- a/NOTIFICATION_PAYLOAD_SCHEMA.md +++ b/NOTIFICATION_PAYLOAD_SCHEMA.md @@ -18,7 +18,7 @@ This document defines the structure, required fields, validation rules, and exam When scheduling a notification via the REST API, the caller provides a `CreateScheduledNotificationInput` object. The listener stores this, then delivers it at the specified time through the chosen channel (Discord, email, webhook, or SMS). -**Endpoint:** `POST /api/notifications/schedule` +**Endpoint:** `POST /api/schedule` --- diff --git a/README.md b/README.md index 67bdff5..c11c1ed 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,9 @@ The project enables developers to build reactive decentralized applications with 10. [License](#license) > **Listener service docs**: +> - [API Contract and Event Reference](listener/API_CONTRACT_EVENT_REFERENCE.md) +> - [API Usage Cookbook](listener/API_USAGE_COOKBOOK.md) +> - [Notification Failure Recovery](NOTIFICATION_FAILURE_RECOVERY.md) — retry lifecycle, configuration, and troubleshooting. > [Notification Lifecycle](NOTIFICATION_LIFECYCLE.md) — creation, delivery, acknowledgment semantics, retries, and archival. > [Notification Failure Recovery](NOTIFICATION_FAILURE_RECOVERY.md) — retry lifecycle, configuration, and troubleshooting. > **Listener service docs**: [Notification Failure Recovery](NOTIFICATION_FAILURE_RECOVERY.md) — retry lifecycle, configuration, and troubleshooting. diff --git a/listener/API_CONTRACT_EVENT_REFERENCE.md b/listener/API_CONTRACT_EVENT_REFERENCE.md new file mode 100644 index 0000000..b2c989a --- /dev/null +++ b/listener/API_CONTRACT_EVENT_REFERENCE.md @@ -0,0 +1,86 @@ +# API Contract and Event Reference Guide + +This guide is the single entry point for integrators that need endpoint contracts, +payload schemas, auth requirements, and emitted contract events. + +## Canonical docs map + +1. Endpoint contract (paths, request/response schema, errors): [`API.md`](API.md) +2. Workflow cookbook (copy/paste examples): [`API_USAGE_COOKBOOK.md`](API_USAGE_COOKBOOK.md) +3. Notification payload schema details: [`../NOTIFICATION_PAYLOAD_SCHEMA.md`](../NOTIFICATION_PAYLOAD_SCHEMA.md) +4. On-chain event structs (AutoShare): `contract/contracts/hello-world/src/base/events.rs` + +## Public API endpoints + +| Endpoint | Method | Purpose | +|---|---|---| +| `/api/events` | GET | Return latest indexed contract events | +| `/api/status` | GET | Return listener runtime status | +| `/api/indexing/health` | GET | Return indexing health details | +| `/api/analytics` | GET | Return analytics summaries | +| `/api/webhooks` | POST | Accept signed inbound webhook payloads | +| `/api/schedule` | POST | Create scheduled notification | +| `/api/schedule/stats` | GET | Return scheduler aggregate stats | +| `/api/schedule/:id` | GET | Return scheduled notification by ID | +| `/api/preferences/:userId` | GET/PUT | Read/update user notification preferences | +| `/api/rate-limit/metrics` | GET | Rate limiter metrics endpoint | +| `/api/notifications/history` | GET | Notification delivery history | +| `/api/search/suggestions` | GET | Search suggestion API | +| `/api/templates` | POST | Create notification template | +| `/api/templates/:id` | GET/PUT | Read/update template | +| `/api/templates/:id/audit` | GET | Template audit trail | +| `/api/archive` | GET | Archive listing | +| `/api/archive/:id` | GET | Archive item lookup | +| `/api/archive/run` | POST | Run archive process | +| `/health` | GET | Dependency and readiness health | + +## Authentication and authorization + +- API clients can be identified by `X-API-Key` or `Authorization: Bearer `. +- `POST /api/webhooks` requires: + - `X-Key-Id` + - `X-Signature` (HMAC-SHA256 of the raw request body) +- Every response includes `X-Request-Id` and `X-Correlation-Id` for tracing. + +## Event reference (AutoShare contract) + +From `contract/contracts/hello-world/src/base/events.rs`: + +- `AutoshareCreated` +- `ContractPaused` +- `ContractUnpaused` +- `AutoshareUpdated` +- `GroupDeactivated` +- `GroupActivated` +- `AdminTransferred` +- `Withdrawal` +- `AuthorizationFailure` +- `ScheduledNotificationCancelled` +- `NotificationScheduled` +- `NotificationExpired` +- `NotificationRevoked` +- `NotificationExtended` + +Each event carries category and priority topics for filtering/routing. + +## Versioning guidelines + +- Current API contract version is **v1** (documented in `API.md` and schema docs). +- Backward-compatible additions (new optional fields/endpoints) are treated as minor updates. +- Breaking changes (removing required fields, renaming fields, incompatible response shape changes) require: + 1. major version bump in docs, + 2. changelog entry, + 3. deprecation note before rollout. + +## Quick verification commands + +```bash +# Health +curl -sS http://localhost:8787/health | jq + +# Events +curl -sS 'http://localhost:8787/api/events?limit=5' | jq + +# Scheduler stats +curl -sS http://localhost:8787/api/schedule/stats | jq +``` diff --git a/listener/API_USAGE_COOKBOOK.md b/listener/API_USAGE_COOKBOOK.md index f9dcde7..b8dbdaf 100644 --- a/listener/API_USAGE_COOKBOOK.md +++ b/listener/API_USAGE_COOKBOOK.md @@ -1,6 +1,6 @@ # NotifyChain Listener — API Usage Cookbook -> **Companion to [`listener/API.md`](listener/API.md).** The reference +> **Companion to [`API.md`](API.md).** The reference > document lists every endpoint, header, and response shape. This cookbook > shows how to combine those endpoints to ship common workflows. Every > example is a real `curl` invocation you can paste into a terminal once @@ -330,7 +330,7 @@ curl -sS -X PUT http://localhost:8787/api/preferences/alice \ > **Note:** this PUT is a *patch*, not a *replace*. Unspecified > categories keep their current value. If you need to wipe a user back -> to defaults, see the [preferences API reference](listener/API.md#put-apipreferencesuserid). +> to defaults, see the [preferences API reference](API.md#put-apipreferencesuserid). --- @@ -423,7 +423,7 @@ grep "requestId=$REQ_ID" listener.log |------|-------------------------------------------------|-------------------------------------------------| | 400 | Missing required field or invalid date format | Re-read [Workflow 2](#workflow-2--schedule-a-future-notification) request body shape | | 401 | Bad HMAC signature or missing X-API-Key | [Workflow 3 — verify signature](#workflow-3--accept-signed-webhooks) | -| 404 | Unknown endpoint or notification ID | Confirm the URL matches [`listener/API.md`](listener/API.md) | +| 404 | Unknown endpoint or notification ID | Confirm the URL matches [`API.md`](API.md) | | 429 | Rate limit exceeded | Back off and retry after `Retry-After` seconds | | 500 | Internal exception (DB lock, panic, etc.) | Capture `X-Request-Id` and grep listener logs | | 503 | Scheduler disabled, or upstream RPC unreachable | Check `notificationAPI` config / `STELLAR_RPC_URL` | @@ -507,7 +507,7 @@ curl -sS -X POST http://localhost:8787/api/schedule \ | Listener logs spam `Webhook missing signature header` | An external system is hitting `/api/webhooks` unsigned | Either configure that system to sign, or block it upstream | For full schema details and the complete error reference, see -[`listener/API.md`](listener/API.md). +[`API.md`](API.md). --- @@ -551,8 +551,8 @@ For full schema details and the complete error reference, see ## See also -- [`listener/API.md`](listener/API.md) — full request/response reference for every endpoint -- [`NOTIFICATION_FAILURE_RECOVERY.md`](NOTIFICATION_FAILURE_RECOVERY.md) — retry lifecycle, configuration, and recovery -- [`NOTIFICATION_PAYLOAD_SCHEMA.md`](NOTIFICATION_PAYLOAD_SCHEMA.md) — contract event payload shape and interpretation -- [`SCHEDULED-NOTIFICATIONS-DELIVERY.md`](SCHEDULED-NOTIFICATIONS-DELIVERY.md) — scheduler internals and tuning -- [`TROUBLESHOOTING.md`](TROUBLESHOOTING.md) — general listener troubleshooting +- [`API.md`](API.md) — full request/response reference for every endpoint +- [`../NOTIFICATION_FAILURE_RECOVERY.md`](../NOTIFICATION_FAILURE_RECOVERY.md) — retry lifecycle, configuration, and recovery +- [`../NOTIFICATION_PAYLOAD_SCHEMA.md`](../NOTIFICATION_PAYLOAD_SCHEMA.md) — notification payload schema and interpretation +- [`../SCHEDULED-NOTIFICATIONS-DELIVERY.md`](../SCHEDULED-NOTIFICATIONS-DELIVERY.md) — scheduler internals and tuning +- [`../TROUBLESHOOTING.md`](../TROUBLESHOOTING.md) — general listener troubleshooting