437 lines
18 KiB
Markdown
437 lines
18 KiB
Markdown
<!-- markdownlint-disable MD024 -->
|
|
|
|
# Capability Spec Delta: sms (sms)
|
|
|
|
**Package**: `@suaveplan/sms`
|
|
**Status**: PROPOSED
|
|
|
|
> Every requirement below carries a `**Verified by:**` line at authoring time.
|
|
|
|
## ADDED Requirements
|
|
|
|
### Requirement: Public package surface
|
|
|
|
The package SHALL export, from its root barrel `src/index.ts`, the
|
|
full upstream surface: `SmsService`, the `SmsProvider` interface,
|
|
`SmsMessage`, `SmsDeliveryReport`, `SmsDeliveryStatus`,
|
|
`OptOutEntry`, `SmsTemplate`, `SmsEventMap`, the legacy `SmsError`
|
|
class with its factory methods, `SmsErrorCode`, `SmsErrorContext`,
|
|
`SmsErrorOptions`, `respondProblemJson`, `PROBLEM_JSON_CONTENT_TYPE`,
|
|
`registerSmsErrorCodes`, `SMS_ERROR_METADATA`, and
|
|
`SmsRegisteredErrorCode`. It SHALL additionally export the genesis
|
|
additions: `SMS_CODES`, every leaf error class, every Zod schema,
|
|
`TemplateRegistry`, `OptOutRegistry`, `RateLimiter`, `RetryPolicy`,
|
|
`MessageScheduler`, `DeliveryTracker`, `InMemorySmsProvider`,
|
|
`renderTemplate`, `isValidE164`, and the OTel `record*` helpers.
|
|
|
|
#### Scenario: every upstream symbol is re-exported
|
|
|
|
- **WHEN** a consumer imports from `@suaveplan/sms`
|
|
- **THEN** `SmsService`, `SmsProvider` (type), `SmsMessage` (type),
|
|
`SmsDeliveryReport` (type), `SmsDeliveryStatus` (type),
|
|
`OptOutEntry` (type), `SmsTemplate` (type), `SmsEventMap` (type),
|
|
`SmsError`, `respondProblemJson`, `PROBLEM_JSON_CONTENT_TYPE`,
|
|
`registerSmsErrorCodes`, `SMS_ERROR_METADATA` are all defined
|
|
|
|
**Verified by:** `src/service/sms-service.test.ts::"re-exports the full upstream surface"`
|
|
|
|
---
|
|
|
|
### Requirement: Stable SMS error-code registry
|
|
|
|
The package SHALL register exactly thirteen error codes via
|
|
`defineCodes("SMS", [...])`: `INVALID_NUMBER`, `INVALID_CONFIG`,
|
|
`PROVIDER_NOT_CONFIGURED`, `PROVIDER_ERROR`, `SEND_FAILED`,
|
|
`TEMPLATE_NOT_FOUND`, `RECIPIENT_OPTED_OUT`, `RATE_LIMITED`,
|
|
`FORBIDDEN`, `CONFIG_MISSING`, `SCHEDULE_CANCELLED`, `ABORTED`,
|
|
`RECEIPT_NOT_FOUND`. Every code SHALL be reachable from at least
|
|
one production call site and SHALL be asserted by a test that
|
|
triggers the real call site.
|
|
|
|
#### Scenario: every code is reachable from a production call site
|
|
|
|
- **WHEN** the package is fully built
|
|
- **THEN** for each of the thirteen codes there exists at least one
|
|
test that triggers the production call site whose `throw` (or
|
|
caught error) carries that code
|
|
|
|
**Verified by:** `src/error-codes/error-codes.test.ts::"every SMS code is reachable from a production call site"`
|
|
|
|
---
|
|
|
|
### Requirement: Legacy SmsError back-compat
|
|
|
|
The package SHALL preserve the upstream `SmsError` class with the
|
|
exact `SmsErrorCode` union (`SMS_INVALID_PHONE_NUMBER`,
|
|
`SMS_SEND_FAILED`, `SMS_TEMPLATE_NOT_FOUND`,
|
|
`SMS_RECIPIENT_OPTED_OUT`, `SMS_PROVIDER_NOT_CONFIGURED`) and the
|
|
five static factory methods (`invalidPhoneNumber`, `sendFailed`,
|
|
`templateNotFound`, `recipientOptedOut`, `providerNotConfigured`)
|
|
plus the `isSmsError` type guard. The legacy class SHALL also carry
|
|
the same `SmsErrorContext` and `SmsErrorOptions` shapes.
|
|
|
|
#### Scenario: legacy factories return SmsError instances
|
|
|
|
- **WHEN** `SmsError.invalidPhoneNumber("xx")` is called
|
|
- **THEN** the returned value is `instanceof SmsError`, `code` is
|
|
`"SMS_INVALID_PHONE_NUMBER"`, and `SmsError.isSmsError(value)` is
|
|
`true`
|
|
|
|
**Verified by:** `src/legacy-errors/legacy-errors.test.ts::"factory methods return the right code"` AND `src/legacy-errors/legacy-errors.test.ts::"isSmsError narrows the type"`
|
|
|
|
---
|
|
|
|
### Requirement: Legacy metadata registration
|
|
|
|
The package SHALL ship `SMS_ERROR_METADATA` containing the six
|
|
upstream metadata entries (`SMS_SEND_FAILED`, `SMS_PROVIDER_ERROR`,
|
|
`SMS_INVALID_NUMBER`, `SMS_RATE_LIMITED`, `SMS_CONFIG_MISSING`,
|
|
`SMS_FORBIDDEN`) with the same `httpStatus` / `severity` / `retry` /
|
|
`userMessageKey` / `category` / `description` fields, and SHALL
|
|
register every entry on the shared `ErrorCodes` singleton via
|
|
`registerSmsErrorCodes()` at module load time. The function SHALL
|
|
be idempotent.
|
|
|
|
#### Scenario: SMS_RATE_LIMITED maps to HTTP 429
|
|
|
|
- **WHEN** `SMS_ERROR_METADATA.SMS_RATE_LIMITED` is read after
|
|
`registerSmsErrorCodes()` has run
|
|
- **THEN** the entry has `httpStatus === 429`, `severity ===
|
|
"warning"`, and `retry.retryable === true`
|
|
|
|
**Verified by:** `src/legacy-metadata/legacy-metadata.test.ts::"every metadata entry preserves the upstream shape"`
|
|
|
|
---
|
|
|
|
### Requirement: E.164 phone validation
|
|
|
|
`isValidE164(value)` SHALL return `true` only when `value` matches
|
|
`/^\+[1-9]\d{1,14}$/`. The service SHALL reject every `send()` call
|
|
whose `message.to` fails this check by throwing
|
|
`SmsInvalidNumberError` (code `SMS.INVALID_NUMBER`).
|
|
|
|
#### Scenario: valid +15551234567 passes
|
|
|
|
- **WHEN** `isValidE164("+15551234567")` is called
|
|
- **THEN** the return value is `true`
|
|
|
|
#### Scenario: missing leading + is rejected
|
|
|
|
- **WHEN** `isValidE164("15551234567")` is called
|
|
- **THEN** the return value is `false`
|
|
|
|
#### Scenario: leading +0 is rejected
|
|
|
|
- **WHEN** `isValidE164("+0123456789")` is called
|
|
- **THEN** the return value is `false`
|
|
|
|
**Verified by:** `src/validation/phone.test.ts::"accepts E.164 numbers"` AND `src/validation/phone.test.ts::"rejects non-E.164 inputs"`
|
|
|
|
---
|
|
|
|
### Requirement: Zod boundary on public inputs
|
|
|
|
`schemas/schemas.ts` SHALL export Zod schemas for `SmsMessage`,
|
|
`SmsTemplate`, `SmsDeliveryReport`, and `SmsServiceOptions`. The
|
|
parser helpers `parseSmsMessage` and `parseSmsTemplate` SHALL throw
|
|
`SmsInvalidConfigError` (code `SMS.INVALID_CONFIG`) with
|
|
`context.issues` containing the Zod issues on rejection.
|
|
|
|
#### Scenario: empty body is rejected
|
|
|
|
- **WHEN** `parseSmsMessage({ to: "+15551234567", body: "" })` is
|
|
called
|
|
- **THEN** the call throws `SmsInvalidConfigError` whose `code` is
|
|
`SMS.INVALID_CONFIG` and whose `context.issues` is a non-empty
|
|
array
|
|
|
|
**Verified by:** `src/schemas/schemas.test.ts::"rejects empty body"` AND `src/schemas/schemas.test.ts::"rejects non-E.164 to"`
|
|
|
|
---
|
|
|
|
### Requirement: Template registry and render
|
|
|
|
`TemplateRegistry` SHALL provide `register(template)`,
|
|
`get(id)`, `has(id)`, `unregister(id)`, and `list()`. `renderTemplate(template, vars, defaults?)` SHALL replace every `{{var}}` placeholder declared in `template.variables` with `vars[var] ?? defaults?.[var] ?? ""`.
|
|
|
|
#### Scenario: rendering substitutes declared variables
|
|
|
|
- **WHEN** `renderTemplate({ id: "x", body: "Hello {{name}}", variables: ["name"] }, { name: "Alice" })` is called
|
|
- **THEN** the returned string is `"Hello Alice"`
|
|
|
|
#### Scenario: missing variables default to empty string
|
|
|
|
- **WHEN** `renderTemplate({ id: "x", body: "Hi {{name}}", variables: ["name"] }, {})` is called
|
|
- **THEN** the returned string is `"Hi "`
|
|
|
|
#### Scenario: defaults map fills missing variables
|
|
|
|
- **WHEN** `renderTemplate({ id: "x", body: "Hi {{name}}", variables: ["name"] }, {}, { name: "World" })` is called
|
|
- **THEN** the returned string is `"Hi World"`
|
|
|
|
**Verified by:** `src/templates/templates.test.ts::"substitutes declared variables"` AND `src/templates/templates.test.ts::"missing variables fall back to defaults then empty string"` AND `src/templates/templates.test.ts::"registry register/get/has/unregister/list"`
|
|
|
|
---
|
|
|
|
### Requirement: Opt-out registry
|
|
|
|
`OptOutRegistry` SHALL provide `add(phoneNumber, channel?)`,
|
|
`remove(phoneNumber)`, `has(phoneNumber)`, `list()`,
|
|
`importEntries(entries)`, and `clear()`. `SmsService` SHALL reject
|
|
every `send()` to an opted-out recipient with
|
|
`SmsRecipientOptedOutError` (code `SMS.RECIPIENT_OPTED_OUT`).
|
|
|
|
#### Scenario: opt-out blocks send
|
|
|
|
- **WHEN** a recipient is added via `optOut(phone)` and `service.send({to: phone, ...})` is called
|
|
- **THEN** the send throws `SmsRecipientOptedOutError`
|
|
|
|
#### Scenario: opt-in clears the registry entry
|
|
|
|
- **WHEN** `optIn(phone)` is called for an opted-out recipient
|
|
- **THEN** `isOptedOut(phone)` returns `false`
|
|
|
|
**Verified by:** `src/opt-out/opt-out.test.ts::"add/remove/has/list/clear"` AND `src/service/sms-service.test.ts::"opt-out blocks send"` AND `src/service/sms-service.test.ts::"opt-in unblocks send"`
|
|
|
|
---
|
|
|
|
### Requirement: Rate limiter
|
|
|
|
`RateLimiter` SHALL implement a token bucket with `capacity` and
|
|
`refillPerSecond`, keyed by an arbitrary string key. `tryConsume(key)` SHALL return `true` when a token is available and `false` otherwise, refilling tokens against an injectable `Clock`. `SmsService` SHALL throw `SmsRateLimitedError` (code `SMS.RATE_LIMITED`) when the limiter rejects.
|
|
|
|
#### Scenario: bucket exhausts after capacity tokens
|
|
|
|
- **WHEN** `tryConsume("k")` is called `capacity + 1` times in a row without time advancing
|
|
- **THEN** the first `capacity` calls return `true` and the last returns `false`
|
|
|
|
#### Scenario: time advances refill tokens
|
|
|
|
- **WHEN** the bucket is exhausted and the injected clock is advanced by `1000ms` with `refillPerSecond = 1`
|
|
- **THEN** the next `tryConsume("k")` returns `true`
|
|
|
|
**Verified by:** `src/rate-limiter/rate-limiter.test.ts::"exhausts after capacity"` AND `src/rate-limiter/rate-limiter.test.ts::"refills on clock advance"` AND `src/service/sms-service.test.ts::"rate-limited recipient throws SmsRateLimitedError"`
|
|
|
|
---
|
|
|
|
### Requirement: Retry policy
|
|
|
|
`RetryPolicy` SHALL retry a thrown attempt up to
|
|
`maxAttempts` times with exponential backoff
|
|
(`initialDelayMs * 2^(attempt - 1)`, capped at `maxDelayMs`) and
|
|
full jitter. Each retry SHALL be awaited against an injectable
|
|
`Timers.delay(ms, signal)`. An aborted retry SHALL throw
|
|
`SmsAbortedError` (code `SMS.ABORTED`).
|
|
|
|
#### Scenario: succeeds on second attempt
|
|
|
|
- **WHEN** a callback fails once then succeeds
|
|
- **THEN** the policy returns the success value and emits one retry event
|
|
|
|
#### Scenario: exhausts attempts and rethrows
|
|
|
|
- **WHEN** a callback fails on every attempt
|
|
- **THEN** the policy rethrows the last error after `maxAttempts` invocations
|
|
|
|
#### Scenario: abort signal halts retries
|
|
|
|
- **WHEN** the signal aborts between attempts
|
|
- **THEN** the policy throws `SmsAbortedError`
|
|
|
|
**Verified by:** `src/retry/retry.test.ts::"succeeds on second attempt"` AND `src/retry/retry.test.ts::"exhausts attempts"` AND `src/retry/retry.test.ts::"abort halts retries"`
|
|
|
|
---
|
|
|
|
### Requirement: Message scheduler
|
|
|
|
`MessageScheduler.scheduleAt(date, fn)` SHALL invoke `fn` at the
|
|
target time through an injectable `Timers.setTimeout`-like seam and
|
|
return a `ScheduleHandle` with `cancel()`. A cancelled handle SHALL
|
|
not invoke `fn`. `SmsService.scheduleAt(date, message)` SHALL emit
|
|
`sms.scheduled` on the bus when the message is queued, and route
|
|
the eventual send through the full pipeline. A cancelled schedule
|
|
SHALL emit `sms.failed` with code `SMS.SCHEDULE_CANCELLED`.
|
|
|
|
#### Scenario: scheduled message fires at the target time
|
|
|
|
- **WHEN** a message is scheduled for `now + 100ms` and the injected timer fires
|
|
- **THEN** the provider's `send` is invoked exactly once
|
|
|
|
#### Scenario: cancelled schedule does not fire
|
|
|
|
- **WHEN** `cancel()` is called before the timer fires
|
|
- **THEN** the provider's `send` is not invoked
|
|
|
|
**Verified by:** `src/scheduler/scheduler.test.ts::"fires at the target time"` AND `src/scheduler/scheduler.test.ts::"cancel prevents firing"` AND `src/service/sms-service.test.ts::"scheduleAt routes through the pipeline"`
|
|
|
|
---
|
|
|
|
### Requirement: Delivery tracker
|
|
|
|
`DeliveryTracker` SHALL accept incoming delivery receipts via
|
|
`ingest(report)` and return the latest cached status via
|
|
`getStatus(messageId)`. The cache SHALL be bounded by an LRU policy
|
|
with configurable `maxEntries` (default `1024`). `lookupOrFetch(messageId, provider)` SHALL fall back to the provider's `getStatus`
|
|
when no cached entry exists, caching the result. Cache miss with no
|
|
provider SHALL throw `SmsReceiptNotFoundError` (code
|
|
`SMS.RECEIPT_NOT_FOUND`).
|
|
|
|
#### Scenario: ingested receipt is retrievable
|
|
|
|
- **WHEN** a report with `messageId: "m1"` is ingested then
|
|
`getStatus("m1")` is called
|
|
- **THEN** the returned report deep-equals the ingested report
|
|
|
|
#### Scenario: LRU eviction drops the oldest entry
|
|
|
|
- **WHEN** `maxEntries = 2` and three reports `m1`, `m2`, `m3` are
|
|
ingested in order
|
|
- **THEN** `getStatus("m1")` returns `undefined`
|
|
|
|
**Verified by:** `src/delivery-tracker/delivery-tracker.test.ts::"ingest/getStatus round-trip"` AND `src/delivery-tracker/delivery-tracker.test.ts::"LRU eviction"` AND `src/delivery-tracker/delivery-tracker.test.ts::"lookupOrFetch falls back to provider"` AND `src/delivery-tracker/delivery-tracker.test.ts::"miss without provider throws receipt-not-found"`
|
|
|
|
---
|
|
|
|
### Requirement: In-memory provider
|
|
|
|
`InMemorySmsProvider` SHALL implement `SmsProvider` with `name` =
|
|
`"in-memory"`, deliver every message synchronously into a `sent`
|
|
log, and return a `SmsDeliveryReport` with `status` controlled by
|
|
the constructor's `defaultStatus` (default `"sent"`). It SHALL
|
|
expose `sent`, `clear()`, `setStatus(messageId, status)`, and
|
|
`failOn(predicate, error)` so tests can simulate provider failures
|
|
and status transitions without external services.
|
|
|
|
#### Scenario: send appends to the sent log
|
|
|
|
- **WHEN** `provider.send({ to: "+15551234567", body: "x" })` is
|
|
called
|
|
- **THEN** `provider.sent` has length 1 and the entry's `to` is
|
|
`"+15551234567"`
|
|
|
|
#### Scenario: failOn triggers a thrown error
|
|
|
|
- **WHEN** `provider.failOn(msg => msg.to === "+15550000000", new Error("boom"))` is set and `send({to: "+15550000000", body: "x"})` is called
|
|
- **THEN** the call rejects with the configured error
|
|
|
|
**Verified by:** `src/in-memory-provider/in-memory-provider.test.ts::"send appends to log"` AND `src/in-memory-provider/in-memory-provider.test.ts::"failOn triggers"` AND `src/in-memory-provider/in-memory-provider.test.ts::"setStatus transitions delivery state"`
|
|
|
|
---
|
|
|
|
### Requirement: OpenTelemetry instruments
|
|
|
|
The package SHALL register four OTel instruments on the
|
|
`@suaveplan/sms` meter: counters `sms.sent_total`,
|
|
`sms.failed_total`, `sms.retry_total`, and histogram
|
|
`sms.send_duration_ms`. The module SHALL expose `record*` helpers
|
|
and a `refreshSmsMeters()` re-bind for tests.
|
|
|
|
#### Scenario: successful send records sent_total + send_duration_ms
|
|
|
|
- **WHEN** `service.send(validMessage)` is called against an
|
|
in-memory provider
|
|
- **THEN** an in-memory metric exporter reads at least one data
|
|
point on `sms.sent_total` and one on `sms.send_duration_ms`
|
|
|
|
**Verified by:** `src/otel/metrics.test.ts::"refresh re-binds against the global provider"` AND `src/service/sms-service.test.ts::"send records sent_total and send_duration_ms"`
|
|
|
|
---
|
|
|
|
### Requirement: Typed EventBus + legacy on/off mirror
|
|
|
|
`SmsService` SHALL expose a typed `EventBus<SmsEventMap>` field
|
|
named `bus`, AND a legacy `on/off/emit` surface that mirrors against
|
|
the bus. Topics: `sms.sent`, `sms.delivered`, `sms.failed`,
|
|
`sms.opted_out`, `sms.opted_in`, `sms.scheduled`, `sms.retry`,
|
|
`sms.rate_limited`.
|
|
|
|
#### Scenario: legacy on/off mirrors the bus
|
|
|
|
- **WHEN** a listener is registered via `service.on("sms.sent", h)`
|
|
and the service emits `sms.sent`
|
|
- **THEN** the handler is invoked exactly once with the report
|
|
|
|
#### Scenario: bus.on receives the same payload
|
|
|
|
- **WHEN** `service.bus.on("sms.sent", h)` is registered before a
|
|
send
|
|
- **THEN** the bus handler is invoked with the same report payload
|
|
|
|
**Verified by:** `src/service/sms-service.test.ts::"legacy on/off mirrors the bus"` AND `src/service/sms-service.test.ts::"bus receives emitted reports"`
|
|
|
|
---
|
|
|
|
### Requirement: Abort signal propagation
|
|
|
|
`SmsService.send(message, { signal })` SHALL propagate the abort
|
|
signal through the rate limiter, retry policy, and provider. An
|
|
abort BEFORE the provider call SHALL throw `SmsAbortedError`. An
|
|
abort that lands inside a retry delay SHALL throw `SmsAbortedError`
|
|
without invoking the next attempt.
|
|
|
|
#### Scenario: pre-aborted signal halts send immediately
|
|
|
|
- **WHEN** `service.send(msg, { signal: AbortSignal.abort() })` is
|
|
called
|
|
- **THEN** the call throws `SmsAbortedError` (code `SMS.ABORTED`)
|
|
and the provider's `send` is not invoked
|
|
|
|
**Verified by:** `src/service/sms-service.test.ts::"pre-aborted signal halts send"` AND `src/retry/retry.test.ts::"abort halts retries"`
|
|
|
|
---
|
|
|
|
### Requirement: Hono problem+json helper
|
|
|
|
`respondProblemJson(c, err)` SHALL serialise any `BaseError` /
|
|
`HttpError` / `SuaveplanError` / unknown throwable into an RFC 7807
|
|
`application/problem+json` response on the Hono `Context`-like
|
|
surface. The helper SHALL preserve the `httpStatus` registered by
|
|
`SMS_ERROR_METADATA` when the error's code is registered in the
|
|
shared `ErrorCodes` singleton, and SHALL fall back to `500` for
|
|
unknown errors.
|
|
|
|
#### Scenario: registered SMS code preserves its httpStatus
|
|
|
|
- **WHEN** `respondProblemJson(c, new SmsError({code: "SMS_RATE_LIMITED", message: "x"}))` is called
|
|
- **THEN** the response body's `status` field is `429`
|
|
|
|
**Verified by:** `src/routes/problem-json.test.ts::"registered code preserves httpStatus"` AND `src/routes/problem-json.test.ts::"unknown error falls back to 500"`
|
|
|
|
---
|
|
|
|
### Requirement: Subpath exports per feature
|
|
|
|
The `package.json` `exports` map SHALL expose a tree-shakeable
|
|
subpath for every feature module: `./error-codes`,
|
|
`./legacy-errors`, `./legacy-metadata`, `./schemas`,
|
|
`./validation/phone`, `./templates`, `./opt-out`,
|
|
`./rate-limiter`, `./retry`, `./scheduler`,
|
|
`./delivery-tracker`, `./in-memory-provider`, `./service`,
|
|
`./routes/problem-json`, `./otel`.
|
|
|
|
#### Scenario: feature subpaths resolve
|
|
|
|
- **WHEN** the package is fully built
|
|
- **THEN** `Object.keys(pkg.exports).filter(k => k.startsWith("./")).length >= 15`
|
|
|
|
**Verified by:** `src/service/sms-service.test.ts::"feature subpaths are declared in package.json"`
|
|
|
|
---
|
|
|
|
### Requirement: Universal-tier purity
|
|
|
|
The package SHALL not import any Node-only or Bun-only API
|
|
(`node:*`, `bun:*`). It SHALL rely only on `globalThis.setTimeout`
|
|
/ `clearTimeout` (universally available) via an injectable
|
|
`Timers` seam.
|
|
|
|
#### Scenario: no node: / bun: imports in src/
|
|
|
|
- **WHEN** the repository is grepped for `from ['\"]node:|from ['\"]bun:`
|
|
under `packages/communication/messaging/sms/src/`
|
|
- **THEN** the grep yields zero matches
|
|
|
|
**Verified by:** `src/service/sms-service.test.ts::"no node: or bun: imports leak into src/"`
|
|
|
|
---
|