@doeza/sms-service 1.0.0

package/examples/nextjs-supabase/supabase/schema.sql

@@ -0,0 +1,399 @@
+begin;
+
+create extension if not exists pgcrypto;
+
+create type public.sms_request_state as enum (
+  'queued',
+  'sending',
+  'accepted',
+  'partial',
+  'rejected',
+  'uncertain',
+  'failed'
+);
+
+create type public.sms_recipient_state as enum (
+  'pending',
+  'accepted',
+  'rejected'
+);
+
+create type public.sms_attempt_state as enum (
+  'sending',
+  'accepted',
+  'partial',
+  'rejected',
+  'uncertain',
+  'failed'
+);
+
+create table public.sms_requests (
+  id uuid primary key default gen_random_uuid(),
+  owner_id uuid not null references auth.users(id) on delete cascade,
+  idempotency_key text not null,
+  client_message_id text not null unique,
+  content text not null,
+  state public.sms_request_state not null default 'queued',
+  response_code integer,
+  error_code text,
+  error_http_status integer,
+  sending_started_at timestamptz,
+  provider_accepted_at timestamptz,
+  completed_at timestamptz,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  constraint sms_requests_idempotency_key_nonblank check (length(btrim(idempotency_key)) between 1 and 200),
+  constraint sms_requests_content_nonblank check (length(btrim(content)) > 0),
+  constraint sms_requests_owner_idempotency_unique unique (owner_id, idempotency_key)
+);
+
+create table public.sms_recipients (
+  id uuid primary key default gen_random_uuid(),
+  request_id uuid not null references public.sms_requests(id) on delete cascade,
+  to_number text not null,
+  state public.sms_recipient_state not null default 'pending',
+  provider_message_id text,
+  provider_error_code text,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  constraint sms_recipients_international_number check (to_number ~ '^[1-9][0-9]{4,14}$'),
+  constraint sms_recipients_request_number_unique unique (request_id, to_number)
+);
+
+create unique index sms_recipients_provider_message_id_unique
+  on public.sms_recipients(provider_message_id)
+  where provider_message_id is not null;
+
+create index sms_recipients_request_id_idx on public.sms_recipients(request_id);
+
+create table public.sms_attempts (
+  id uuid primary key default gen_random_uuid(),
+  request_id uuid not null references public.sms_requests(id) on delete cascade,
+  attempt_no integer not null,
+  state public.sms_attempt_state not null default 'sending',
+  error_code text,
+  error_http_status integer,
+  started_at timestamptz not null default now(),
+  finished_at timestamptz,
+  constraint sms_attempts_positive_number check (attempt_no > 0),
+  constraint sms_attempts_request_number_unique unique (request_id, attempt_no)
+);
+
+create index sms_attempts_request_id_idx on public.sms_attempts(request_id);
+
+create table public.sms_status_events (
+  id uuid primary key default gen_random_uuid(),
+  dedupe_key text not null unique,
+  request_id uuid references public.sms_requests(id) on delete set null,
+  recipient_id uuid references public.sms_recipients(id) on delete set null,
+  provider_message_id text not null,
+  provider_request_id text,
+  client_message_id text,
+  integration_name text,
+  to_number text not null,
+  from_number text,
+  status_code integer not null,
+  status text not null,
+  status_description text,
+  provider_timestamp text not null,
+  normalized_payload jsonb not null,
+  received_at timestamptz not null default now()
+);
+
+create index sms_status_events_request_id_idx on public.sms_status_events(request_id);
+create index sms_status_events_recipient_id_idx on public.sms_status_events(recipient_id);
+create index sms_status_events_provider_message_id_idx on public.sms_status_events(provider_message_id);
+
+create table public.sms_replies (
+  id uuid primary key default gen_random_uuid(),
+  dedupe_key text not null unique,
+  request_id uuid references public.sms_requests(id) on delete set null,
+  recipient_id uuid references public.sms_recipients(id) on delete set null,
+  reply_message_id text,
+  provider_message_id text,
+  integration_name text,
+  from_number text not null,
+  to_number text not null,
+  provider_timestamp bigint not null,
+  text text not null,
+  charset text,
+  udh text,
+  network integer,
+  keyword text,
+  normalized_payload jsonb not null,
+  received_at timestamptz not null default now(),
+  constraint sms_replies_text_nonblank check (length(btrim(text)) > 0)
+);
+
+create unique index sms_replies_reply_message_id_unique
+  on public.sms_replies(reply_message_id)
+  where reply_message_id is not null;
+
+create index sms_replies_request_id_idx on public.sms_replies(request_id);
+create index sms_replies_recipient_id_idx on public.sms_replies(recipient_id);
+create index sms_replies_provider_message_id_idx on public.sms_replies(provider_message_id);
+
+create or replace function public.set_updated_at()
+returns trigger
+language plpgsql
+set search_path = public
+as $$
+begin
+  new.updated_at = now();
+  return new;
+end;
+$$;
+
+create trigger sms_requests_set_updated_at
+before update on public.sms_requests
+for each row execute function public.set_updated_at();
+
+create trigger sms_recipients_set_updated_at
+before update on public.sms_recipients
+for each row execute function public.set_updated_at();
+
+create or replace function public.create_sms_request(
+  p_owner_id uuid,
+  p_idempotency_key text,
+  p_content text,
+  p_recipients text[]
+)
+returns uuid
+language plpgsql
+security definer
+set search_path = public
+as $$
+declare
+  v_request_id uuid;
+  v_existing_content text;
+  v_existing_recipients text[];
+  v_recipients text[];
+begin
+  if p_owner_id is null then
+    raise exception 'owner_id is required' using errcode = '22023';
+  end if;
+
+  if p_idempotency_key is null or length(btrim(p_idempotency_key)) not between 1 and 200 then
+    raise exception 'idempotency_key must contain 1-200 characters' using errcode = '22023';
+  end if;
+
+  if p_content is null or length(btrim(p_content)) = 0 then
+    raise exception 'content cannot be blank' using errcode = '22023';
+  end if;
+
+  if p_recipients is null or cardinality(p_recipients) = 0 then
+    raise exception 'at least one recipient is required' using errcode = '22023';
+  end if;
+
+  select array_agg(distinct recipient order by recipient)
+    into v_recipients
+  from unnest(p_recipients) as recipient;
+
+  if exists (
+    select 1
+    from unnest(v_recipients) as recipient
+    where recipient !~ '^[1-9][0-9]{4,14}$'
+  ) then
+    raise exception 'recipients must already be normalized international numbers' using errcode = '22023';
+  end if;
+
+  select id, content
+    into v_request_id, v_existing_content
+  from public.sms_requests
+  where owner_id = p_owner_id
+    and idempotency_key = btrim(p_idempotency_key)
+  for update;
+
+  if found then
+    select array_agg(to_number order by to_number)
+      into v_existing_recipients
+    from public.sms_recipients
+    where request_id = v_request_id;
+
+    if v_existing_content is distinct from p_content
+       or v_existing_recipients is distinct from v_recipients then
+      raise exception 'idempotency key was already used with different SMS data' using errcode = '22023';
+    end if;
+
+    return v_request_id;
+  end if;
+
+  v_request_id := gen_random_uuid();
+
+  insert into public.sms_requests (
+    id,
+    owner_id,
+    idempotency_key,
+    client_message_id,
+    content
+  ) values (
+    v_request_id,
+    p_owner_id,
+    btrim(p_idempotency_key),
+    v_request_id::text,
+    p_content
+  );
+
+  insert into public.sms_recipients (request_id, to_number)
+  select v_request_id, recipient
+  from unnest(v_recipients) as recipient;
+
+  return v_request_id;
+exception
+  when unique_violation then
+    select id into v_request_id
+    from public.sms_requests
+    where owner_id = p_owner_id
+      and idempotency_key = btrim(p_idempotency_key);
+
+    if v_request_id is null then
+      raise;
+    end if;
+
+    select content into v_existing_content
+    from public.sms_requests
+    where id = v_request_id;
+
+    select array_agg(to_number order by to_number)
+      into v_existing_recipients
+    from public.sms_recipients
+    where request_id = v_request_id;
+
+    if v_existing_content is distinct from p_content
+       or v_existing_recipients is distinct from v_recipients then
+      raise exception 'idempotency key was already used with different SMS data' using errcode = '22023';
+    end if;
+
+    return v_request_id;
+end;
+$$;
+
+create or replace function public.claim_sms_request(p_request_id uuid)
+returns boolean
+language plpgsql
+security definer
+set search_path = public
+as $$
+declare
+  v_state public.sms_request_state;
+  v_attempt_no integer;
+begin
+  select state
+    into v_state
+  from public.sms_requests
+  where id = p_request_id
+  for update;
+
+  if not found or v_state <> 'queued' then
+    return false;
+  end if;
+
+  select coalesce(max(attempt_no), 0) + 1
+    into v_attempt_no
+  from public.sms_attempts
+  where request_id = p_request_id;
+
+  update public.sms_requests
+  set state = 'sending',
+      sending_started_at = now(),
+      error_code = null,
+      error_http_status = null
+  where id = p_request_id;
+
+  insert into public.sms_attempts (request_id, attempt_no, state)
+  values (p_request_id, v_attempt_no, 'sending');
+
+  return true;
+end;
+$$;
+
+alter table public.sms_requests enable row level security;
+alter table public.sms_recipients enable row level security;
+alter table public.sms_attempts enable row level security;
+alter table public.sms_status_events enable row level security;
+alter table public.sms_replies enable row level security;
+
+create policy sms_requests_select_own
+on public.sms_requests
+for select
+to authenticated
+using (owner_id = auth.uid());
+
+create policy sms_recipients_select_own
+on public.sms_recipients
+for select
+to authenticated
+using (
+  exists (
+    select 1
+    from public.sms_requests request
+    where request.id = sms_recipients.request_id
+      and request.owner_id = auth.uid()
+  )
+);
+
+create policy sms_attempts_select_own
+on public.sms_attempts
+for select
+to authenticated
+using (
+  exists (
+    select 1
+    from public.sms_requests request
+    where request.id = sms_attempts.request_id
+      and request.owner_id = auth.uid()
+  )
+);
+
+create policy sms_status_events_select_own
+on public.sms_status_events
+for select
+to authenticated
+using (
+  request_id is not null
+  and exists (
+    select 1
+    from public.sms_requests request
+    where request.id = sms_status_events.request_id
+      and request.owner_id = auth.uid()
+  )
+);
+
+create policy sms_replies_select_own
+on public.sms_replies
+for select
+to authenticated
+using (
+  request_id is not null
+  and exists (
+    select 1
+    from public.sms_requests request
+    where request.id = sms_replies.request_id
+      and request.owner_id = auth.uid()
+  )
+);
+
+revoke all on public.sms_requests from anon, authenticated;
+revoke all on public.sms_recipients from anon, authenticated;
+revoke all on public.sms_attempts from anon, authenticated;
+revoke all on public.sms_status_events from anon, authenticated;
+revoke all on public.sms_replies from anon, authenticated;
+
+grant select on public.sms_requests to authenticated;
+grant select on public.sms_recipients to authenticated;
+grant select on public.sms_attempts to authenticated;
+grant select on public.sms_status_events to authenticated;
+grant select on public.sms_replies to authenticated;
+
+grant all on public.sms_requests to service_role;
+grant all on public.sms_recipients to service_role;
+grant all on public.sms_attempts to service_role;
+grant all on public.sms_status_events to service_role;
+grant all on public.sms_replies to service_role;
+
+revoke all on function public.create_sms_request(uuid, text, text, text[]) from public, anon, authenticated;
+revoke all on function public.claim_sms_request(uuid) from public, anon, authenticated;
+grant execute on function public.create_sms_request(uuid, text, text, text[]) to service_role;
+grant execute on function public.claim_sms_request(uuid) to service_role;
+
+commit;

package/examples/send.mjs

@@ -0,0 +1,18 @@
+import { createSmsService, SmsError } from "../index.js";
+
+const [to, ...words] = process.argv.slice(2);
+if (!to || words.length === 0) {
+  console.error('Usage: node --env-file=.env.local examples/send.mjs +46701234567 "Hello"');
+  process.exitCode = 1;
+} else {
+  try {
+    const sms = createSmsService({ apiKey: process.env.CLICKATELL_API_KEY });
+    const result = await sms.send({ to, content: words.join(" ") });
+    console.log(JSON.stringify(result));
+    if (!result.success) process.exitCode = 1;
+  } catch (error) {
+    if (!(error instanceof SmsError)) throw error;
+    console.error(error.code, error.message, error.clientMessageId ?? "");
+    process.exitCode = 1;
+  }
+}

package/http.d.ts

@@ -0,0 +1,9 @@
+import type { SmsReply, SmsService, SmsStatus } from "./index.js";
+export type RequestHandler = (request: Request) => Promise<Response>;
+export interface HandlerOptions {
+  /** Run the host application's authentication/rate-limit checks before processing. */
+  authorize?: (request: Request) => boolean | Promise<boolean>;
+}
+export function createSendSmsHandler(service: SmsService | (() => SmsService), options?: HandlerOptions): RequestHandler;
+export function createStatusCallbackHandler(onStatus: (status: SmsStatus) => void | Promise<void>, options?: HandlerOptions): RequestHandler;
+export function createReplyCallbackHandler(onReply: (reply: SmsReply) => void | Promise<void>, options?: HandlerOptions): RequestHandler;

package/http.js

@@ -0,0 +1,75 @@
+import { SmsError, parseReplyCallback, parseStatusCallback } from "./index.js";
+
+const json = (body, status = 200, headers = {}) => Response.json(body, { status, headers: { "Cache-Control": "no-store", ...headers } });
+
+function errorResponse(error) {
+  if (!(error instanceof SmsError)) return json({ success: false, message: "An unexpected server error occurred." }, 500);
+  const statuses = { VALIDATION: 400, CONFIGURATION: 500, PROVIDER: 502, INVALID_RESPONSE: 502, NETWORK: 504, TIMEOUT: 504, ABORTED: 408 };
+  return json({
+    success: false,
+    message: error.code === "CONFIGURATION" ? "The SMS service is not configured correctly." : error.message,
+    code: error.code,
+    ...(error.clientMessageId ? { clientMessageId: error.clientMessageId } : {}),
+  }, statuses[error.code] ?? 500);
+}
+
+async function readJson(request) {
+  try { return await request.json(); } catch {
+    throw new SmsError("VALIDATION", "Request body must contain valid JSON.");
+  }
+}
+
+async function authorized(request, options) {
+  return !options.authorize || await options.authorize(request);
+}
+
+export function createSendSmsHandler(service, options = {}) {
+  return async (request) => {
+    if (request.method !== "POST") return json({ success: false, message: "Use POST." }, 405, { Allow: "POST" });
+    try {
+      if (!await authorized(request, options)) return json({ success: false, message: "Unauthorized." }, 401);
+      const input = await readJson(request);
+      const sms = typeof service === "function" ? service() : service;
+      const result = await sms.send(input, { signal: request.signal });
+      // Preserve the existing app's response parser while exposing structured fields.
+      const providerResponse = JSON.stringify({ responseCode: result.responseCode, messages: result.messages });
+      const message = result.success
+        ? `SMS sent successfully to ${result.to.join(",")} (accepted by provider). Provider response: ${providerResponse}`
+        : result.partial
+          ? "Only some recipients were accepted. Inspect messages before retrying rejected recipients."
+          : "The SMS provider rejected all recipients.";
+      return json({ ...result, message });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  };
+}
+
+function createCallbackHandler(parse, consume, message, options) {
+  if (typeof consume !== "function") throw new SmsError("CONFIGURATION", "A callback consumer is required.");
+  return async (request) => {
+    if (!["GET", "POST"].includes(request.method)) return json({ success: false, message: "Use GET or POST." }, 405, { Allow: "GET, POST" });
+    try {
+      if (!await authorized(request, options)) return json({ success: false, message: "Unauthorized." }, 401);
+      let body;
+      if (request.method === "GET") body = Object.fromEntries(new URL(request.url).searchParams);
+      else if (request.headers.get("content-type")?.split(";")[0].trim() === "application/x-www-form-urlencoded") {
+        body = Object.fromEntries(new URLSearchParams(await request.text()));
+      } else body = await readJson(request);
+      const payload = parse(body);
+      // Acknowledge only after the host application's consumer succeeds.
+      await consume(payload);
+      return json({ success: true, message });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  };
+}
+
+export function createStatusCallbackHandler(onStatus, options = {}) {
+  return createCallbackHandler(parseStatusCallback, onStatus, "Status received", options);
+}
+
+export function createReplyCallbackHandler(onReply, options = {}) {
+  return createCallbackHandler(parseReplyCallback, onReply, "Reply received", options);
+}

package/index.d.ts

@@ -0,0 +1,70 @@
+export type SmsErrorCode = "CONFIGURATION" | "VALIDATION" | "PROVIDER" | "INVALID_RESPONSE" | "NETWORK" | "TIMEOUT" | "ABORTED";
+export class SmsError extends Error {
+  readonly code: SmsErrorCode;
+  readonly httpStatus?: number;
+  readonly clientMessageId?: string;
+  constructor(code: SmsErrorCode, message: string, details?: { httpStatus?: number; clientMessageId?: string });
+}
+export interface SmsOptions {
+  apiKey: string;
+  timeoutMs?: number;
+  fetch?: typeof globalThis.fetch;
+  /** Optional absolute URLs; the host app owns callback configuration. */
+  statusCallbackUrl?: string;
+  replyCallbackUrl?: string;
+}
+export interface SendSmsInput {
+  /** International numbers, with optional +; array or comma-separated string. */
+  to: string | readonly string[];
+  content: string;
+  /** Correlation identifier, not an idempotency guarantee. */
+  clientMessageId?: string;
+}
+export interface SmsMessageResult {
+  to: string;
+  accepted: boolean;
+  apiMessageId?: string;
+  errorCode?: string | number;
+}
+export interface SmsResult {
+  success: boolean;
+  partial: boolean;
+  clientMessageId: string;
+  to: string[];
+  responseCode?: number;
+  messages: SmsMessageResult[];
+}
+export interface SmsService {
+  /** One provider request. Never automatically retries. Acceptance is not delivery. */
+  send(input: SendSmsInput, options?: { signal?: AbortSignal }): Promise<SmsResult>;
+}
+export function createSmsService(options: SmsOptions): SmsService;
+export function normalizeRecipients(to: unknown): string[];
+export interface SmsStatus {
+  integrationName?: string;
+  messageId: string;
+  requestId?: string;
+  clientMessageId?: string;
+  to: string;
+  from?: string;
+  statusCode: number;
+  status: string;
+  statusDescription?: string;
+  timestamp: string;
+}
+export interface SmsReply {
+  integrationName?: string;
+  replyMessageId?: string;
+  messageId?: string;
+  fromNumber: string;
+  toNumber: string;
+  timestamp: number;
+  text: string;
+  charset?: string;
+  udh?: string;
+  network?: number;
+  keyword?: string;
+}
+/** Parse the callback payloads used by this app; these functions do not authenticate requests. */
+export function parseStatusCallback(input: unknown): SmsStatus;
+export function parseReplyCallback(input: unknown): SmsReply;