[Documentation] Resolve #138 and #183 API cookbook + contract reference

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`
 
 ---
 

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.

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 <token>`.
+- `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
+```

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