@doeza/sms-service 1.0.0

package/examples/nextjs-supabase/src/lib/sms/repository.ts

@@ -0,0 +1,250 @@
+import "server-only";
+
+import { createHash } from "node:crypto";
+import type {
+  SmsError,
+  SmsReply,
+  SmsResult,
+  SmsStatus,
+} from "@doeza/sms-service";
+import { getSupabaseAdmin } from "@/lib/supabase/admin";
+
+export class SmsRequestConflictError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SmsRequestConflictError";
+  }
+}
+
+export type StoredSmsRequest = {
+  id: string;
+  owner_id: string;
+  client_message_id: string;
+  content: string;
+  state: string;
+  sms_recipients: Array<{
+    id: string;
+    to_number: string;
+    state: string;
+    provider_message_id: string | null;
+  }>;
+};
+
+function assertNoError(error: { message: string } | null, context: string): void {
+  if (error) throw new Error(`${context}: ${error.message}`);
+}
+
+function sha256(parts: Array<string | number | undefined>): string {
+  return createHash("sha256")
+    .update(parts.map((part) => String(part ?? "")).join("\u001f"))
+    .digest("hex");
+}
+
+export async function createSmsRequest(input: {
+  ownerId: string;
+  idempotencyKey: string;
+  content: string;
+  recipients: string[];
+}): Promise<string> {
+  const admin = getSupabaseAdmin();
+  const { data, error } = await admin.rpc("create_sms_request", {
+    p_owner_id: input.ownerId,
+    p_idempotency_key: input.idempotencyKey,
+    p_content: input.content,
+    p_recipients: input.recipients,
+  });
+
+  if (error?.code === "22023") {
+    throw new SmsRequestConflictError(error.message);
+  }
+  assertNoError(error, "Could not create SMS request");
+
+  if (typeof data !== "string") throw new Error("SMS request RPC returned an invalid id.");
+  return data;
+}
+
+export async function claimSmsRequest(requestId: string): Promise<boolean> {
+  const admin = getSupabaseAdmin();
+  const { data, error } = await admin.rpc("claim_sms_request", {
+    p_request_id: requestId,
+  });
+  assertNoError(error, "Could not claim SMS request");
+  return data === true;
+}
+
+export async function getSmsRequest(requestId: string): Promise<StoredSmsRequest> {
+  const admin = getSupabaseAdmin();
+  const { data, error } = await admin
+    .from("sms_requests")
+    .select(
+      "id,owner_id,client_message_id,content,state,sms_recipients(id,to_number,state,provider_message_id)",
+    )
+    .eq("id", requestId)
+    .single();
+
+  assertNoError(error, "Could not load SMS request");
+  if (!data) throw new Error("SMS request was not found.");
+  return data as StoredSmsRequest;
+}
+
+export async function recordSmsResult(
+  requestId: string,
+  result: SmsResult,
+): Promise<void> {
+  const admin = getSupabaseAdmin();
+
+  for (const message of result.messages) {
+    const { error } = await admin
+      .from("sms_recipients")
+      .update({
+        state: message.accepted ? "accepted" : "rejected",
+        provider_message_id: message.apiMessageId ?? null,
+        provider_error_code:
+          message.errorCode === undefined ? null : String(message.errorCode),
+      })
+      .eq("request_id", requestId)
+      .eq("to_number", message.to);
+    assertNoError(error, "Could not persist recipient result");
+  }
+
+  const state = result.success ? "accepted" : result.partial ? "partial" : "rejected";
+  const now = new Date().toISOString();
+
+  const { error: attemptError } = await admin
+    .from("sms_attempts")
+    .update({ state, finished_at: now })
+    .eq("request_id", requestId)
+    .eq("state", "sending");
+  assertNoError(attemptError, "Could not complete SMS attempt");
+
+  const { error: requestError } = await admin
+    .from("sms_requests")
+    .update({
+      state,
+      response_code: result.responseCode ?? null,
+      provider_accepted_at: result.messages.some((message) => message.accepted)
+        ? now
+        : null,
+      completed_at: now,
+      error_code: null,
+      error_http_status: null,
+    })
+    .eq("id", requestId);
+  assertNoError(requestError, "Could not complete SMS request");
+}
+
+export async function recordSmsError(
+  requestId: string,
+  error: SmsError,
+  state: "uncertain" | "failed",
+): Promise<void> {
+  const admin = getSupabaseAdmin();
+  const now = new Date().toISOString();
+
+  const { error: attemptError } = await admin
+    .from("sms_attempts")
+    .update({
+      state,
+      error_code: error.code,
+      error_http_status: error.httpStatus ?? null,
+      finished_at: now,
+    })
+    .eq("request_id", requestId)
+    .eq("state", "sending");
+  assertNoError(attemptError, "Could not persist SMS attempt failure");
+
+  const { error: requestError } = await admin
+    .from("sms_requests")
+    .update({
+      state,
+      error_code: error.code,
+      error_http_status: error.httpStatus ?? null,
+      completed_at: state === "failed" ? now : null,
+    })
+    .eq("id", requestId);
+  assertNoError(requestError, "Could not persist SMS request failure");
+}
+
+export async function saveStatusCallback(status: SmsStatus): Promise<void> {
+  const admin = getSupabaseAdmin();
+  const { data: recipient, error: lookupError } = await admin
+    .from("sms_recipients")
+    .select("id,request_id")
+    .eq("provider_message_id", status.messageId)
+    .maybeSingle();
+  assertNoError(lookupError, "Could not resolve delivery-status recipient");
+
+  const dedupeKey = sha256([
+    status.messageId,
+    status.statusCode,
+    status.status,
+    status.timestamp,
+  ]);
+
+  const { error } = await admin.from("sms_status_events").upsert(
+    {
+      dedupe_key: dedupeKey,
+      request_id: recipient?.request_id ?? null,
+      recipient_id: recipient?.id ?? null,
+      provider_message_id: status.messageId,
+      provider_request_id: status.requestId ?? null,
+      client_message_id: status.clientMessageId ?? null,
+      integration_name: status.integrationName ?? null,
+      to_number: status.to,
+      from_number: status.from ?? null,
+      status_code: status.statusCode,
+      status: status.status,
+      status_description: status.statusDescription ?? null,
+      provider_timestamp: status.timestamp,
+      normalized_payload: status,
+    },
+    { onConflict: "dedupe_key", ignoreDuplicates: true },
+  );
+  assertNoError(error, "Could not persist delivery-status callback");
+}
+
+export async function saveReplyCallback(reply: SmsReply): Promise<void> {
+  const admin = getSupabaseAdmin();
+  let recipient: { id: string; request_id: string } | null = null;
+
+  if (reply.messageId) {
+    const { data, error } = await admin
+      .from("sms_recipients")
+      .select("id,request_id")
+      .eq("provider_message_id", reply.messageId)
+      .maybeSingle();
+    assertNoError(error, "Could not resolve reply recipient");
+    recipient = data;
+  }
+
+  const dedupeKey = sha256([
+    reply.replyMessageId,
+    reply.messageId,
+    reply.fromNumber,
+    reply.toNumber,
+    reply.timestamp,
+    reply.text,
+  ]);
+
+  const { error } = await admin.from("sms_replies").upsert(
+    {
+      dedupe_key: dedupeKey,
+      request_id: recipient?.request_id ?? null,
+      recipient_id: recipient?.id ?? null,
+      reply_message_id: reply.replyMessageId ?? null,
+      provider_message_id: reply.messageId ?? null,
+      integration_name: reply.integrationName ?? null,
+      from_number: reply.fromNumber,
+      to_number: reply.toNumber,
+      provider_timestamp: reply.timestamp,
+      text: reply.text,
+      charset: reply.charset ?? null,
+      udh: reply.udh ?? null,
+      network: reply.network ?? null,
+      keyword: reply.keyword ?? null,
+      normalized_payload: reply,
+    },
+    { onConflict: "dedupe_key", ignoreDuplicates: true },
+  );
+  assertNoError(error, "Could not persist SMS reply callback");
+}

package/examples/nextjs-supabase/src/lib/sms/send-request.ts

@@ -0,0 +1,56 @@
+import "server-only";
+
+import { SmsError, type SmsResult } from "@doeza/sms-service";
+import {
+  claimSmsRequest,
+  getSmsRequest,
+  recordSmsError,
+  recordSmsResult,
+  type StoredSmsRequest,
+} from "@/lib/sms/repository";
+import { getSmsService } from "@/lib/sms/service";
+
+export type ProcessSmsRequestResult =
+  | { kind: "sent"; request: StoredSmsRequest; result: SmsResult }
+  | { kind: "existing"; request: StoredSmsRequest };
+
+export async function processSmsRequest(
+  requestId: string,
+): Promise<ProcessSmsRequestResult> {
+  const claimed = await claimSmsRequest(requestId);
+
+  if (!claimed) {
+    return { kind: "existing", request: await getSmsRequest(requestId) };
+  }
+
+  const request = await getSmsRequest(requestId);
+  const recipients = request.sms_recipients.map((recipient) => recipient.to_number);
+
+  let result: SmsResult;
+  try {
+    result = await getSmsService().send({
+      to: recipients,
+      content: request.content,
+      clientMessageId: request.client_message_id,
+    });
+  } catch (error) {
+    if (!(error instanceof SmsError)) {
+      // An unknown exception around provider I/O is not safe to resend automatically.
+      throw error;
+    }
+
+    const definitelyLocal = error.code === "CONFIGURATION" || error.code === "VALIDATION";
+    await recordSmsError(requestId, error, definitelyLocal ? "failed" : "uncertain");
+    throw error;
+  }
+
+  // If persistence fails here, leave the request in `sending` rather than automatically
+  // transmitting it again. Reconcile the provider result before any resend.
+  await recordSmsResult(requestId, result);
+
+  return {
+    kind: "sent",
+    request: await getSmsRequest(requestId),
+    result,
+  };
+}

package/examples/nextjs-supabase/src/lib/sms/service.ts

@@ -0,0 +1,43 @@
+import "server-only";
+
+import { createSmsService, SmsError, type SmsService } from "@doeza/sms-service";
+
+let service: SmsService | undefined;
+
+function callbackUrl(pathname: string): string | undefined {
+  if (process.env.ENABLE_SMS_CALLBACKS !== "true") return undefined;
+
+  const appUrl = process.env.APP_URL;
+  const token = process.env.SMS_WEBHOOK_TOKEN;
+
+  if (!appUrl || !token) {
+    throw new SmsError(
+      "CONFIGURATION",
+      "APP_URL and SMS_WEBHOOK_TOKEN are required when SMS callbacks are enabled.",
+    );
+  }
+
+  try {
+    const url = new URL(pathname, appUrl);
+    url.searchParams.set("token", token);
+    return url.href;
+  } catch {
+    throw new SmsError("CONFIGURATION", "APP_URL must be an absolute HTTP(S) URL.");
+  }
+}
+
+export function getSmsService(): SmsService {
+  if (service) return service;
+
+  service = createSmsService({
+    apiKey: process.env.CLICKATELL_API_KEY ?? "",
+    timeoutMs:
+      process.env.SMS_TIMEOUT_MS === undefined
+        ? 10_000
+        : Number(process.env.SMS_TIMEOUT_MS),
+    statusCallbackUrl: callbackUrl("/api/sms/callbacks/status"),
+    replyCallbackUrl: callbackUrl("/api/sms/callbacks/reply"),
+  });
+
+  return service;
+}

package/examples/nextjs-supabase/src/lib/sms/webhook-auth.ts

@@ -0,0 +1,19 @@
+import "server-only";
+
+import { timingSafeEqual } from "node:crypto";
+
+export function verifySmsWebhookRequest(request: Request): boolean {
+  const expected = process.env.SMS_WEBHOOK_TOKEN;
+  if (!expected) return false;
+
+  const actual = new URL(request.url).searchParams.get("token");
+  if (!actual) return false;
+
+  const expectedBytes = Buffer.from(expected);
+  const actualBytes = Buffer.from(actual);
+
+  return (
+    expectedBytes.length === actualBytes.length &&
+    timingSafeEqual(expectedBytes, actualBytes)
+  );
+}

package/examples/nextjs-supabase/src/lib/supabase/admin.ts

@@ -0,0 +1,25 @@
+import "server-only";
+
+import { createClient, type SupabaseClient } from "@supabase/supabase-js";
+
+let admin: SupabaseClient | undefined;
+
+export function getSupabaseAdmin(): SupabaseClient {
+  if (admin) return admin;
+
+  const url = process.env.NEXT_PUBLIC_SUPABASE_URL;
+  const serviceRoleKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
+
+  if (!url || !serviceRoleKey) {
+    throw new Error("Supabase server configuration is missing.");
+  }
+
+  admin = createClient(url, serviceRoleKey, {
+    auth: {
+      autoRefreshToken: false,
+      persistSession: false,
+    },
+  });
+
+  return admin;
+}

package/examples/nextjs-supabase/src/lib/supabase/server.ts

@@ -0,0 +1,28 @@
+import { createServerClient } from "@supabase/ssr";
+import { cookies } from "next/headers";
+
+export async function createSupabaseServerClient() {
+  const cookieStore = await cookies();
+
+  return createServerClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL ?? "",
+    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY ?? "",
+    {
+      cookies: {
+        getAll() {
+          return cookieStore.getAll();
+        },
+        setAll(cookiesToSet) {
+          try {
+            for (const { name, value, options } of cookiesToSet) {
+              cookieStore.set(name, value, options);
+            }
+          } catch {
+            // Some Server Component contexts cannot write cookies.
+            // Route handlers and server actions can.
+          }
+        },
+      },
+    },
+  );
+}