# Tasks: enterprise-sms-providers

- [ ] 1.1 Scaffold package at `packages/communication/messaging/sms-providers/` with `package.json` v0.1.0, vite + dts build, `vitest.config.ts`, `tsconfig.json` + `tsconfig.lib.json`, `tests/setup/polyfills.ts`.
- [ ] 1.2 Add `dependencies`: `@suaveplan/error`, `@suaveplan/sms`, `@suaveplan/opentelemetry`, `tslib`, `zod`; `devDependencies`: testing infrastructure + node types.
- [ ] 2.1 `src/error-codes/error-codes.ts` — `SMS_PROVIDERS_CODES` via `defineCodes("SMS_PROVIDERS", [8 codes])`, `SmsProvidersError` discriminated class, six factory helpers, eager metadata.
- [ ] 2.2 `src/error-codes/error-codes.md` — six required sections.
- [ ] 2.3 `src/error-codes/error-codes.test.ts` — every factory covered (verified by tests).
- [ ] 3.1 `src/types/types.ts` — `FetchLike`, `HttpOptions`, `ProviderResponse`, per-provider config interfaces (`TwilioConfig`, `VonageConfig`, `MessageBirdConfig`, `PlivoConfig`, `AwsSnsConfig`), `InboundSmsEvent` discriminated union, `WebhookVerifyOptions`.
- [ ] 3.2 `src/types/types.md` — six required sections.
- [ ] 4.1 `src/http/http.ts` — `composeAbortSignal` + `httpRequest<T>` over `FetchLike` with timeout + typed-error translation.
- [ ] 4.2 `src/http/http.md` — six required sections.
- [ ] 4.3 `src/http/http.test.ts` — happy path, JSON body, form body, timeout, non-2xx → `HTTP_ERROR`, parse failure → `PARSE_ERROR`, abort propagation, header forwarding (verified by tests).
- [ ] 5.1 `src/registry/registry.ts` — `ProviderRegistry` (register/get/has/unregister/list/size) throwing typed errors on duplicate/missing.
- [ ] 5.2 `src/registry/registry.md`.
- [ ] 5.3 `src/registry/registry.test.ts` (verified by tests).
- [ ] 6.1 `src/otel/otel.ts` — meter + 5 instruments + `recordSend`, `recordWebhook`, `recordSignatureFailure`, `recordSendDuration`, `recordWebhookVerifyDuration` helpers.
- [ ] 6.2 `src/otel/otel.md`.
- [ ] 6.3 `src/otel/otel.test.ts` — verifies every helper records on the corresponding instrument (verified by tests).
- [ ] 7.1 `src/keywords/keywords.ts` — STOP/UNSTOP/HELP/START keyword detector + canonical `OptOutAction` enum.
- [ ] 7.2 `src/keywords/keywords.md`.
- [ ] 7.3 `src/keywords/keywords.test.ts` (verified by tests).
- [ ] 8.1 `src/twilio/twilio.ts` — `TwilioProvider implements SmsProvider`: HTTP Basic auth, form-encoded POST, MMS `MediaUrl[]`, `mapStatus`, status polling, `verifyWebhookSignature(rawBody, url, headers)` (HMAC-SHA1 via injectable `HmacSign`), `parseInbound(body)` → `InboundSmsEvent`.
- [ ] 8.2 `src/twilio/twilio.md`.
- [ ] 8.3 `src/twilio/twilio.test.ts` — `node:http` round-trip on random port (send), status fetch round-trip, MMS, status mapping, signature accept + reject, inbound parse (verified by tests).
- [ ] 9.1 `src/vonage/vonage.ts` — `VonageProvider` (api_key/api_secret body params, alpha/short/long sender parsing, HMAC-SHA256 webhook verifier).
- [ ] 9.2 `src/vonage/vonage.md`.
- [ ] 9.3 `src/vonage/vonage.test.ts` — round-trip + status + signature accept/reject + inbound (verified by tests).
- [ ] 10.1 `src/messagebird/messagebird.ts` — `MessageBirdProvider` (`AccessKey` header, JWT HS256 webhook verify with timestamp freshness window).
- [ ] 10.2 `src/messagebird/messagebird.md`.
- [ ] 10.3 `src/messagebird/messagebird.test.ts` (verified by tests).
- [ ] 11.1 `src/plivo/plivo.ts` — `PlivoProvider` (Basic auth, JSON body, X-Plivo-Signature-V3 canonical-string HMAC-SHA256 verify).
- [ ] 11.2 `src/plivo/plivo.md`.
- [ ] 11.3 `src/plivo/plivo.test.ts` (verified by tests).
- [ ] 12.1 `src/aws-sns/aws-sns.ts` — `AwsSnsProvider`: AWS SigV4 signer (computed inline), `Action=Publish` form body, `SMSType`/sender attributes; SNS-notification verifier with injectable PEM-cert resolver.
- [ ] 12.2 `src/aws-sns/aws-sns.md`.
- [ ] 12.3 `src/aws-sns/aws-sns.test.ts` (verified by tests).
- [ ] 13.1 `src/index.ts` — explicit named re-exports of all public symbols.
- [ ] 13.2 `README.md` describing public surface, dependency rationale, quick-start examples for each provider.
- [ ] 14.1 Pre-publish gate: `bunx turbo lint typecheck test build --filter=@suaveplan/sms-providers` green.
- [ ] 14.2 Coverage gate: `bunx turbo test:coverage --filter=@suaveplan/sms-providers` ≥ 100/100/100/100.
- [ ] 15.1 Refresh MANIFEST via `bun scripts/folder-reorg/generate-manifest.ts`.
- [ ] 15.2 Fold spec delta into `openspec/specs/sms-providers/spec.md` and archive change to `openspec/archive/2026-05-25-enterprise-sms-providers/`.
- [ ] 15.3 Flip STATUS.md row `–` → `✅`.
- [ ] 16.1 Commit on `feat/migrate-sms-providers` with Conventional message + Claude co-author.