c68883bd69
Phase 1 RFC-004 prep — define the event contract that the notifications module will publish through the Phase 0 outbox + Redis Streams backbone. - Add notification.requested.schema.json (JSON Schema 2020-12) covering notificationId, userId, category, template, params, channels, locale, priority, dedupeKey, requestedAt - Add NotificationRequestedPayload + supporting union types (NotificationCategory, NotificationChannel, NotificationLocale, NotificationPriority) to @goodgo/contracts-events barrel - Register 'notification.requested' in KNOWN_EVENT_TYPES Pure contract addition; no producer/consumer wiring yet (follow-up commits in this branch will introduce the publisher refactor + BullMQ worker). Co-Authored-By: Paperclip <noreply@paperclip.ing>
@goodgo/contracts-events
Cross-runtime (Node + Python) event contracts for RFC-004's async messaging backbone. See GOO-95 for the RFC and GOO-172 for Phase 0.
What lives here
src/envelope.ts—EventEnvelope<T>TypeScript type +EVENT_ENVELOPE_SCHEMA_VERSION.src/uuid-v7.ts— pure-Node UUIDv7 generator (no runtime deps).src/event-types.ts— string-literal union of all known event types.schemas/envelope.schema.json— JSON Schema for the envelope itself.schemas/<event-type>.schema.json— JSON Schema for each event payload.
The schemas/ directory is consumed by the Python AI services
(libs/ai-services) via redis-py consumers — JSON Schema is the single
source of truth across runtimes.
Envelope shape
interface EventEnvelope<TPayload = unknown> {
schemaVersion: number; // bump when envelope itself changes
eventId: string; // UUIDv7 — time-ordered, idempotency key
eventType: string; // dotted: "payment.completed"
occurredAt: string; // ISO-8601 UTC
producer: string; // service name, e.g. "api"
traceId: string; // OpenTelemetry-compatible (32 hex chars or "00…")
payload: TPayload; // event-specific, validated by per-type schema
}
schemaVersion starts at 1. Bump only when the envelope changes;
payload changes are versioned per event-type schema independently.
First 3 schemas (Phase 0 deliverable)
| Event type | Trigger |
|---|---|
payment.completed |
Payment moves to succeeded after gateway IPN |
listing.approved |
Moderation approves a listing |
kyc.verified |
KYC review marks a user verified |
Phase 1 (notifications cutover, GOO-173) will add the rest of the production event surface.
Adding a new event type
- Pick a stable dotted name (
<aggregate>.<past-tense-verb>). - Add a
schemas/<name>.schema.jsonJSON Schema describing the payload. - Add the literal to
src/event-types.ts. - (Optional) Re-export a typed payload alias from
src/index.ts. - Land + dual-publish for at least one sprint before any consumer hard-fails on it.