2.5 KiB
Notifications service contract
This independent module owns the public internal-service contract. The canonical
source is proto/v1/interface.proto; it defines Send, Get, requests, statuses
and email/SMS/push/Telegram targets. The executable currently implements email.
From the repository root, make generate-notifications produces Go/gRPC client
bindings in notifications/v1. Generated .pb.go files are ignored and must not
be committed. Both backend validation targets generate bindings before compiling.
The generators are pinned in the Makefile; install protoc separately.
make package-notifications-interface creates a distributable source archive and
a standalone Go client-module archive under dist/. Client consumers can generate
bindings for their own language from the source archive. The Go archive contains
the generated bindings and its own go.mod/go.sum, with no executable or shared
infrastructure dependency. Archive generation does not upload to a registry.
Internal Go consumers use the module
git.sendico.io/tech/sxchnge/notifications/interface and import
git.sendico.io/tech/sxchnge/notifications/interface/notifications/v1. Within this
checkout, use a local replace to this directory and generate before building.
Calls use the trusted private network without caller authentication. The service uses the existing product storage namespace. Callers authorize user/destination ownership and preferences before sending; this contract is not a public user API.
Parameters are string values keyed by template parameter name. The entire request is validated before persistence. An identical idempotency key/request returns the original resource, even after completion or expiry. A changed request conflicts. Keys are scoped to the product namespace and retained at least seven days; Mongo TTL deletion is asynchronous. Expiry defaults to 24 hours and cannot exceed 24 hours. One email target is accepted; other declared channels return UNIMPLEMENTED.
ACCEPTED means provider acceptance, not delivery or reading. UNKNOWN means the provider may have sent the message and automatic replay is unsafe. DELIVERED is reserved for a future receipt implementation. Get never exposes recipient addresses, rendered content, parameters, provider credentials or raw provider responses.
Keep published template revisions and field numbers stable. Reserve removed protobuf field/enum names and numbers. Compatible additions belong in v1; incompatible changes require a new version.