@doeza/sms-service 1.0.0

package/README.md

@@ -0,0 +1,139 @@
+# @doeza/sms-service
+
+Standalone, server-side Clickatell SMS package. No Next.js, React, database, environment loader, runtime dependencies, or build step. Runs on Node.js 22+ and ships TypeScript declarations.
+
+> **AI coding agents and production integrations:** read [`AGENTS.md`](./AGENTS.md) before implementing or modifying this package. It defines strict rules for duplicate-send prevention, secret handling, retries, callbacks, persistence, observability, testing, and framework integration.
+
+## Install in another project
+
+From this repository:
+
+```sh
+pnpm pack:sms
+```
+
+This creates `packages/sms-service/doeza-sms-service-1.0.0.tgz`. In your other project:
+
+```sh
+npm install /absolute/path/to/doeza-sms-service-1.0.0.tgz
+```
+
+Alternatively copy the entire `packages/sms-service` directory into your project and install it with `npm install ./packages/sms-service`. No registry publication is required. Do not install the repository root as the SMS package.
+
+## Send an SMS
+
+```js
+import { createSmsService } from "@doeza/sms-service";
+
+const sms = createSmsService({
+  apiKey: process.env.CLICKATELL_API_KEY,
+  timeoutMs: 10000,
+});
+
+const result = await sms.send({
+  to: "+46701234567",
+  content: "Your booking is confirmed.",
+  clientMessageId: "booking-123",
+});
+
+for (const message of result.messages) {
+  console.log(message.to, message.accepted, message.apiMessageId);
+}
+```
+
+Configure a single service instance per credential set. Keep it in server code. Credentials are passed explicitly; the package does not read environment variables or log messages.
+
+`to` accepts a string, comma-separated string, or string array. International numbers must contain 5–15 digits including the country code; a leading `+` and surrounding whitespace are removed. Duplicates are removed. Local numbers are rejected rather than assigned a country code. Content is preserved exactly and must not be blank.
+
+`clientMessageId` defaults to a UUID. It correlates requests and callbacks; it is **not an idempotency guarantee**.
+
+## Results and errors
+
+`send()` returns `{ success, partial, clientMessageId, to, responseCode?, messages }`.
+Each message has `to`, `accepted`, and optional `apiMessageId` / `errorCode`.
+`success` means every recipient was accepted by Clickatell, not delivered to a handset.
+`partial` means some recipients were accepted. Rejected recipients remain in the result.
+
+Invalid input/configuration, HTTP failures, provider request errors, malformed responses, network errors, cancellation, and timeouts throw `SmsError`:
+
+```js
+import { SmsError } from "@doeza/sms-service";
+
+try {
+  const result = await sms.send({ to: ["46701234567"], content: "Hello" });
+  // Persist result here using your project's own database.
+  console.log(result.success, result.partial);
+} catch (error) {
+  if (!(error instanceof SmsError)) throw error;
+  console.error(error.code, error.httpStatus, error.clientMessageId);
+}
+```
+
+Error codes: `CONFIGURATION`, `VALIDATION`, `PROVIDER`, `INVALID_RESPONSE`, `NETWORK`, `TIMEOUT`, `ABORTED`.
+The service does not expose raw provider bodies or native fetch errors, which can contain credentials.
+The timeout covers fetching and reading the response. Pass `{ signal }` as the second argument to `send()` for cancellation.
+
+There are no automatic retries. A timeout, disconnect, or incomplete provider response can happen after acceptance. Check provider status before resending. Handle storage failures separately from sending so a database retry does not send the SMS again.
+
+The transport preserves this application's Clickatell Platform HTTP endpoint:
+`https://platform.clickatell.com/messages/http/send`.
+It sends one GET request with URL-encoded parameters and refuses redirects. Avoid logging outbound URLs because this API includes credentials and message content in query parameters.
+The response fields follow [Clickatell's HTTP SDK examples](https://github.com/clickatell/clickatell-python#http-api).
+
+## Next.js and other Web Request runtimes
+
+The optional `/http` entry point uses standard `Request` / `Response` objects.
+In a Next.js App Router route:
+
+```ts
+import { createSmsService } from "@doeza/sms-service";
+import { createSendSmsHandler } from "@doeza/sms-service/http";
+
+export const runtime = "nodejs";
+export const POST = createSendSmsHandler(() => createSmsService({
+  apiKey: process.env.CLICKATELL_API_KEY ?? "",
+}));
+```
+
+The lazy factory keeps missing runtime credentials from breaking the build.
+For server jobs or Express applications, call `sms.send()` directly inside your existing authenticated handler.
+
+The host application owns authentication and rate limiting. Each HTTP handler accepts an optional `authorize(request)` callback. Returning false gives HTTP 401 before processing; omitting it adds no access control. Use the callback to connect your existing session or API-key checks before exposing a send route.
+
+The send handler accepts POST JSON and returns the result plus a human-readable `message`. It retains the existing app's `success`, `message`, and `clientMessageId` contract. Partial and rejected recipient results use HTTP 200 with `success: false`; inspect `messages` rather than retrying the entire batch. Validation returns 400, configuration 500, provider failures 502, timeouts/network failures 504, and cancellation 408.
+
+## Delivery status and incoming replies
+
+The parsers and handlers accept the callback payloads already used by this app. They do not verify sender authenticity. Configure your Clickatell integration to match the payload format and callback URLs.
+
+```ts
+import { createStatusCallbackHandler } from "@doeza/sms-service/http";
+import { saveStatus } from "./your-database.js";
+
+const handler = createStatusCallbackHandler(saveStatus);
+export const GET = handler;
+export const POST = handler;
+```
+
+`createReplyCallbackHandler(onReply)` works the same way. Consumers can be async; responses are acknowledged only after the consumer succeeds. Throwing returns an error so a provider can retry. Make database writes idempotent because callbacks can be repeated or arrive out of order. Both handlers accept GET query parameters, POST JSON, and POST URL-encoded forms. Connect webhook verification through `authorize` or your existing ingress.
+
+For another framework, call `parseStatusCallback(payload)` or `parseReplyCallback(payload)` and persist their result yourself.
+
+Required status fields: `messageId`, `to`, integer `statusCode`, `status`, and string `timestamp`.
+Required reply fields: `fromNumber`, `toNumber`, integer `timestamp`, and `text`.
+Numeric query values are normalized; missing timestamps and malformed numbers are rejected.
+See the exported TypeScript types for optional fields.
+
+Optional `statusCallbackUrl` and `replyCallbackUrl` service options preserve this app's `callback` and `replyCallback` send parameters. Use absolute HTTP(S) URLs. They do not replace configuring callbacks and two-way messaging in your provider account.
+
+## Test and run the example
+
+```sh
+# No dependencies, credentials, or network required:
+node --test packages/sms-service/test/*.test.js
+
+# Sends a real message only when you provide a recipient and content:
+node --env-file=.env.local packages/sms-service/examples/send.mjs +46701234567 "Hello"
+```
+
+Inject `fetch` in `createSmsService({ apiKey, fetch })` to use a mock or an instrumented transport. It must implement Fetch semantics, including abort signals. The bundled example also works from the copied package directory.

package/examples/README.md

@@ -0,0 +1,4 @@
+# Examples
+
+- [`send.mjs`](./send.mjs) — minimal Node.js send example.
+- [`nextjs-supabase/`](./nextjs-supabase/) — Next.js App Router + Supabase reference integration with authenticated sending, idempotency, persistence, delivery callbacks, incoming replies, RLS, and a complete SQL schema.

package/examples/nextjs-supabase/.env.example

@@ -0,0 +1,10 @@
+NEXT_PUBLIC_SUPABASE_URL=https://YOUR_PROJECT.supabase.co
+NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
+SUPABASE_SERVICE_ROLE_KEY=YOUR_SERVICE_ROLE_KEY
+
+CLICKATELL_API_KEY=YOUR_CLICKATELL_API_KEY
+SMS_TIMEOUT_MS=10000
+
+APP_URL=http://localhost:3000
+ENABLE_SMS_CALLBACKS=true
+SMS_WEBHOOK_TOKEN=replace-with-a-long-random-secret

package/examples/nextjs-supabase/README.md

@@ -0,0 +1,211 @@
+# Next.js + Supabase integration
+
+A production-oriented reference for using `@doeza/sms-service` from a new Next.js App Router project backed by Supabase.
+
+The example deliberately keeps the SMS package server-only and leaves authentication, persistence, idempotency, policy, RLS, callback storage, and audit state in the host application.
+
+## What this example demonstrates
+
+- Next.js 16 App Router route handlers.
+- Supabase SSR authentication using `@supabase/ssr`.
+- A separate server-only service-role client for privileged SMS persistence.
+- Required application idempotency keys.
+- Atomic creation of an SMS request and its recipients.
+- Atomic claim-before-send so concurrent requests cannot both transmit the same intent.
+- One provider request per claimed intent.
+- Per-recipient Clickatell acceptance/rejection persistence.
+- An explicit `uncertain` state for timeout/network/provider/invalid-response outcomes.
+- Delivery-status callback event storage without assuming callback arrival order equals delivery order.
+- Incoming-reply deduplication.
+- Row Level Security for user-readable operational data.
+- No automatic send retries.
+
+## 1. Create the Next.js project
+
+```sh
+pnpm create next-app@latest sms-example --ts --app --src-dir
+cd sms-example
+pnpm add @supabase/supabase-js @supabase/ssr
+```
+
+Install the SMS package from this repository:
+
+```sh
+# In sms-app
+pnpm pack:sms
+
+# In the new Next.js project
+pnpm add /absolute/path/to/sms-app/packages/sms-service/doeza-sms-service-1.0.0.tgz
+```
+
+The package requires Node.js 22+.
+
+## 2. Copy the example files
+
+Copy the contents of this example's `src/` directory into your new project's `src/` directory.
+
+Recommended structure:
+
+```txt
+src/
+  app/api/sms/send/route.ts
+  app/api/sms/callbacks/status/route.ts
+  app/api/sms/callbacks/reply/route.ts
+  lib/sms/repository.ts
+  lib/sms/send-request.ts
+  lib/sms/service.ts
+  lib/sms/webhook-auth.ts
+  lib/supabase/admin.ts
+  lib/supabase/server.ts
+supabase/
+  schema.sql
+```
+
+## 3. Apply the database schema
+
+Run [`supabase/schema.sql`](./supabase/schema.sql) in the Supabase SQL editor or include it in your migrations.
+
+The schema contains:
+
+- `sms_requests`
+- `sms_recipients`
+- `sms_attempts`
+- `sms_status_events`
+- `sms_replies`
+- enums and constraints
+- updated-at triggers
+- RLS policies
+- `create_sms_request(...)`
+- `claim_sms_request(...)`
+- indexes and grants
+
+`create_sms_request(...)` makes the application idempotency key authoritative. Reusing the same key with different content or recipients fails instead of silently changing an existing intent.
+
+`claim_sms_request(...)` transitions only `queued -> sending` while holding a row lock. If two handlers race, only one can claim and call Clickatell.
+
+## 4. Configure environment variables
+
+Copy `.env.example` to `.env.local` and set real values.
+
+`SUPABASE_SERVICE_ROLE_KEY` and `CLICKATELL_API_KEY` are server-only secrets. Never expose them through `NEXT_PUBLIC_*`.
+
+For callbacks, use a long random `SMS_WEBHOOK_TOKEN`. This example embeds the token into the configured callback URL and verifies it before parsing callback payloads. Treat callback URLs as secret-bearing and do not log them.
+
+If your ingress/provider setup supports a stronger documented verification mechanism, replace `verifySmsWebhookRequest()` with that mechanism. Do not invent a provider signature algorithm.
+
+## 5. Send an SMS
+
+The example route requires an authenticated Supabase user and an `Idempotency-Key` header.
+
+Request:
+
+```http
+POST /api/sms/send
+Idempotency-Key: booking-confirmation:5a6201a7
+Content-Type: application/json
+
+{
+  "to": "+46701234567",
+  "content": "Your booking is confirmed."
+}
+```
+
+Example browser/server call:
+
+```ts
+const response = await fetch("/api/sms/send", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    "Idempotency-Key": `booking-confirmation:${bookingId}`,
+  },
+  body: JSON.stringify({
+    to: customer.phoneNumber,
+    content: "Your booking is confirmed.",
+  }),
+});
+
+const data = await response.json();
+```
+
+For a real product, prefer a domain-specific API such as `{ bookingId }` and resolve the phone number and message template server-side. A generic authenticated relay is useful for demonstrating the integration, but product authorization, recipient ownership, quotas, rate limits, consent, and template policy still belong in your application.
+
+## 6. Idempotency and retries
+
+There are two different identifiers:
+
+- `Idempotency-Key`: host-application duplicate-intent protection.
+- `clientMessageId`: correlation value passed to `@doeza/sms-service` and Clickatell.
+
+The database request UUID is reused as `clientMessageId` so one value links database records, provider results, callbacks, and logs.
+
+`clientMessageId` by itself is not an idempotency guarantee.
+
+The send workflow is:
+
+```txt
+create/recover durable intent
+        |
+        v
+atomically claim queued -> sending
+        |
+        v
+call sms.send() exactly once
+        |
+        +--> accepted/partial/rejected -> persist result
+        |
+        +--> ambiguous transport/provider error -> uncertain
+```
+
+Do not automatically retry requests in `sending` or `uncertain`. A process can lose the response after the provider accepted the SMS. Reconcile provider state before any resend.
+
+A crash after the row is claimed but before result persistence intentionally leaves the request in `sending`. That is safer than automatically transmitting it again.
+
+## 7. Acceptance is not delivery
+
+`sms.send()` reports provider acceptance. Delivery is a separate lifecycle driven by later status callbacks.
+
+This schema therefore stores:
+
+- send-request state in `sms_requests`
+- per-recipient acceptance in `sms_recipients`
+- every normalized delivery callback in `sms_status_events`
+
+The callback example does not convert provider status strings into a universal `delivered` boolean because that mapping is provider/business-policy specific and callbacks can arrive out of order. Build an explicit transition policy for the Clickatell statuses your account actually receives.
+
+## 8. Incoming replies
+
+`/api/sms/callbacks/reply` stores normalized reply payloads in `sms_replies`.
+
+A SHA-256 `dedupe_key` makes repeated callbacks idempotent. Replies are linked back to a known request/recipient when the callback contains a provider `messageId` that matches a stored `provider_message_id`.
+
+Treat incoming text as untrusted input. If replies trigger commands or business actions, run normal parsing, authorization-by-context, validation, and anti-abuse checks first.
+
+## 9. RLS model
+
+Authenticated users can read their own:
+
+- SMS requests
+- recipients
+- attempts
+- status events linked to their requests
+- replies linked to their requests
+
+Client-side inserts and updates are not granted. All SMS workflow writes use the service-role client on the server.
+
+Unlinked inbound replies are intentionally not visible to normal users.
+
+## 10. Operational rules
+
+Do not log:
+
+- Clickatell API keys
+- Supabase service-role keys
+- full provider request URLs
+- callback URLs containing the webhook token
+- full SMS bodies by default
+- raw native fetch errors from the provider request
+
+Useful structured fields include request ID/clientMessageId, account/user ID, recipient count, outcome category, `SmsError.code`, latency, and provider message IDs where appropriate.
+
+Add your own rate limiter and quota policy before exposing the send route in production.

package/examples/nextjs-supabase/src/app/api/sms/callbacks/reply/route.ts

@@ -0,0 +1,12 @@
+import { createReplyCallbackHandler } from "@doeza/sms-service/http";
+import { saveReplyCallback } from "@/lib/sms/repository";
+import { verifySmsWebhookRequest } from "@/lib/sms/webhook-auth";
+
+export const runtime = "nodejs";
+
+const handler = createReplyCallbackHandler(saveReplyCallback, {
+  authorize: verifySmsWebhookRequest,
+});
+
+export const GET = handler;
+export const POST = handler;

package/examples/nextjs-supabase/src/app/api/sms/callbacks/status/route.ts

@@ -0,0 +1,12 @@
+import { createStatusCallbackHandler } from "@doeza/sms-service/http";
+import { saveStatusCallback } from "@/lib/sms/repository";
+import { verifySmsWebhookRequest } from "@/lib/sms/webhook-auth";
+
+export const runtime = "nodejs";
+
+const handler = createStatusCallbackHandler(saveStatusCallback, {
+  authorize: verifySmsWebhookRequest,
+});
+
+export const GET = handler;
+export const POST = handler;

package/examples/nextjs-supabase/src/app/api/sms/send/route.ts

@@ -0,0 +1,133 @@
+import { SmsError, normalizeRecipients } from "@doeza/sms-service";
+import {
+  createSmsRequest,
+  SmsRequestConflictError,
+} from "@/lib/sms/repository";
+import { processSmsRequest } from "@/lib/sms/send-request";
+import { createSupabaseServerClient } from "@/lib/supabase/server";
+
+export const runtime = "nodejs";
+
+type Body = {
+  to?: unknown;
+  content?: unknown;
+};
+
+function smsErrorStatus(error: SmsError): number {
+  switch (error.code) {
+    case "VALIDATION":
+      return 400;
+    case "CONFIGURATION":
+      return 500;
+    case "ABORTED":
+      return 408;
+    case "PROVIDER":
+    case "INVALID_RESPONSE":
+      return 502;
+    case "NETWORK":
+    case "TIMEOUT":
+      return 504;
+  }
+}
+
+export async function POST(request: Request): Promise<Response> {
+  const supabase = await createSupabaseServerClient();
+  const {
+    data: { user },
+    error: authError,
+  } = await supabase.auth.getUser();
+
+  if (authError || !user) {
+    return Response.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  const idempotencyKey = request.headers.get("Idempotency-Key")?.trim();
+  if (!idempotencyKey || idempotencyKey.length > 200) {
+    return Response.json(
+      { error: "A 1-200 character Idempotency-Key header is required." },
+      { status: 400 },
+    );
+  }
+
+  let body: Body;
+  try {
+    body = (await request.json()) as Body;
+  } catch {
+    return Response.json({ error: "Request body must be valid JSON." }, { status: 400 });
+  }
+
+  if (typeof body.content !== "string" || !body.content.trim()) {
+    return Response.json({ error: "content must be a non-empty string." }, { status: 400 });
+  }
+
+  let recipients: string[];
+  try {
+    recipients = normalizeRecipients(body.to);
+  } catch (error) {
+    if (error instanceof SmsError) {
+      return Response.json({ error: error.message, code: error.code }, { status: 400 });
+    }
+    throw error;
+  }
+
+  let requestId: string;
+  try {
+    requestId = await createSmsRequest({
+      ownerId: user.id,
+      idempotencyKey,
+      content: body.content,
+      recipients,
+    });
+  } catch (error) {
+    if (error instanceof SmsRequestConflictError) {
+      return Response.json(
+        { error: "The idempotency key is already bound to different SMS data." },
+        { status: 409 },
+      );
+    }
+
+    return Response.json(
+      { error: "Could not create the SMS request." },
+      { status: 500 },
+    );
+  }
+
+  try {
+    const outcome = await processSmsRequest(requestId);
+
+    if (outcome.kind === "existing") {
+      return Response.json({
+        requestId,
+        state: outcome.request.state,
+        duplicate: true,
+      });
+    }
+
+    return Response.json({
+      requestId,
+      state: outcome.request.state,
+      success: outcome.result.success,
+      partial: outcome.result.partial,
+      messages: outcome.result.messages,
+    });
+  } catch (error) {
+    if (error instanceof SmsError) {
+      return Response.json(
+        {
+          requestId,
+          error: "SMS provider request failed.",
+          code: error.code,
+        },
+        { status: smsErrorStatus(error) },
+      );
+    }
+
+    return Response.json(
+      {
+        requestId,
+        error: "SMS workflow persistence failed. Do not automatically resend this request.",
+      },
+      { status: 500 },
+    );
+  }
+}