42 lines
2.5 KiB
Markdown
42 lines
2.5 KiB
Markdown
# 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.
|