README

aice-notification — Specification

The contract for the aice-notification polyglot delivery-only notification framework: the abstract port every consumer calls, the HTTP API the hosted/self-hosted notification-server exposes, and the conformance vectors every implementation must pass.

This repo delivers nothing itself and owns no credentials. Normative sources:

What this framework is

A thin delivery layer with exactly two channels in v1 — email and sms. The caller renders all content; the framework ships it verbatim:

sendEmail({ to, subject, text, html? }) → DeliveryReceipt
sendSms({ to, message })                → DeliveryReceipt

Failures are typed (invalid_recipient, invalid_payload, rate_limited, quota_exceeded, provider_unavailable, internal_error) so callers can distinguish retryable from permanent, with retry_after_seconds where retryable.

One port, two bindings

Consumers code against the port once and choose a binding by construction:

• Embedded (source-available, free): construct channel adapters with your own provider credentials (SMTP / email API / SMS gateway) in-process. Zero third-party visibility into your messages. Source under FSL-1.1 (converts to Apache-2.0 after 2 years).
• Hosted (paid): call the HTTP API with a per-tenant bearer API key (aice_ntf_…). You still bring your own provider credentials (BYO); the hosted service supplies ops, limits, and availability — never a shared sending account.

Relationship to aice-otp

aice-otp (v2) owns the OTP token lifecycle — minting, magic-link and numeric code redemption, expiry, supersede. Delivery of the minted link/code is out of scope there and in scope here: the otp issuer is simply a consumer of this port. This framework never mints, stores, verifies, or interprets payloads.

Non-goals (v1)

No queues/retries/scheduled send · no status webhooks/analytics · no template storage or engine · no whatsapp/push/voice · no shared/central sending account · no browser/mobile callers (server-to-server only).

Conformance

Implementations vendor vectors/ byte-for-byte and must pass all of them. The in-tree Go runner demonstrates the harness contract:

cd conformance/runner && go run ./cmd/aice-notification-conformance ../../vectors

License

FSL-1.1-Apache-2.0 (see LICENSE).

This is a snapshot generated from GitLab. For the live README, see the project page.