@doeza/sms-service 1.0.0

package/AGENTS.md

@@ -0,0 +1,1616 @@
+# @doeza/sms-service — AI Agent Development and Integration Guide
+
+This document is the authoritative implementation guide for LLM-based coding agents, autonomous software agents, AI pair programmers, and human developers using or modifying `@doeza/sms-service`.
+
+It is intentionally stricter than the package README. The README explains how to use the package. This document defines how an implementation agent must reason about the package, what it may change, what it must preserve, and which production-safety rules are non-negotiable.
+
+The package source and tests remain the ultimate source of truth. When this document and executable behavior differ, inspect the current source and tests before making any change. Do not silently reinterpret existing behavior.
+
+---
+
+## 1. Agent operating mandate
+
+When integrating or modifying this package, act as a senior backend/platform engineer responsible for correctness, security, delivery semantics, observability, and operational safety.
+
+Your priorities, in order, are:
+
+1. Prevent duplicate SMS sends.
+2. Protect credentials, message content, recipient data, and provider URLs.
+3. Preserve explicit delivery-state semantics.
+4. Fail closed on malformed or ambiguous provider responses.
+5. Keep provider-specific behavior inside the SMS package or a thin application adapter.
+6. Keep authentication, authorization, persistence, rate limiting, product policy, and business rules in the host application.
+7. Preserve the package's zero-runtime-dependency, server-only design unless a deliberate package-level architectural change is explicitly requested.
+8. Prefer small, auditable changes over framework-specific abstractions.
+9. Never claim delivery when the provider only confirmed acceptance.
+10. Never add automatic retries to the send path without an explicit, externally verified idempotency design.
+
+Do not optimize for convenience at the expense of these rules.
+
+---
+
+## 2. Mandatory preflight for every agent task
+
+Before changing code that uses or modifies this package, inspect at least:
+
+- `packages/sms-service/package.json`
+- `packages/sms-service/index.js`
+- `packages/sms-service/index.d.ts`
+- `packages/sms-service/http.js` when using Web `Request` / `Response` handlers
+- `packages/sms-service/http.d.ts` when using the HTTP entry point
+- `packages/sms-service/test/service.test.js`
+- `packages/sms-service/README.md`
+
+If integrating in this repository, also inspect:
+
+- `lib/sms.ts`
+- the relevant `app/api/**/route.ts` files
+- the host application's authentication, authorization, rate-limiting, and persistence layers
+
+Do not assume the public API from memory. Do not invent methods, options, callback fields, or error codes.
+
+Before coding, determine which of these tasks you are performing:
+
+- direct server-side send integration
+- HTTP send endpoint integration
+- delivery-status callback integration
+- incoming-reply callback integration
+- package modification
+- provider migration
+- test-only integration
+
+Use the smallest public surface needed for the task.
+
+---
+
+## 3. Package contract at a glance
+
+Package name:
+
+```txt
+@doeza/sms-service
+```
+
+Runtime characteristics:
+
+- Node.js 22+
+- ESM
+- no runtime dependencies
+- no build step
+- no environment loader
+- no database
+- no framework dependency
+- no implicit logging
+- no automatic retries
+- explicit credential injection
+- Fetch API transport
+- TypeScript declarations included
+
+Public entry points:
+
+```js
+import {
+  createSmsService,
+  SmsError,
+  normalizeRecipients,
+  parseStatusCallback,
+  parseReplyCallback,
+} from "@doeza/sms-service";
+```
+
+Optional HTTP adapter:
+
+```js
+import {
+  createSendSmsHandler,
+  createStatusCallbackHandler,
+  createReplyCallbackHandler,
+} from "@doeza/sms-service/http";
+```
+
+Do not import implementation files such as `index.js` or `http.js` through deep package-relative paths from a consuming application. Use the documented package exports.
+
+---
+
+## 4. Core architectural boundary
+
+The package owns:
+
+- recipient normalization
+- send-input validation
+- Clickatell request construction
+- provider transport
+- timeout handling
+- cancellation handling
+- provider response validation
+- typed result normalization
+- SMS-specific error normalization
+- callback payload parsing
+- framework-neutral Web `Request` / `Response` adapters
+
+The host application owns:
+
+- environment-variable loading
+- secret storage
+- authentication
+- authorization
+- permissions
+- rate limits
+- abuse prevention
+- CAPTCHA / bot protection when applicable
+- persistence
+- message templates
+- consent and communication policy
+- recipient ownership checks
+- business rules
+- scheduling
+- queues
+- auditing
+- application logging
+- metrics and tracing
+- webhook ingress protection
+- callback deduplication
+- callback ordering policy
+- provider-status reconciliation
+- user-facing error text
+
+Do not move host-application responsibilities into the package merely because it is convenient for one application.
+
+Do not make the package read `process.env` directly. Pass configuration explicitly.
+
+---
+
+## 5. Required service construction pattern
+
+Create one service instance per credential/configuration set and reuse it.
+
+Preferred host adapter:
+
+```ts
+import {
+  createSmsService,
+  type SmsService,
+} from "@doeza/sms-service";
+
+let smsService: SmsService | undefined;
+
+export function getSmsService(): SmsService {
+  if (smsService) return smsService;
+
+  smsService = createSmsService({
+    apiKey: process.env.CLICKATELL_API_KEY ?? "",
+    timeoutMs: 10_000,
+  });
+
+  return smsService;
+}
+```
+
+Why:
+
+- configuration stays in the host application
+- package initialization is centralized
+- credentials are not duplicated across routes
+- tests can replace the adapter
+- lazy construction prevents missing runtime secrets from unnecessarily breaking build-time evaluation in frameworks such as Next.js
+
+Do not create a new instance for every recipient unless a specific credential/configuration boundary requires it.
+
+Do not construct the service in browser code.
+
+---
+
+## 6. Server-only rule
+
+`@doeza/sms-service` is server-side infrastructure.
+
+Never:
+
+- import it into a React client component
+- expose `CLICKATELL_API_KEY` through `NEXT_PUBLIC_*`
+- pass the API key to a browser
+- send directly from browser JavaScript to Clickatell
+- place provider credentials in serialized page props
+- store the API key in localStorage, sessionStorage, IndexedDB, cookies, HTML, or client bundles
+
+A browser action must call an authenticated and authorized server endpoint controlled by the host application.
+
+For Next.js App Router, make the Node runtime explicit when appropriate:
+
+```ts
+export const runtime = "nodejs";
+```
+
+---
+
+## 7. Recipient handling rules
+
+The package accepts:
+
+```ts
+string | readonly string[]
+```
+
+A string may be comma-separated.
+
+Accepted number format after normalization:
+
+- optional surrounding whitespace
+- optional leading `+`
+- 5–15 digits total after removing the leading `+`
+- first digit must be non-zero
+- country code must already be present
+
+The package intentionally does not guess country codes.
+
+Correct:
+
+```txt
++46701234567
+46701234567
+```
+
+Incorrect:
+
+```txt
+0701234567
+```
+
+Do not silently prepend `46`, `1`, `44`, or any other country code in a generic integration layer.
+
+If the product accepts local-format numbers, normalize them in a country-aware host-domain layer before calling this package. That layer must have explicit locale/country context and tests.
+
+The package deduplicates identical normalized recipients. Do not assume duplicate inputs produce duplicate sends.
+
+---
+
+## 8. Message-content rules
+
+`content` must be a non-empty string after trimming for validation.
+
+The package sends the original content string. Do not assume it trims, rewrites, transliterates, shortens, or sanitizes the message.
+
+The host application must own:
+
+- template rendering
+- localization
+- length policy
+- segmentation/cost policy
+- prohibited-content policy
+- personalization escaping
+- opt-out wording
+- consent requirements
+
+Do not add HTML escaping and assume it is SMS sanitization. SMS is plain text; product-specific template safety must be handled where templates are created.
+
+Do not log full message bodies by default.
+
+---
+
+## 9. `clientMessageId` semantics
+
+`clientMessageId` is a correlation identifier.
+
+It is not an idempotency guarantee.
+
+If omitted, the package generates a UUID.
+
+Use an application-provided `clientMessageId` when you need stable correlation across:
+
+- your database record
+- the initial send request
+- logs
+- provider callbacks
+- operational reconciliation
+
+Example:
+
+```ts
+const result = await sms.send({
+  to: recipient,
+  content,
+  clientMessageId: notification.id,
+});
+```
+
+Do not interpret reusing the same `clientMessageId` as proof that the provider will suppress duplicate sends.
+
+Never implement retry safety solely by reusing `clientMessageId`.
+
+---
+
+## 10. The most important rule: do not automatically retry sends
+
+The package intentionally performs one provider request and does not retry automatically.
+
+This is a correctness feature.
+
+A timeout, socket failure, connection reset, response-body failure, cancellation, malformed provider response, or intermediary failure can occur after the provider has already accepted the SMS.
+
+Therefore:
+
+```txt
+request failed locally != provider definitely did not accept the message
+```
+
+Never add generic retry middleware around `sms.send()`.
+
+Never configure a job runner, queue, HTTP client, serverless platform, or orchestration system to blindly rerun failed SMS sends.
+
+Never use patterns such as:
+
+```ts
+await retry(() => sms.send(input), { retries: 3 });
+```
+
+Do not retry `NETWORK`, `TIMEOUT`, `ABORTED`, or `INVALID_RESPONSE` merely because they look transient.
+
+Before any resend after an ambiguous failure:
+
+1. persist or recover the correlation identifier
+2. query/reconcile provider state when possible
+3. determine whether the provider accepted the prior request
+4. resend only if policy explicitly says it is safe
+5. create a new application audit event for the resend decision
+
+If the provider gains a documented, verified idempotency facility in the future, design and test idempotency before introducing retries.
+
+---
+
+## 11. Distinguish acceptance from delivery
+
+`SmsResult.success === true` means every requested recipient was accepted by Clickatell's send endpoint.
+
+It does not mean:
+
+- delivered to handset
+- displayed to recipient
+- read by recipient
+- permanently successful
+
+Delivery must be derived from later delivery-status callbacks or provider reconciliation.
+
+UI copy, database field names, and logs must reflect this distinction.
+
+Prefer terms such as:
+
+- `accepted`
+- `providerAcceptedAt`
+- `deliveryStatus`
+- `deliveredAt`
+
+Avoid setting a final status named `sent` if that status is later interpreted as delivered.
+
+If legacy schema uses `sent`, document its exact meaning.
+
+---
+
+## 12. Batch-send result handling
+
+A provider request can contain multiple recipients.
+
+Always inspect `result.messages`.
+
+Result shape:
+
+```ts
+interface SmsResult {
+  success: boolean;
+  partial: boolean;
+  clientMessageId: string;
+  to: string[];
+  responseCode?: number;
+  messages: Array<{
+    to: string;
+    accepted: boolean;
+    apiMessageId?: string;
+    errorCode?: string | number;
+  }>;
+}
+```
+
+Semantics:
+
+- `success: true` => all recipients accepted
+- `partial: true` => some accepted and some rejected
+- `success: false, partial: false` => none accepted
+
+Never retry the entire recipient batch after partial acceptance.
+
+If product policy permits retries, isolate only recipients known to have been rejected and make the retry decision explicitly.
+
+Persist per-recipient provider IDs and error codes when delivery tracking or reconciliation matters.
+
+---
+
+## 13. Error model
+
+All expected SMS-package failures are normalized to `SmsError`.
+
+Codes:
+
+```txt
+CONFIGURATION
+VALIDATION
+PROVIDER
+INVALID_RESPONSE
+NETWORK
+TIMEOUT
+ABORTED
+```
+
+Use typed branching:
+
+```ts
+import { SmsError } from "@doeza/sms-service";
+
+try {
+  return await sms.send(input);
+} catch (error) {
+  if (!(error instanceof SmsError)) throw error;
+
+  switch (error.code) {
+    case "VALIDATION":
+      // Caller/input problem.
+      break;
+    case "CONFIGURATION":
+      // Deployment/configuration problem.
+      break;
+    case "PROVIDER":
+    case "INVALID_RESPONSE":
+    case "NETWORK":
+    case "TIMEOUT":
+    case "ABORTED":
+      // Operational failure. Do not blindly resend.
+      break;
+  }
+}
+```
+
+Do not parse error message strings to determine behavior.
+
+Do not expose internal stack traces to end users.
+
+Do not replace `SmsError` with an untyped generic application error before recording the error code and correlation identifier needed for operations.
+
+---
+
+## 14. Secret-redaction rules
+
+The Clickatell HTTP endpoint used by this package sends credentials and message data as URL query parameters.
+
+Therefore, the full outbound URL is secret-bearing.
+
+Never log:
+
+- `url.href` from the provider request
+- raw fetch request URLs
+- raw native fetch exceptions that may contain the URL
+- Clickatell API keys
+- complete query strings
+- full provider response bodies unless separately reviewed and redacted
+- message content by default
+
+This applies to:
+
+- application logs
+- reverse proxies
+- APM tools
+- OpenTelemetry attributes
+- tracing spans
+- Sentry breadcrumbs
+- HTTP instrumentation
+- test snapshots
+- debug output
+- CI logs
+
+When instrumenting `fetch`, explicitly redact the URL.
+
+Prefer metadata such as:
+
+```ts
+{
+  operation: "sms.send",
+  provider: "clickatell",
+  clientMessageId,
+  recipientCount,
+  outcome,
+  errorCode,
+  durationMs,
+}
+```
+
+If recipient-level observability is required, prefer an internal recipient/customer identifier or a deliberately masked/hardened representation rather than full phone numbers.
+
+---
+
+## 15. Logging and observability policy
+
+The package intentionally does not log.
+
+The host application should add structured observability at the boundary around `sms.send()`.
+
+Recommended events:
+
+- `sms_send_attempted`
+- `sms_send_accepted`
+- `sms_send_partially_accepted`
+- `sms_send_rejected`
+- `sms_send_failed`
+- `sms_delivery_status_received`
+- `sms_reply_received`
+
+Recommended dimensions:
+
+- `clientMessageId`
+- application notification/message ID
+- provider
+- recipient count
+- result category
+- `SmsError.code`
+- HTTP status if safely available
+- latency
+
+Avoid high-cardinality dimensions unless your telemetry system is designed for them.
+
+Never attach API keys or full message bodies to traces.
+
+---
+
+## 16. Timeout policy
+
+Default package timeout is 10 seconds unless overridden.
+
+`timeoutMs` must be a positive integer.
+
+The timeout covers both:
+
+- obtaining the HTTP response
+- reading the response body
+
+Do not assume a timeout proves non-delivery.
+
+Choose a host-specific timeout based on the containing request/job budget, but preserve enough time for the package to cleanly classify its own timeout.
+
+Avoid stacking multiple timeout layers with nearly identical deadlines because the outer layer can obscure the SMS-specific error type.
+
+When cancellation from the caller is meaningful, pass an `AbortSignal`:
+
+```ts
+await sms.send(input, { signal });
+```
+
+Cancellation is also an ambiguous send outcome if the provider request may already have left the process.
+
+---
+
+## 17. Callback URL configuration
+
+Optional service options:
+
+```ts
+statusCallbackUrl?: string;
+replyCallbackUrl?: string;
+```
+
+They must be absolute `http:` or `https:` URLs without embedded credentials or URL fragments.
+
+Prefer building callback URLs from an explicit trusted application origin:
+
+```ts
+const appUrl = process.env.APP_URL;
+const statusCallbackUrl = new URL("/api/callbacks/sms-status", appUrl).href;
+```
+
+Do not derive externally visible callback destinations from an untrusted `Host`, `X-Forwarded-Host`, or request-origin header unless the deployment has a carefully configured trusted-proxy model.
+
+Do not assume supplying callback URLs in the send request automatically completes all provider-side callback or two-way messaging configuration.
+
+---
+
+## 18. Callback authentication and ingress protection
+
+`parseStatusCallback` and `parseReplyCallback` validate shape. They do not authenticate the sender.
+
+The callback HTTP handlers also do not add authentication unless `authorize` is supplied.
+
+This distinction is mandatory:
+
+```txt
+valid payload shape != authentic provider callback
+```
+
+Before production exposure, determine how the deployment verifies callback authenticity. Depending on provider capabilities and infrastructure this may include:
+
+- provider-supported signatures
+- a secret callback token
+- authenticated ingress
+- provider IP allowlisting as a defense-in-depth control
+- private networking or gateway verification
+
+Do not invent a signature scheme that Clickatell does not document.
+
+Do not claim callbacks are secure merely because the payload parses.
+
+Use `authorize(request)` when the verification can be expressed at the handler boundary:
+
+```ts
+const handler = createStatusCallbackHandler(saveStatus, {
+  authorize: verifySmsWebhookRequest,
+});
+```
+
+For more complex verification, place a trusted ingress wrapper in front of the package handler/parser.
+
+---
+
+## 19. Callback persistence rules
+
+Callback consumers may be called more than once and callbacks can arrive out of order.
+
+Persistence must therefore be idempotent and ordering-aware.
+
+For delivery status:
+
+- key records by provider message ID and/or stable application correlation data
+- store raw normalized status fields needed for auditing
+- preserve the latest accepted business state according to an explicit state-transition policy
+- do not assume arrival order equals lifecycle order
+- make duplicate processing safe
+
+For replies:
+
+- deduplicate by a stable provider reply/message identifier when available
+- avoid creating duplicate chat messages from repeated provider callbacks
+- retain enough linkage to associate the reply with the correct conversation/account
+
+The package handlers acknowledge success only after your consumer resolves successfully. Preserve that behavior.
+
+Do not return success before durable storage when provider retry behavior is required for reliability.
+
+---
+
+## 20. Status callback shape
+
+Required normalized fields:
+
+```ts
+{
+  messageId: string;
+  to: string;
+  statusCode: number;
+  status: string;
+  timestamp: string;
+}
+```
+
+Optional normalized fields include:
+
+```ts
+integrationName
+requestId
+clientMessageId
+from
+statusDescription
+```
+
+Numeric query/form values are normalized where applicable.
+
+Do not accept malformed callback values merely to keep an endpoint returning `200`.
+
+Failing closed allows invalid integrations to surface during testing and operations.
+
+---
+
+## 21. Reply callback shape
+
+Required normalized fields:
+
+```ts
+{
+  fromNumber: string;
+  toNumber: string;
+  timestamp: number;
+  text: string;
+}
+```
+
+Optional fields include:
+
+```ts
+integrationName
+replyMessageId
+messageId
+charset
+udh
+network
+keyword
+```
+
+Do not treat incoming text as trusted command input.
+
+If replies trigger business actions, run normal authentication-by-context, authorization, parsing, anti-abuse, and domain validation before acting.
+
+---
+
+## 22. HTTP adapter rules
+
+The `/http` entry point uses standard Web `Request` and `Response` types.
+
+`createSendSmsHandler`:
+
+- accepts POST only
+- reads JSON
+- can run `authorize(request)` before processing
+- returns structured SMS results
+- returns HTTP 200 for provider-level partial/all-recipient rejection represented as a valid result
+- maps validation errors to 400
+- maps configuration errors to 500
+- maps provider/invalid-response errors to 502
+- maps network/timeout errors to 504
+- maps cancellation to 408
+- adds `Cache-Control: no-store`
+
+Do not interpret every HTTP 200 as `result.success === true`.
+
+The response body is authoritative for recipient acceptance.
+
+`createStatusCallbackHandler` and `createReplyCallbackHandler`:
+
+- accept GET and POST
+- accept JSON
+- accept `application/x-www-form-urlencoded`
+- accept query parameters on GET
+- await the consumer before acknowledging success
+- support optional authorization
+
+Do not bypass host authentication/rate limiting when exposing the send handler publicly.
+
+---
+
+## 23. Next.js integration pattern
+
+Recommended App Router structure:
+
+```txt
+lib/
+  sms.ts
+app/
+  api/
+    send-sms/
+      route.ts
+    callbacks/
+      sms-status/
+        route.ts
+      sms-reply/
+        route.ts
+```
+
+Service adapter:
+
+```ts
+// lib/sms.ts
+import { createSmsService, type SmsService } from "@doeza/sms-service";
+
+let service: SmsService | undefined;
+
+export function getSmsService() {
+  if (service) return service;
+
+  service = createSmsService({
+    apiKey: process.env.CLICKATELL_API_KEY ?? "",
+    timeoutMs: Number(process.env.SMS_TIMEOUT_MS ?? 10_000),
+  });
+
+  return service;
+}
+```
+
+Route:
+
+```ts
+// app/api/send-sms/route.ts
+import { createSendSmsHandler } from "@doeza/sms-service/http";
+import { getSmsService } from "@/lib/sms";
+
+export const runtime = "nodejs";
+
+export const POST = createSendSmsHandler(getSmsService, {
+  authorize: async (request) => {
+    // Call the application's real authentication/authorization layer.
+    return false;
+  },
+});
+```
+
+The `authorize` example deliberately denies by default. Replace it with the host application's real authorization logic.
+
+Never ship a production send route with a placeholder `return true` authorization callback.
+
+---
+
+## 24. Express / Fastify / job-worker integration
+
+For server frameworks that do not use Web `Request` / `Response`, prefer calling the core service directly.
+
+Example service-layer function:
+
+```ts
+export async function sendBookingConfirmation(input: {
+  phoneNumber: string;
+  bookingId: string;
+}) {
+  const sms = getSmsService();
+  const content = renderBookingConfirmation(input.bookingId);
+
+  return sms.send({
+    to: input.phoneNumber,
+    content,
+    clientMessageId: `booking:${input.bookingId}`,
+  });
+}
+```
+
+Keep framework adaptation outside the package.
+
+Do not wrap the package in a second generic "SMS SDK" unless that layer provides real application-domain value such as templates, policy, persistence, or provider abstraction.
+
+Avoid abstraction layers that only rename methods and make failure semantics harder to see.
+
+---
+
+## 25. Authentication, authorization, and abuse prevention
+
+Sending SMS has direct financial and abuse impact.
+
+A production send endpoint should normally enforce:
+
+- authenticated caller identity
+- authorization for the specific operation
+- recipient ownership or business relationship
+- server-side recipient selection when possible
+- rate limits
+- per-account quotas
+- anti-automation/abuse controls where applicable
+- audit logging
+
+Do not let a normal end user submit arbitrary `to` and `content` values to a generic public relay unless the product explicitly requires that behavior and has strong abuse controls.
+
+Preferred product API:
+
+```json
+{
+  "bookingId": "..."
+}
+```
+
+Less safe generic API:
+
+```json
+{
+  "to": "+46701234567",
+  "content": "anything"
+}
+```
+
+When possible, resolve recipients and templates server-side from trusted application data.
+
+---
+
+## 26. Persistence and transaction boundaries
+
+Do not combine SMS transmission and database transactions in a way that causes database retries to resend SMS.
+
+Bad pattern:
+
+```ts
+await db.transaction(async (tx) => {
+  await tx.insert(...);
+  await sms.send(...);
+});
+```
+
+If the transaction callback is retried by the database/client, the SMS may be duplicated.
+
+Prefer an outbox/job model when durable workflow matters:
+
+1. transactionally store the domain change and an SMS intent/outbox record
+2. commit
+3. a worker claims the SMS intent exactly once according to application policy
+4. worker sends once
+5. worker records the provider result
+6. ambiguous failures enter reconciliation, not blind resend
+
+If an outbox is unnecessary, at minimum separate durable application writes from the network send so retry behavior is explicit.
+
+---
+
+## 27. Queue-worker rules
+
+Queues often retry failed jobs automatically. This is dangerous for SMS.
+
+If `sms.send()` is called inside a queue job:
+
+- do not use the queue's default retry policy without analysis
+- classify failures
+- prevent automatic resend after ambiguous transport failures
+- persist the attempt before or with a stable attempt identifier
+- route uncertain outcomes to reconciliation/manual policy
+- make job ownership/locking robust against concurrent workers
+
+A job-level crash after provider acceptance but before success persistence is also an ambiguous state.
+
+Design for that case explicitly.
+
+---
+
+## 28. Rate limiting
+
+The package does not implement rate limits.
+
+Apply rate limits at the host boundary based on product risk, for example:
+
+- caller/account
+- recipient
+- operation type
+- tenant
+- IP address as a secondary signal
+
+Do not rate-limit only by IP in authenticated multi-user systems.
+
+Do not rely on provider throttling as your abuse-control layer.
+
+Provider HTTP 429 is a provider failure, not permission to automatically resend the same SMS later without duplicate-safety analysis.
+
+---
+
+## 29. Configuration validation
+
+Allow package construction to validate SMS-specific configuration.
+
+Also validate deployment configuration at application startup or health-check time when operationally appropriate.
+
+Important variables may include:
+
+```txt
+CLICKATELL_API_KEY
+SMS_TIMEOUT_MS
+APP_URL
+ENABLE_SMS_CALLBACKS
+```
+
+Do not coerce invalid numeric values into apparently valid defaults without intention.
+
+Do not expose secret values in configuration-error messages.
+
+---
+
+## 30. Testing strategy
+
+Every integration should test behavior, not only the happy path.
+
+The package supports injected `fetch`:
+
+```ts
+const sms = createSmsService({
+  apiKey: "test-key",
+  fetch: mockFetch,
+});
+```
+
+Use this instead of real provider calls in automated tests.
+
+Required test categories for changes affecting sends:
+
+1. successful acceptance
+2. partial acceptance
+3. all-recipient rejection
+4. input validation
+5. provider HTTP error
+6. body-level provider error
+7. malformed JSON
+8. malformed provider response shape
+9. timeout
+10. cancellation
+11. native network failure
+12. secret redaction
+13. no implicit retry
+14. duplicate recipient normalization
+15. Unicode/special-character content encoding
+
+Required callback test categories:
+
+1. valid callback
+2. malformed required field
+3. numeric query/form normalization
+4. duplicate callback handling in the host persistence layer
+5. consumer failure does not acknowledge success
+6. authorization failure
+7. GET query payload when supported
+8. POST JSON
+9. POST form-encoded payload
+
+Never require real credentials or network access for unit tests.
+
+---
+
+## 31. Package-change requirements
+
+When modifying `packages/sms-service` itself, preserve the public contract unless the task explicitly authorizes a breaking change.
+
+For every public API modification:
+
+- update JavaScript implementation
+- update `.d.ts` declarations
+- update tests
+- update README
+- update this `AGENTS.md` if agent guidance changes
+- consider package versioning implications
+
+Do not add a dependency for functionality that can be implemented safely with Node/Web platform APIs unless there is a strong maintenance reason.
+
+Do not add framework imports to the core package.
+
+Do not add hidden environment-variable reads.
+
+Do not add global mutable state inside the package for application-specific concerns.
+
+Do not expose raw provider responses or native fetch errors simply to aid debugging; add safe normalized fields instead.
+
+---
+
+## 32. Provider-response validation principle
+
+Fail closed.
+
+The package deliberately verifies that provider responses correspond to the requested recipients and contain expected fields.
+
+Do not weaken response validation to "make an integration work" without first verifying the current Clickatell response contract.
+
+If the provider changes its response format:
+
+1. capture a sanitized example
+2. consult current provider documentation
+3. determine compatibility requirements
+4. update parser behavior deliberately
+5. add regression tests
+6. preserve secret redaction
+7. document the change
+
+Never mark an SMS accepted from an unrecognized or incomplete response structure.
+
+---
+
+## 33. Provider API changes
+
+The current transport targets:
+
+```txt
+https://platform.clickatell.com/messages/http/send
+```
+
+It uses a GET request with URL-encoded parameters and refuses redirects.
+
+Do not migrate to another Clickatell API, SDK, HTTP method, or endpoint as an incidental refactor.
+
+A provider-API migration affects:
+
+- authentication
+- secret exposure model
+- request encoding
+- response schema
+- retry/idempotency semantics
+- callback semantics
+- errors
+- rate limits
+- delivery receipts
+- tests
+- documentation
+
+Treat it as an explicit migration project.
+
+---
+
+## 34. Do not accidentally leak data through instrumentation
+
+Many HTTP/APM libraries automatically capture request URLs.
+
+Because this provider uses query parameters for secrets and message content, review instrumentation around custom/injected `fetch` implementations.
+
+If adding tracing, either:
+
+- disable URL capture for this operation, or
+- replace the URL attribute with a safe origin/path-only representation
+
+Safe example:
+
+```txt
+https://platform.clickatell.com/messages/http/send
+```
+
+Unsafe example:
+
+```txt
+https://platform.clickatell.com/messages/http/send?apiKey=...&to=...&content=...
+```
+
+Do not attach `URLSearchParams` objects to telemetry.
+
+---
+
+## 35. Data minimization
+
+Phone numbers and message bodies may contain personal or sensitive information.
+
+Default engineering policy:
+
+- process only what is required
+- avoid duplicating message bodies into logs
+- retain provider IDs and correlation IDs when they are sufficient
+- mask phone numbers in operational logs where practical
+- follow the host application's retention policy
+- do not place SMS bodies in error text
+
+Do not make broad claims about regulatory compliance solely because these engineering practices are followed. Compliance depends on jurisdiction and product context.
+
+---
+
+## 36. Safe user-facing status mapping
+
+Application UI should not directly display low-level provider/network errors.
+
+Example policy:
+
+```ts
+function toUserMessage(error: unknown) {
+  if (!(error instanceof SmsError)) {
+    return "We could not send the message right now.";
+  }
+
+  if (error.code === "VALIDATION") {
+    return "The phone number or message is invalid.";
+  }
+
+  return "We could not confirm the SMS send. Please check the message status before trying again.";
+}
+```
+
+The final text is product-specific, but it must not encourage automatic/manual duplicate sends after ambiguous outcomes without checking status.
+
+---
+
+## 37. Code-review invariants
+
+Reject a change if it introduces any of the following without an explicit and verified design:
+
+- automatic retries around `sms.send()`
+- provider URLs in logs
+- API keys in client code
+- browser-side provider calls
+- direct `process.env` reads inside the package
+- local phone-number guessing in the generic package
+- callbacks without any production ingress-authentication plan
+- success being equated with handset delivery
+- whole-batch retry after partial acceptance
+- swallowed callback persistence failures
+- untyped string matching on error messages
+- raw provider-body exposure
+- native fetch error exposure
+- framework dependency in the core package
+- database dependency in the package
+- queue retry policies that can duplicate sends
+- database transaction callbacks that may resend SMS on transaction retry
+- tests that require real provider credentials
+
+---
+
+## 38. Agent anti-patterns
+
+### Anti-pattern: "Improve reliability with exponential backoff"
+
+Do not add automatic resend logic to ambiguous failures.
+
+### Anti-pattern: "Store API key in a public env var so the frontend can send"
+
+Never expose the provider key to the client.
+
+### Anti-pattern: "Normalize Swedish numbers by adding +46"
+
+Not in this generic package. Use an explicit country-aware application layer.
+
+### Anti-pattern: "The provider returned HTTP 200, so sending succeeded"
+
+Wrong. Inspect normalized `messages` and `success`.
+
+### Anti-pattern: "The API returned success, mark delivered"
+
+Wrong. Acceptance and delivery are separate states.
+
+### Anti-pattern: "Log the request URL to debug the provider"
+
+Wrong. The URL contains secrets and content.
+
+### Anti-pattern: "A callback parsed, so it came from Clickatell"
+
+Wrong. Parsing validates shape, not authenticity.
+
+### Anti-pattern: "Database write failed after send, rerun the function"
+
+Potential duplicate. Separate persistence/reconciliation from resend behavior.
+
+### Anti-pattern: "Queue failed, let BullMQ/SQS/etc. retry automatically"
+
+Potential duplicate. Define safe retry semantics first.
+
+---
+
+## 39. Recommended production domain model
+
+For systems that need reliable tracking, model an SMS as more than a boolean.
+
+Example states:
+
+```txt
+created
+send_attempt_started
+provider_accepted
+partially_accepted
+provider_rejected
+send_outcome_unknown
+delivery_pending
+delivered
+delivery_failed
+```
+
+This is an example, not a package API.
+
+The key principle is to preserve uncertainty rather than converting every exception into `failed` and every acceptance into `delivered`.
+
+A useful attempt record may contain:
+
+```ts
+{
+  id: string;
+  clientMessageId: string;
+  applicationMessageId: string;
+  provider: "clickatell";
+  startedAt: Date;
+  completedAt?: Date;
+  outcome: string;
+  errorCode?: string;
+}
+```
+
+Store recipient/provider-message details in child records when sending to multiple recipients.
+
+---
+
+## 40. Recommended implementation workflow for AI agents
+
+When asked to implement SMS in a new project, follow this sequence.
+
+### Phase 1 — inspect
+
+- identify runtime/framework
+- identify authentication layer
+- identify persistence layer
+- identify queue/retry behavior
+- identify where secrets live
+- identify how phone numbers are normalized
+- identify whether status/reply callbacks are needed
+
+### Phase 2 — integrate core service
+
+- install `@doeza/sms-service`
+- add a server-only service adapter
+- pass credentials explicitly
+- reuse one instance per credential set
+- choose a timeout
+
+### Phase 3 — add product boundary
+
+- enforce auth/authz
+- resolve recipient server-side when possible
+- render approved templates server-side
+- apply rate limits/quotas
+- assign stable correlation IDs
+
+### Phase 4 — persistence
+
+- persist send intent when required
+- preserve per-recipient acceptance
+- model uncertain outcomes
+- avoid transaction/queue retry duplication
+
+### Phase 5 — callbacks
+
+- configure trusted callback URLs
+- implement ingress verification
+- use idempotent persistence
+- handle out-of-order status events
+
+### Phase 6 — observability
+
+- add structured safe metadata
+- redact URLs, keys, bodies, and sensitive recipient data
+- add operational metrics
+
+### Phase 7 — tests
+
+- test happy path
+- test partial result
+- test malformed provider response
+- test network/timeout ambiguity
+- assert no automatic retry
+- test callback duplicates and persistence failures
+
+### Phase 8 — review
+
+Run the checklist in this document before completion.
+
+---
+
+## 41. Master prompt for an implementation agent
+
+Copy this prompt when assigning an AI agent to integrate the package into another project.
+
+```text
+You are the senior backend engineer responsible for integrating @doeza/sms-service into this application.
+
+Treat SMS sending as a side effect with financial cost and ambiguous network-failure semantics.
+
+Before changing code, inspect the application's runtime, authentication, authorization, persistence, queue/retry configuration, phone-number model, logging/APM setup, and existing notification architecture. Inspect the installed @doeza/sms-service README, type declarations, implementation, and tests. Do not invent package APIs.
+
+Non-negotiable rules:
+1. Keep the package server-only. Never expose provider credentials to client code.
+2. Pass the Clickatell API key explicitly from the host application's secret/config layer. Do not modify the package to read environment variables.
+3. Reuse one service instance per credential/configuration set.
+4. Do not automatically retry sms.send() after timeout, network error, cancellation, malformed response, or other ambiguous transport failure. The provider may already have accepted the SMS.
+5. clientMessageId is correlation data, not an idempotency guarantee.
+6. Treat result.success as provider acceptance, not handset delivery.
+7. Inspect per-recipient result.messages and preserve partial acceptance. Never resend an entire partially accepted batch.
+8. Never log full Clickatell request URLs, query strings, API keys, raw native fetch errors, or message bodies. The provider request URL contains sensitive query parameters.
+9. Do not guess country codes. Supply international-format numbers to the package from a country-aware application layer.
+10. Authentication, authorization, rate limiting, quotas, consent/business rules, templates, persistence, and audit logging belong to the host application.
+11. Callback parsers validate payload shape; they do not authenticate webhook origin. Add a real ingress-verification strategy before production exposure.
+12. Make callback persistence idempotent and able to tolerate duplicate/out-of-order callbacks.
+13. Await durable callback processing before acknowledging success when provider retries are needed.
+14. If a database transaction or queue can retry application code, ensure it cannot duplicate an SMS send.
+15. Use SmsError.code for control flow. Do not parse error strings.
+16. Use injected fetch/mocks for tests; automated tests must not require real provider credentials or network access.
+17. Preserve the package's Node 22+, ESM, zero-runtime-dependency design unless explicitly asked to redesign the package itself.
+
+Implementation expectations:
+- Create a thin server-side application adapter around createSmsService.
+- Use createSendSmsHandler only when standard Web Request/Response integration is appropriate; otherwise call sms.send() directly from the framework's server layer.
+- Add explicit auth/authz and rate limits around any send endpoint.
+- Prefer server-side recipient/template selection over accepting arbitrary public to/content values.
+- Add structured, redacted observability using correlation IDs and outcome categories.
+- Model acceptance, delivery, rejection, and unknown outcomes distinctly if persisted.
+- Implement callback storage with deduplication and ordering rules when delivery/reply tracking is required.
+- Cover success, partial acceptance, validation, provider rejection, malformed provider responses, timeout, network failure, cancellation, secret redaction, and no-retry behavior in tests.
+
+Before completing the task, review every changed file for credential exposure, accidental retries, incorrect delivery semantics, weak callback authentication, unsafe logging, and framework/client-boundary violations. Report any assumptions that could not be verified from the codebase.
+```
+
+---
+
+## 42. Master prompt for an agent modifying the package itself
+
+```text
+You are maintaining @doeza/sms-service, a standalone server-side Clickatell SMS package.
+
+Before editing, read package.json, index.js, index.d.ts, http.js, http.d.ts, README.md, AGENTS.md, and the complete test suite.
+
+Preserve these architectural invariants unless the task explicitly authorizes changing them:
+- Node.js 22+
+- ESM
+- zero runtime dependencies
+- no framework dependency
+- no database dependency
+- no environment loader
+- explicit configuration injection
+- server-side use only
+- normalized SmsError failures
+- no automatic send retries
+- provider acceptance kept distinct from delivery
+- strict provider-response validation
+- no raw provider/native-fetch error exposure
+- no logging inside the package
+- Web Request/Response HTTP adapter kept optional under the ./http export
+
+For every public behavior change, update implementation, TypeScript declarations, tests, README, and AGENTS.md where applicable.
+
+Security requirements:
+- never expose API keys or message content in errors
+- never expose native fetch errors containing credential-bearing URLs
+- preserve redirect refusal unless a verified provider change requires otherwise
+- preserve explicit callback URL validation
+- do not claim webhook authenticity from parser validation
+
+Reliability requirements:
+- do not introduce automatic retries unless the provider's current API supplies a documented idempotency mechanism and the change includes a complete idempotency design and regression tests
+- preserve per-recipient result handling and partial acceptance
+- fail closed on malformed/incomplete/mismatched provider responses
+- keep timeout and cancellation behavior explicit
+
+Testing requirements:
+- no real credentials
+- no required network access
+- use injected Fetch implementations
+- test all new branches
+- include secret-redaction regression tests for error paths
+- include no-retry assertions for ambiguous send failures
+
+Do not add abstraction or dependencies unless they materially improve maintainability and preserve the package's standalone nature.
+```
+
+---
+
+## 43. Review prompt for AI code reviewers
+
+```text
+Review this SMS integration as a production backend/security reviewer.
+
+Do not focus only on style. Find correctness and operational risks.
+
+Check specifically for:
+- browser/client exposure of @doeza/sms-service or CLICKATELL_API_KEY
+- provider URLs, API keys, message bodies, or raw fetch errors entering logs/traces
+- automatic retries around sms.send()
+- queue retries that can resend SMS
+- database transaction retries that can resend SMS
+- misuse of clientMessageId as idempotency
+- result.success incorrectly treated as handset delivery
+- partial recipient acceptance being ignored
+- entire-batch resend after partial acceptance
+- local-number country-code guessing in generic infrastructure
+- missing authentication/authorization on send routes
+- accepting arbitrary recipient/content from untrusted callers without product policy
+- missing rate limits/quotas
+- missing callback sender verification
+- non-idempotent callback persistence
+- callback consumers acknowledged before durable write
+- out-of-order delivery events overwriting newer state incorrectly
+- string matching on SmsError.message instead of SmsError.code
+- raw provider response exposure
+- weakened malformed-response validation
+- real network/provider calls in unit tests
+- package API/type declaration drift
+
+Classify findings by severity and explain the duplicate-send, credential-exposure, data-integrity, or delivery-state failure mode for each finding. Suggest the smallest safe correction.
+```
+
+---
+
+## 44. Migration prompt for existing SMS code
+
+```text
+Migrate the existing SMS implementation to @doeza/sms-service without changing product behavior unnecessarily.
+
+First inventory:
+- existing provider endpoint and parameters
+- credential source
+- number normalization
+- templates/content generation
+- retries/backoff
+- queue behavior
+- persistence schema
+- delivery callbacks
+- incoming replies
+- auth/authz
+- rate limits
+- logs/APM
+- user-facing statuses
+
+Then map each responsibility either to @doeza/sms-service or to the host application. Do not move product-specific concerns into the package.
+
+Pay special attention to legacy retry logic. Remove or redesign any automatic retry that could duplicate sends after ambiguous failures. Preserve existing correlation IDs where possible, but do not treat them as provider idempotency keys.
+
+Preserve per-recipient acceptance and distinguish provider acceptance from delivery.
+
+Add regression tests before deleting the old transport. Ensure no provider URL/API key/message content is logged by the new integration.
+
+Complete the migration with a clear list of behavior intentionally preserved, behavior intentionally changed, and unresolved provider assumptions.
+```
+
+---
+
+## 45. Incident-debugging prompt
+
+```text
+Investigate this SMS incident without causing duplicate sends.
+
+Do not resend anything as an investigative step.
+
+Collect and correlate only safe metadata:
+- application message/notification ID
+- clientMessageId
+- provider apiMessageId when available
+- timestamps
+- recipient-safe identifier/masked number
+- SmsError.code
+- HTTP status when available
+- delivery callback history
+- queue/job attempt history
+
+Do not log or paste API keys, full Clickatell request URLs, query strings, or message bodies.
+
+Determine whether the state is:
+- provider accepted
+- provider rejected
+- partially accepted
+- delivery pending
+- delivered
+- delivery failed
+- unknown/ambiguous
+
+For timeout/network/cancellation/malformed-response incidents, assume the send outcome may be unknown until provider state is reconciled. Do not infer non-acceptance from a local exception.
+
+Identify whether queue/database retry behavior could have produced duplicates. Provide remediation that prevents recurrence before recommending any resend policy.
+```
+
+---
+
+## 46. Completion checklist
+
+An AI agent must not mark an SMS integration complete until it can answer yes to all applicable items.
+
+### Architecture
+
+- Is the package used only on the server?
+- Is configuration injected explicitly?
+- Is the service instance reused appropriately?
+- Are host-specific concerns outside the package?
+
+### Security
+
+- Is the provider API key absent from client code?
+- Are full provider URLs/query strings excluded from logs and traces?
+- Are raw native fetch errors excluded from user/log output?
+- Are message bodies excluded from routine logs?
+- Is any send endpoint authenticated and authorized?
+- Are abuse/rate-limit controls present where required?
+- Is callback-origin verification handled or explicitly blocked from production until handled?
+
+### Correctness
+
+- Are phone numbers international before reaching the package?
+- Is no generic country-code guessing performed?
+- Is `clientMessageId` treated only as correlation?
+- Is acceptance distinguished from delivery?
+- Are per-recipient results processed?
+- Is partial acceptance handled without whole-batch resend?
+- Are malformed provider responses treated as failures?
+
+### Reliability
+
+- Are automatic send retries absent unless a verified idempotency design exists?
+- Are queue retries safe?
+- Are database transaction retries safe?
+- Are ambiguous failures represented as unknown/reconciliation states where persistence exists?
+- Are callback writes idempotent?
+- Are out-of-order callback events handled?
+
+### Testing
+
+- Are unit tests network-independent?
+- Is `fetch` mocked/injected?
+- Are success, partial, rejection, timeout, cancellation, network, malformed response, and validation paths covered?
+- Is no-retry behavior asserted?
+- Is secret redaction asserted?
+- Are callback duplicate/failure cases covered?
+
+### Documentation
+
+- Are new public APIs reflected in `.d.ts`?
+- Is README documentation current?
+- Is this agent guide still accurate?
+
+---
+
+## 47. Final agent rule
+
+When uncertain whether an operation is safe to repeat, treat it as non-repeatable until you have evidence otherwise.
+
+For SMS, duplicate prevention and secret protection are more important than hiding an operational failure with a retry.