@doeza/sms-service 1.0.0

package/index.js

@@ -0,0 +1,176 @@
+import { randomUUID } from "node:crypto";
+
+export class SmsError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "SmsError";
+    this.code = code;
+    this.httpStatus = details.httpStatus;
+    this.clientMessageId = details.clientMessageId;
+  }
+}
+
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const invalid = (message) => { throw new SmsError("VALIDATION", message); };
+
+export function normalizeRecipients(to) {
+  const values = typeof to === "string" ? to.split(",") : to;
+  if (!Array.isArray(values) || values.length === 0) invalid("At least one recipient is required.");
+  const numbers = values.map((value) => {
+    if (typeof value !== "string") invalid("Recipients must be strings.");
+    const number = value.trim().replace(/^\+/, "");
+    if (!/^[1-9]\d{4,14}$/.test(number)) {
+      invalid("Use international phone numbers with 5–15 digits, including the country code.");
+    }
+    return number;
+  });
+  return [...new Set(numbers)];
+}
+
+function callbackUrl(value) {
+  if (value === undefined) return undefined;
+  try {
+    const url = new URL(value);
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.hash) throw new Error();
+    return url.href;
+  } catch {
+    throw new SmsError("CONFIGURATION", "Callback URLs must be absolute HTTP(S) URLs without credentials or fragments.");
+  }
+}
+
+function parseResponse(body, to, clientMessageId, httpStatus) {
+  const fail = () => { throw new SmsError("INVALID_RESPONSE", "The SMS provider returned an invalid response. Check message status before retrying.", { httpStatus, clientMessageId }); };
+  if (!object(body)) fail();
+  // Clickatell may reject a request inside a successful HTTP response.
+  if (body.error || (body.responseCode !== undefined && (!Number.isInteger(body.responseCode) || body.responseCode >= 400))) {
+    throw new SmsError("PROVIDER", "The SMS provider rejected the request.", { httpStatus, clientMessageId });
+  }
+  if (!Array.isArray(body.messages) || body.messages.length !== to.length) fail();
+  const seen = new Set();
+  const messages = body.messages.map((entry) => {
+    if (!object(entry) || typeof entry.to !== "string" || typeof entry.accepted !== "boolean") fail();
+    const recipient = entry.to.replace(/^\+/, "");
+    if (!to.includes(recipient) || seen.has(recipient)) fail();
+    seen.add(recipient);
+    if (entry.accepted && (typeof entry.apiMessageId !== "string" || !entry.apiMessageId.trim())) fail();
+    const result = { to: recipient, accepted: entry.accepted };
+    if (typeof entry.apiMessageId === "string") result.apiMessageId = entry.apiMessageId;
+    const errorCode = entry.errorCode ?? entry.error?.code;
+    if (typeof errorCode === "string" || typeof errorCode === "number") result.errorCode = errorCode;
+    return result;
+  });
+  const accepted = messages.filter((message) => message.accepted).length;
+  return {
+    success: accepted === to.length,
+    partial: accepted > 0 && accepted < to.length,
+    clientMessageId,
+    to,
+    ...(body.responseCode === undefined ? {} : { responseCode: body.responseCode }),
+    messages,
+  };
+}
+
+export function createSmsService(options) {
+  if (!object(options) || typeof options.apiKey !== "string" || !options.apiKey.trim()) {
+    throw new SmsError("CONFIGURATION", "A Clickatell API key is required.");
+  }
+  const apiKey = options.apiKey.trim();
+  const timeoutMs = options.timeoutMs ?? 10000;
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 2147483647) {
+    throw new SmsError("CONFIGURATION", "timeoutMs must be a positive integer no greater than 2147483647.");
+  }
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") throw new SmsError("CONFIGURATION", "A Fetch API implementation is required.");
+  const statusCallbackUrl = callbackUrl(options.statusCallbackUrl);
+  const replyCallbackUrl = callbackUrl(options.replyCallbackUrl);
+
+  return {
+    async send(input, { signal } = {}) {
+      if (!object(input)) invalid("An SMS request object is required.");
+      const to = normalizeRecipients(input.to);
+      if (typeof input.content !== "string" || !input.content.trim()) invalid("Message content cannot be empty.");
+      if (input.clientMessageId !== undefined && (typeof input.clientMessageId !== "string" || !input.clientMessageId.trim())) {
+        invalid("clientMessageId must be a non-empty string.");
+      }
+      const clientMessageId = input.clientMessageId ?? randomUUID();
+      const details = { clientMessageId };
+      if (signal?.aborted) throw new SmsError("ABORTED", "The SMS request was cancelled.", details);
+      const url = new URL("https://platform.clickatell.com/messages/http/send");
+      url.search = new URLSearchParams({ apiKey, to: to.join(","), content: input.content, clientMessageId }).toString();
+      if (statusCallbackUrl) url.searchParams.set("callback", statusCallbackUrl);
+      if (replyCallbackUrl) url.searchParams.set("replyCallback", replyCallbackUrl);
+
+      const controller = new AbortController();
+      const cancel = () => controller.abort();
+      signal?.addEventListener("abort", cancel, { once: true });
+      let timedOut = false;
+      const timer = setTimeout(() => { timedOut = true; controller.abort(); }, timeoutMs);
+      try {
+        const response = await fetchImpl(url.href, {
+          method: "GET", cache: "no-store", redirect: "error",
+          headers: { Accept: "application/json" }, signal: controller.signal,
+        });
+        if (!response.ok) {
+          await response.body?.cancel();
+          throw new SmsError("PROVIDER", `The SMS provider returned HTTP ${response.status}.`, { ...details, httpStatus: response.status });
+        }
+        const text = await response.text();
+        if (controller.signal.aborted) throw new Error();
+        let body;
+        try { body = JSON.parse(text); } catch {
+          throw new SmsError("INVALID_RESPONSE", "The SMS provider returned invalid JSON. Check message status before retrying.", details);
+        }
+        return parseResponse(body, to, clientMessageId, response.status);
+      } catch (error) {
+        if (timedOut) throw new SmsError("TIMEOUT", "The SMS request timed out. Check message status before retrying.", details);
+        if (signal?.aborted) throw new SmsError("ABORTED", "The SMS request was cancelled. Check message status before retrying.", details);
+        if (error instanceof SmsError) throw error;
+        // Native fetch errors can contain the credential-bearing URL. Do not expose them.
+        throw new SmsError("NETWORK", "Could not contact the SMS provider. Check message status before retrying.", details);
+      } finally {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", cancel);
+      }
+    },
+  };
+}
+
+function stringField(input, name, optional = false) {
+  const value = input[name];
+  if (optional && value === undefined) return undefined;
+  if (typeof value !== "string" || !value.trim()) invalid(`${name} must be a non-empty string.`);
+  return value;
+}
+
+function integerField(input, name, optional = false) {
+  const value = input[name];
+  if (optional && value === undefined) return undefined;
+  if ((typeof value !== "number" && typeof value !== "string") || !/^\d+$/.test(String(value)) || !Number.isSafeInteger(Number(value))) {
+    invalid(`${name} must be a non-negative integer.`);
+  }
+  return Number(value);
+}
+
+function optionalStrings(input, names) {
+  return Object.fromEntries(names.filter((name) => input[name] !== undefined).map((name) => [name, stringField(input, name, true)]));
+}
+
+export function parseStatusCallback(input) {
+  if (!object(input)) invalid("A status callback object is required.");
+  return {
+    ...optionalStrings(input, ["integrationName", "requestId", "clientMessageId", "from", "statusDescription"]),
+    messageId: stringField(input, "messageId"), to: stringField(input, "to"),
+    statusCode: integerField(input, "statusCode"), status: stringField(input, "status"),
+    timestamp: stringField(input, "timestamp"),
+  };
+}
+
+export function parseReplyCallback(input) {
+  if (!object(input)) invalid("A reply callback object is required.");
+  return {
+    ...optionalStrings(input, ["integrationName", "replyMessageId", "messageId", "charset", "udh", "keyword"]),
+    fromNumber: stringField(input, "fromNumber"), toNumber: stringField(input, "toNumber"),
+    timestamp: integerField(input, "timestamp"), text: stringField(input, "text"),
+    ...(input.network === undefined ? {} : { network: integerField(input, "network") }),
+  };
+}

package/package.json

@@ -0,0 +1 @@
+{"name":"@doeza/sms-service","version":"1.0.0","description":"Standalone server-side Clickatell SMS service with typed results and Web Request handlers","type":"module","main":"./index.js","types":"./index.d.ts","exports":{".":{"types":"./index.d.ts","import":"./index.js","default":"./index.js"},"./http":{"types":"./http.d.ts","import":"./http.js","default":"./http.js"}},"files":["*.js","*.d.ts","README.md","AGENTS.md","examples"],"engines":{"node":">=22"},"scripts":{"test":"node --test test/*.test.js"}}