@listeningkit/telnyx 0.1.0

package/lib/telnyx.ts

@@ -0,0 +1,143 @@
+import nacl from "tweetnacl";
+
+export type TelnyxEventType = "message.received" | "message.sent" | "message.finalized";
+
+export type TelnyxMessagePayload = {
+  id: string;
+  direction: "inbound" | "outbound";
+  to: Array<{ phone_number: string; status?: string }>;
+  from?: { phone_number: string; carrier?: string; line_type?: string };
+  text?: string;
+  media?: Array<{ url: string; content_type?: string; size?: number }>;
+  errors?: Array<{ code: string; title?: string; detail?: string }>;
+  completed_at?: string | null;
+  messaging_profile_id?: string;
+  received_at?: string;
+};
+
+export type TelnyxWebhookEvent = {
+  event_type: TelnyxEventType;
+  id: string;
+  occurred_at?: string;
+  payload: TelnyxMessagePayload;
+};
+
+export type TelnyxSendInput = {
+  from: string;
+  to: string;
+  text: string;
+  webhook_url?: string;
+  media_urls?: string[];
+};
+
+export type TelnyxSendResult = {
+  id: string;
+  status: string;
+};
+
+export class TelnyxProviderError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = "TelnyxProviderError";
+  }
+}
+
+const E164 = /^\+[1-9]\d{6,14}$/;
+const MAX_WEBHOOK_AGE_MS = 5 * 60 * 1000;
+const EVENT_TYPES = new Set<TelnyxEventType>(["message.received", "message.sent", "message.finalized"]);
+
+function requireE164(value: string, field: string): string {
+  if (!E164.test(value)) throw new TelnyxProviderError(`${field} must be E.164 formatted`, 0);
+  return value;
+}
+
+function parseMessagePayload(value: unknown): TelnyxMessagePayload {
+  if (typeof value !== "object" || value === null) throw new TelnyxProviderError("Telnyx payload is missing", 0);
+  const payload = value as Partial<TelnyxMessagePayload>;
+  if (typeof payload.id !== "string" || !Array.isArray(payload.to)) {
+    throw new TelnyxProviderError("Telnyx payload has an unexpected shape", 0);
+  }
+  return payload as TelnyxMessagePayload;
+}
+
+export function parseTelnyxWebhook(rawBody: string): TelnyxWebhookEvent {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    throw new TelnyxProviderError("Telnyx webhook body is not JSON", 0);
+  }
+  if (typeof parsed !== "object" || parsed === null) throw new TelnyxProviderError("Telnyx webhook body is invalid", 0);
+  const data = (parsed as { data?: unknown }).data;
+  if (typeof data !== "object" || data === null) throw new TelnyxProviderError("Telnyx webhook data is missing", 0);
+  const event = data as { event_type?: unknown; id?: unknown; occurred_at?: unknown; payload?: unknown };
+  if (typeof event.event_type !== "string" || !EVENT_TYPES.has(event.event_type as TelnyxEventType)) {
+    throw new TelnyxProviderError("Telnyx webhook event type is unsupported", 0);
+  }
+  if (typeof event.id !== "string") throw new TelnyxProviderError("Telnyx webhook event id is missing", 0);
+  return {
+    event_type: event.event_type as TelnyxEventType,
+    id: event.id,
+    occurred_at: typeof event.occurred_at === "string" ? event.occurred_at : undefined,
+    payload: parseMessagePayload(event.payload),
+  };
+}
+
+function decodeBase64(value: string): Uint8Array {
+  return new Uint8Array(Buffer.from(value, "base64"));
+}
+
+export async function sendTelnyxSms(input: {
+  apiKey?: string;
+  baseUrl?: string;
+  fetcher?: typeof fetch;
+  message: TelnyxSendInput;
+}): Promise<TelnyxSendResult> {
+  const apiKey = input.apiKey?.trim() ?? "";
+  if (!apiKey) throw new TelnyxProviderError("TELNYX_API_KEY is not set", 0);
+  const baseUrl = (input.baseUrl ?? "https://api.telnyx.com/v2").replace(/\/+$/, "");
+  const fetcher = input.fetcher ?? ((...args: Parameters<typeof fetch>) => fetch(...args));
+  const from = requireE164(input.message.from, "from");
+  const to = requireE164(input.message.to, "to");
+  if (!input.message.text.trim()) throw new TelnyxProviderError("Message text is required", 0);
+  if (input.message.text.length > 1600) throw new TelnyxProviderError("Message text is too long", 0);
+
+  const response = await fetcher(`${baseUrl}/messages`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ ...input.message, from, to }),
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new TelnyxProviderError(`Telnyx send failed (${response.status})${detail ? `: ${detail.slice(0, 300)}` : ""}`, response.status);
+  }
+  const body = (await response.json()) as { data?: { id?: unknown; to?: Array<{ status?: unknown }> } };
+  if (typeof body.data?.id !== "string") throw new TelnyxProviderError("Telnyx send response has no message id", response.status);
+  const status = body.data?.to?.[0]?.status;
+  return { id: body.data.id, status: typeof status === "string" ? status : "queued" };
+}
+
+export function verifyTelnyxWebhook(input: {
+  rawBody: string;
+  headers: Record<string, string>;
+  publicKey?: string;
+  now?: number;
+}): TelnyxWebhookEvent | null {
+  const timestamp = Number(input.headers["telnyx-timestamp"]);
+  const signature = input.headers["telnyx-signature-ed25519"];
+  const publicKey = input.publicKey?.trim() ?? "";
+  const now = input.now ?? Date.now();
+  if (!timestamp || !signature || !publicKey) return null;
+  if (Math.abs(now - timestamp * 1000) > MAX_WEBHOOK_AGE_MS) return null;
+  try {
+    const message = new TextEncoder().encode(`${timestamp}|${input.rawBody}`);
+    const valid = nacl.sign.detached.verify(message, decodeBase64(signature), decodeBase64(publicKey));
+    return valid ? parseTelnyxWebhook(input.rawBody) : null;
+  } catch {
+    return null;
+  }
+}

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@listeningkit/telnyx",
+  "version": "0.1.0",
+  "description": "Production Convex component for Telnyx. Send SMS, verify Ed25519-signed webhooks, and keep every message idempotent through one typed API.",
+  "keywords": [
+    "convex",
+    "convex-component",
+    "telnyx",
+    "sms",
+    "messaging",
+    "webhooks",
+    "ed25519",
+    "idempotency",
+    "a2p",
+    "10dlc"
+  ],
+  "homepage": "https://github.com/matthewdonsemail-lab/convex-telnyx#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/matthewdonsemail-lab/convex-telnyx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/matthewdonsemail-lab/convex-telnyx/issues"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "ListeningKit",
+    "url": "https://listeningkit.ai"
+  },
+  "maintainers": [
+    {
+      "name": "matthewdonse",
+      "email": "matthewdonsemail@gmail.com"
+    }
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "main": "./dist/client.js",
+  "types": "./dist/client.d.ts",
+  "files": [
+    "dist",
+    "convex.config.ts",
+    "schema.ts",
+    "telnyx.ts",
+    "client.ts",
+    "test.ts",
+    "lib/telnyx.ts",
+    "banner.png",
+    "README.md"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./convex.config": {
+      "types": "./dist/convex.config.d.ts",
+      "default": "./dist/convex.config.js"
+    },
+    "./convex.config.js": {
+      "types": "./dist/convex.config.d.ts",
+      "default": "./dist/convex.config.js"
+    },
+    "./_generated/component.js": {
+      "types": "./dist/_generated/component.d.ts"
+    },
+    "./_generated/component": {
+      "types": "./dist/_generated/component.d.ts"
+    },
+    "./test": "./test.ts"
+  },
+  "scripts": {
+    "build": "tsc --build ./tsconfig.build.json --force",
+    "build:clean": "rm -rf dist && npm run build",
+    "build:codegen": "convex codegen --component-dir ./",
+    "typecheck": "tsc --noEmit --skipLibCheck",
+    "test": "vitest run",
+    "prepare": "npm run build"
+  },
+  "peerDependencies": {
+    "convex": ">=1.45.0"
+  },
+  "dependencies": {
+    "tweetnacl": "^1.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "convex": "^1.46.0",
+    "convex-test": "^0.0.60",
+    "typescript": "^5.6.3",
+    "vite": "^8.3.1",
+    "vitest": "^5.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schema.ts

@@ -0,0 +1,25 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  messages: defineTable({
+    owner: v.string(),
+    providerMessageId: v.string(),
+    to: v.string(),
+    text: v.string(),
+    status: v.string(),
+    createdAt: v.number(),
+  })
+    .index("by_owner", ["owner"])
+    .index("by_provider_message", ["providerMessageId"]),
+
+  webhookEvents: defineTable({
+    eventId: v.string(),
+    eventType: v.string(),
+    payload: v.any(),
+    occurredAt: v.optional(v.string()),
+    receivedAt: v.number(),
+  })
+    .index("by_event", ["eventId"])
+    .index("by_received", ["receivedAt"]),
+});

package/telnyx.ts

@@ -0,0 +1,182 @@
+import { ConvexError, v } from "convex/values";
+import { action, env, internalMutation, query } from "./_generated/server.js";
+import { internal } from "./_generated/api.js";
+import {
+  sendTelnyxSms,
+  verifyTelnyxWebhook,
+  type TelnyxSendResult,
+  type TelnyxWebhookEvent,
+} from "./lib/telnyx.js";
+
+const messageRow = v.object({
+  _id: v.string(),
+  _creationTime: v.number(),
+  owner: v.string(),
+  providerMessageId: v.string(),
+  to: v.string(),
+  text: v.string(),
+  status: v.string(),
+  createdAt: v.number(),
+});
+
+const webhookEventRow = v.object({
+  _id: v.string(),
+  _creationTime: v.number(),
+  eventId: v.string(),
+  eventType: v.string(),
+  payload: v.any(),
+  occurredAt: v.optional(v.string()),
+  receivedAt: v.number(),
+});
+
+const webhookEvent = v.union(
+  v.null(),
+  v.object({
+    event_type: v.string(),
+    id: v.string(),
+    occurred_at: v.optional(v.string()),
+    payload: v.any(),
+  }),
+);
+
+/**
+ * Send an SMS through `POST /v2/messages` and record it in the component's
+ * isolated `messages` table, keyed by the Telnyx message id so a retried send
+ * never double-logs.
+ *
+ * Auth lives in the app: components have no `ctx.auth`, so the caller passes
+ * its already-verified owner string. The API key and default sender number
+ * come only from the component's declared env, never from arguments.
+ */
+export const sendSms = action({
+  args: {
+    owner: v.string(),
+    from: v.optional(v.string()),
+    to: v.string(),
+    text: v.string(),
+    webhookUrl: v.optional(v.string()),
+  },
+  returns: v.object({ id: v.string(), status: v.string() }),
+  handler: async (ctx, args): Promise<TelnyxSendResult> => {
+    const from = args.from ?? env.TELNYX_FROM_NUMBER;
+    if (!from) throw new ConvexError("TELNYX_FROM_NUMBER is not configured");
+    const result = await sendTelnyxSms({
+      apiKey: env.TELNYX_API_KEY,
+      baseUrl: env.TELNYX_API_BASE_URL,
+      message: {
+        from,
+        to: args.to,
+        text: args.text,
+        ...(args.webhookUrl ? { webhook_url: args.webhookUrl } : {}),
+      },
+    });
+    await ctx.runMutation(internal.telnyx.recordMessage, {
+      owner: args.owner,
+      providerMessageId: result.id,
+      to: args.to,
+      text: args.text,
+      status: result.status,
+      createdAt: Date.now(),
+    });
+    return result;
+  },
+});
+
+/**
+ * Verify an Ed25519-signed Telnyx webhook against the exact raw body and store
+ * the event once by Telnyx event id. Returns `null` for an invalid signature,
+ * a stale timestamp, or an unparseable body, so the host can answer 401 and
+ * let Telnyx retry.
+ */
+export const verifyWebhook = action({
+  args: {
+    rawBody: v.string(),
+    headers: v.record(v.string(), v.string()),
+  },
+  returns: webhookEvent,
+  handler: async (ctx, args): Promise<TelnyxWebhookEvent | null> => {
+    const event = verifyTelnyxWebhook({
+      rawBody: args.rawBody,
+      headers: args.headers,
+      publicKey: env.TELNYX_PUBLIC_KEY,
+    });
+    if (!event) return null;
+    await ctx.runMutation(internal.telnyx.recordWebhook, {
+      eventId: event.id,
+      eventType: event.event_type,
+      payload: event,
+      occurredAt: event.occurred_at,
+      receivedAt: Date.now(),
+    });
+    return event;
+  },
+});
+
+/** Insert a sent message. Idempotent on `providerMessageId`. Internal: not part of the host-facing API. */
+export const recordMessage = internalMutation({
+  args: {
+    owner: v.string(),
+    providerMessageId: v.string(),
+    to: v.string(),
+    text: v.string(),
+    status: v.string(),
+    createdAt: v.number(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("messages")
+      .withIndex("by_provider_message", (q) => q.eq("providerMessageId", args.providerMessageId))
+      .first();
+    if (existing) return null;
+    await ctx.db.insert("messages", args);
+    return null;
+  },
+});
+
+/** Insert a verified webhook event. Idempotent on `eventId`. Internal: not part of the host-facing API. */
+export const recordWebhook = internalMutation({
+  args: {
+    eventId: v.string(),
+    eventType: v.string(),
+    payload: v.any(),
+    occurredAt: v.optional(v.string()),
+    receivedAt: v.number(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("webhookEvents")
+      .withIndex("by_event", (q) => q.eq("eventId", args.eventId))
+      .first();
+    if (existing) return null;
+    await ctx.db.insert("webhookEvents", args);
+    return null;
+  },
+});
+
+/** List an owner's most recent messages, newest first. */
+export const listMessages = query({
+  args: { owner: v.string(), limit: v.optional(v.number()) },
+  returns: v.array(messageRow),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("messages")
+      .withIndex("by_owner", (q) => q.eq("owner", args.owner))
+      .order("desc")
+      .take(args.limit ?? 50);
+  },
+});
+
+/** List the most recently received verified webhook events, newest first. */
+export const listWebhookEvents = query({
+  args: { limit: v.optional(v.number()) },
+  returns: v.array(webhookEventRow),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("webhookEvents")
+      .withIndex("by_received", (q) => q.gte("receivedAt", 0))
+      .order("desc")
+      .take(args.limit ?? 50);
+  },
+});

package/test.ts

@@ -0,0 +1,35 @@
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import * as telnyxFunctions from "./telnyx.js";
+import * as generatedApi from "./_generated/api.js";
+import * as generatedServer from "./_generated/server.js";
+import schema from "./schema.js";
+
+/**
+ * The component's function modules, for `convex-test`.
+ *
+ * Declared statically rather than with `import.meta.glob` so the Convex
+ * analyzer can bundle this directory: `import.meta` is not available in the
+ * Convex runtime. The `_generated` entries are required by `convex-test` to
+ * locate the modules root.
+ */
+export const modules: Record<string, () => Promise<unknown>> = {
+  "./telnyx.ts": async () => telnyxFunctions,
+  "./_generated/api.ts": async () => generatedApi,
+  "./_generated/server.ts": async () => generatedServer,
+};
+
+/**
+ * Register the component with the test convex instance.
+ *
+ * @param t The test convex instance, e.g. from calling `convexTest`.
+ * @param name The name of the component, as registered in `convex.config.ts`.
+ */
+export function register(
+  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name: string = "telnyx",
+) {
+  t.registerComponent(name, schema, modules);
+}
+
+export default { register, schema, modules };