@christian-ek/sweego 0.1.0

package/src/component/schema.ts

@@ -0,0 +1,117 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+import {
+  onEvent,
+  vAttachment,
+  vChannel,
+  vDeliveryStatus,
+  vEmailAddress,
+  vEmailRecipient,
+  vListUnsub,
+  vSendStatus,
+  vSmsRecipient,
+  vVariables,
+} from "./shared.js";
+
+export default defineSchema({
+  // A logical send request. One row per `sendEmail` / `sendSms` / `sendBulkEmail`
+  // call. Content is stored inline; the whole document must fit within Convex's
+  // ~1 MiB limit (so keep attachments small).
+  messages: defineTable({
+    channel: vChannel,
+    provider: v.string(),
+    status: vSendStatus,
+    bulk: v.boolean(),
+
+    // Recipients (per channel).
+    emailRecipients: v.optional(v.array(vEmailRecipient)),
+    smsRecipients: v.optional(v.array(vSmsRecipient)),
+
+    // Email fields.
+    from: v.optional(vEmailAddress),
+    subject: v.optional(v.string()),
+    cc: v.optional(v.array(vEmailAddress)),
+    bcc: v.optional(v.array(vEmailAddress)),
+    replyTo: v.optional(vEmailAddress),
+    html: v.optional(v.string()),
+    text: v.optional(v.string()),
+    templateId: v.optional(v.string()),
+    variables: v.optional(vVariables),
+    attachments: v.optional(v.array(vAttachment)),
+    headers: v.optional(v.record(v.string(), v.string())),
+    listUnsub: v.optional(vListUnsub),
+    expires: v.optional(v.string()),
+    campaignId: v.optional(v.string()),
+    campaignTags: v.optional(v.array(v.string())),
+    campaignType: v.optional(v.string()),
+    compressStyle: v.optional(v.boolean()),
+    forceInlineStyle: v.optional(v.boolean()),
+    dryRun: v.optional(v.boolean()),
+
+    // SMS fields.
+    senderId: v.optional(v.string()),
+    shortenUrls: v.optional(v.boolean()),
+    shortenWithProtocol: v.optional(v.boolean()),
+    bat: v.optional(v.boolean()),
+
+    // Lifecycle.
+    transactionId: v.optional(v.string()),
+    errorMessage: v.optional(v.string()),
+    creditLeft: v.optional(v.string()),
+    finalizedAt: v.number(),
+  })
+    .index("by_status", ["status"])
+    .index("by_finalizedAt", ["finalizedAt"])
+    .index("by_transactionId", ["transactionId"]),
+
+  // One row per recipient (per swg_uid returned by Sweego). Webhook events are
+  // matched to a delivery via `swgUid`.
+  deliveries: defineTable({
+    messageId: v.id("messages"),
+    swgUid: v.string(),
+    recipientKey: v.string(),
+    channel: vChannel,
+    status: vDeliveryStatus,
+    lastEventType: v.optional(v.string()),
+    delivered: v.boolean(),
+    bounced: v.boolean(),
+    softBounced: v.boolean(),
+    complained: v.boolean(),
+    unsubscribed: v.boolean(),
+    opened: v.boolean(),
+    clicked: v.boolean(),
+    stopped: v.boolean(),
+    errorMessage: v.optional(v.string()),
+    finalizedAt: v.number(),
+  })
+    .index("by_swgUid", ["swgUid"])
+    .index("by_messageId", ["messageId"]),
+
+  // Raw webhook events, kept for auditing/debugging.
+  events: defineTable({
+    swgUid: v.string(),
+    messageId: v.optional(v.id("messages")),
+    deliveryId: v.optional(v.id("deliveries")),
+    channel: v.optional(vChannel),
+    eventType: v.string(),
+    // The `webhook-id` header (Standard-Webhooks message id) — used to
+    // deduplicate redelivered/replayed webhooks.
+    webhookId: v.optional(v.string()),
+    eventId: v.optional(v.string()),
+    transactionId: v.optional(v.string()),
+    timestamp: v.optional(v.string()),
+    payload: v.any(),
+    createdAt: v.number(),
+  })
+    .index("by_swgUid", ["swgUid"])
+    .index("by_messageId", ["messageId"])
+    .index("by_webhookId", ["webhookId"])
+    .index("by_createdAt", ["createdAt"]),
+
+  // Singleton row holding the latest webhook-event callback handle, refreshed
+  // whenever a message is enqueued. The webhook handler reads it to dispatch
+  // `onEvent` (which arrives independently of any send).
+  config: defineTable({
+    onEvent: v.optional(onEvent),
+  }),
+});

package/src/component/shared.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import {
+  classifyEvent,
+  normalizeEventType,
+  parseEmailAddress,
+  parseEmailAddresses,
+} from "./shared.js";
+
+describe("classifyEvent", () => {
+  it("classifies email events regardless of hyphen/underscore casing", () => {
+    expect(classifyEvent("email_sent")).toBe("sent");
+    expect(classifyEvent("delivered")).toBe("delivered");
+    expect(classifyEvent("soft-bounce")).toBe("soft_bounce");
+    expect(classifyEvent("hard_bounce")).toBe("hard_bounce");
+    expect(classifyEvent("complaint")).toBe("complaint");
+    expect(classifyEvent("list_unsub")).toBe("unsub");
+    expect(classifyEvent("email_opened")).toBe("open");
+    expect(classifyEvent("email_clicked")).toBe("click");
+    expect(classifyEvent("email_inbound")).toBe("inbound");
+  });
+
+  it("classifies SMS events including the stop/sms_stop variants", () => {
+    expect(classifyEvent("sms_sent")).toBe("sms_sent");
+    expect(classifyEvent("sms_undelivered")).toBe("sms_undelivered");
+    expect(classifyEvent("sms_stop")).toBe("sms_stop");
+    expect(classifyEvent("stop")).toBe("sms_stop");
+    expect(classifyEvent("sms_clicked")).toBe("sms_click");
+  });
+
+  it("returns unknown for unrecognized strings", () => {
+    expect(classifyEvent("totally_made_up")).toBe("unknown");
+  });
+
+  it("normalizes case and hyphens", () => {
+    expect(normalizeEventType("Soft-Bounce")).toBe("soft_bounce");
+  });
+});
+
+describe("parseEmailAddress", () => {
+  it('parses "Name <email>"', () => {
+    expect(parseEmailAddress("Acme <hi@acme.com>")).toEqual({
+      email: "hi@acme.com",
+      name: "Acme",
+    });
+  });
+
+  it("parses a bare email", () => {
+    expect(parseEmailAddress("hi@acme.com")).toEqual({ email: "hi@acme.com" });
+  });
+
+  it("passes structured addresses through", () => {
+    expect(parseEmailAddress({ email: "x@y.com", name: "X" })).toEqual({
+      email: "x@y.com",
+      name: "X",
+    });
+  });
+
+  it("parses arrays and strips quotes from names", () => {
+    expect(parseEmailAddresses(['"Cara" <c@d.com>', "a@b.com"])).toEqual([
+      { email: "c@d.com", name: "Cara" },
+      { email: "a@b.com" },
+    ]);
+  });
+});

package/src/component/shared.ts

@@ -0,0 +1,315 @@
+import {
+  type GenericActionCtx,
+  type GenericDataModel,
+  type GenericMutationCtx,
+  type GenericQueryCtx,
+} from "convex/server";
+import { type Infer, v } from "convex/values";
+
+// The Sweego API base URL. All requests go here.
+export const SWEEGO_API_BASE_URL = "https://api.sweego.io";
+
+// The default provider Sweego expects on every send request.
+export const DEFAULT_PROVIDER = "sweego";
+
+/* -------------------------------------------------------------------------- */
+/*  Channels                                                                  */
+/* -------------------------------------------------------------------------- */
+
+export const vChannel = v.union(v.literal("email"), v.literal("sms"));
+export type Channel = Infer<typeof vChannel>;
+
+/* -------------------------------------------------------------------------- */
+/*  Addresses / recipients                                                    */
+/* -------------------------------------------------------------------------- */
+
+// An email address with an optional display name, e.g. { email, name }.
+export const vEmailAddress = v.object({
+  email: v.string(),
+  name: v.optional(v.string()),
+});
+export type EmailAddress = Infer<typeof vEmailAddress>;
+
+// Variables passed to a Sweego template. Values are interpolated into
+// `{{ placeholder }}` tokens; Sweego accepts string/number/boolean values.
+export const vVariables = v.record(
+  v.string(),
+  v.union(v.string(), v.number(), v.boolean()),
+);
+export type Variables = Infer<typeof vVariables>;
+
+// An email recipient. `variables` is only honored on the bulk endpoint
+// (`/send/bulk/email`), where each recipient may be personalized.
+export const vEmailRecipient = v.object({
+  email: v.string(),
+  name: v.optional(v.string()),
+  variables: v.optional(vVariables),
+});
+export type EmailRecipient = Infer<typeof vEmailRecipient>;
+
+// An SMS recipient: a phone number plus its ISO-3166 alpha-2 region (e.g. "FR").
+export const vSmsRecipient = v.object({
+  num: v.string(),
+  region: v.string(),
+});
+export type SmsRecipient = Infer<typeof vSmsRecipient>;
+
+/* -------------------------------------------------------------------------- */
+/*  Email extras                                                              */
+/* -------------------------------------------------------------------------- */
+
+// A file attachment. `content` MUST be base64-encoded bytes. The total
+// message (incl. attachments) must fit within a single Convex document
+// (~1 MiB); use small attachments or host large files elsewhere.
+export const vAttachment = v.object({
+  content: v.string(),
+  filename: v.string(),
+  contentId: v.optional(v.string()),
+  disposition: v.optional(
+    v.union(v.literal("attachment"), v.literal("inline")),
+  ),
+  isRelated: v.optional(v.boolean()),
+});
+export type Attachment = Infer<typeof vAttachment>;
+
+// The List-Unsubscribe header. For "mailto", `value` is an email; for
+// "one-click", `value` is "<mailto:EMAIL>,<URL>".
+export const vListUnsub = v.object({
+  method: v.optional(v.union(v.literal("mailto"), v.literal("one-click"))),
+  value: v.string(),
+});
+export type ListUnsub = Infer<typeof vListUnsub>;
+
+// Email campaign type. Optional for email.
+export const vEmailCampaignType = v.union(
+  v.literal("market"),
+  v.literal("newsletter"),
+  v.literal("transac"),
+);
+
+// SMS campaign type. REQUIRED by Sweego for every SMS send.
+export const vSmsCampaignType = v.union(
+  v.literal("market"),
+  v.literal("transac"),
+);
+export type SmsCampaignType = Infer<typeof vSmsCampaignType>;
+
+/* -------------------------------------------------------------------------- */
+/*  Statuses                                                                  */
+/* -------------------------------------------------------------------------- */
+
+// Lifecycle of a logical send (one `messages` row).
+export const vSendStatus = v.union(
+  v.literal("queued"), // enqueued, not yet handed to Sweego
+  v.literal("sent"), // accepted by Sweego (swg_uids issued)
+  v.literal("failed"), // permanent failure / retries exhausted
+  v.literal("cancelled"), // cancelled before being sent
+);
+export type SendStatus = Infer<typeof vSendStatus>;
+
+// Per-recipient delivery outcome (one `deliveries` row per swg_uid).
+export const vDeliveryStatus = v.union(
+  v.literal("pending"), // accepted, awaiting delivery events
+  v.literal("sent"),
+  v.literal("delivered"),
+  v.literal("soft_bounced"), // transient bounce, may still deliver
+  v.literal("bounced"), // hard bounce (terminal)
+  v.literal("undelivered"), // SMS not delivered (terminal)
+  v.literal("stopped"), // SMS recipient opted out (terminal)
+);
+export type DeliveryStatus = Infer<typeof vDeliveryStatus>;
+
+/* -------------------------------------------------------------------------- */
+/*  Webhook events                                                            */
+/* -------------------------------------------------------------------------- */
+
+// Known Sweego email webhook event_type strings. Casing is inconsistent in
+// Sweego's docs (e.g. "soft-bounce" vs "hard_bounce"), so we match defensively
+// via `classifyEvent` rather than relying on these literally.
+export const KNOWN_EMAIL_EVENT_TYPES = [
+  "email_sent",
+  "delivered",
+  "soft-bounce",
+  "hard_bounce",
+  "list_unsub",
+  "complaint",
+  "email_opened",
+  "email_clicked",
+  "email_inbound",
+] as const;
+
+export const KNOWN_SMS_EVENT_TYPES = [
+  "sms_sent",
+  "sms_undelivered",
+  "sms_stop",
+  "sms_clicked",
+] as const;
+
+// A normalized webhook event handed to your `onEvent` handler. The raw,
+// unmodified payload is always available on `raw`.
+export const vSweegoEvent = v.object({
+  eventType: v.string(),
+  channel: v.optional(vChannel),
+  swgUid: v.string(),
+  eventId: v.optional(v.string()),
+  transactionId: v.optional(v.string()),
+  timestamp: v.optional(v.string()),
+  raw: v.any(),
+});
+export type SweegoEvent = Infer<typeof vSweegoEvent>;
+
+// Coarse classification of a Sweego event_type string, normalizing the
+// documented hyphen/underscore inconsistencies (and the sms_stop/stop variant).
+export type EventKind =
+  | "sent"
+  | "delivered"
+  | "soft_bounce"
+  | "hard_bounce"
+  | "complaint"
+  | "unsub"
+  | "open"
+  | "click"
+  | "sms_sent"
+  | "sms_undelivered"
+  | "sms_stop"
+  | "sms_click"
+  | "inbound"
+  | "unknown";
+
+export function normalizeEventType(raw: string): string {
+  return raw.trim().toLowerCase().replace(/-/g, "_");
+}
+
+export function classifyEvent(raw: string): EventKind {
+  switch (normalizeEventType(raw)) {
+    case "email_sent":
+      return "sent";
+    case "delivered":
+      return "delivered";
+    case "soft_bounce":
+      return "soft_bounce";
+    case "hard_bounce":
+    case "bounce":
+      return "hard_bounce";
+    case "complaint":
+      return "complaint";
+    case "list_unsub":
+      return "unsub";
+    case "email_opened":
+      return "open";
+    case "email_clicked":
+      return "click";
+    case "email_inbound":
+      return "inbound";
+    case "sms_sent":
+      return "sms_sent";
+    case "sms_undelivered":
+      return "sms_undelivered";
+    case "sms_stop":
+    case "stop":
+      return "sms_stop";
+    case "sms_clicked":
+      return "sms_click";
+    default:
+      return "unknown";
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Runtime configuration                                                     */
+/* -------------------------------------------------------------------------- */
+
+// A reference to a mutation in the host app that runs after each event.
+export const onEvent = v.object({ fnHandle: v.string() });
+
+// Runtime configuration threaded from the client into the component on each
+// send. Note: components cannot read the host app's environment variables, so
+// the API key is passed in explicitly here.
+export const vOptions = v.object({
+  apiKey: v.string(),
+  provider: v.string(),
+  initialBackoffMs: v.number(),
+  retryAttempts: v.number(),
+  // When true, email sends use Sweego's `dry-run` (validated, never sent).
+  testMode: v.boolean(),
+  onEvent: v.optional(onEvent),
+});
+export type RuntimeConfig = Infer<typeof vOptions>;
+
+/* -------------------------------------------------------------------------- */
+/*  Message input (client -> component)                                       */
+/* -------------------------------------------------------------------------- */
+
+// The normalized message a client hands to the component's `enqueueMessage`
+// mutation. Lifecycle fields (status, transactionId, finalizedAt, …) are added
+// by the component, not provided here.
+export const vMessageInput = v.object({
+  channel: vChannel,
+  bulk: v.boolean(),
+  emailRecipients: v.optional(v.array(vEmailRecipient)),
+  smsRecipients: v.optional(v.array(vSmsRecipient)),
+  from: v.optional(vEmailAddress),
+  subject: v.optional(v.string()),
+  cc: v.optional(v.array(vEmailAddress)),
+  bcc: v.optional(v.array(vEmailAddress)),
+  replyTo: v.optional(vEmailAddress),
+  html: v.optional(v.string()),
+  text: v.optional(v.string()),
+  templateId: v.optional(v.string()),
+  variables: v.optional(vVariables),
+  attachments: v.optional(v.array(vAttachment)),
+  headers: v.optional(v.record(v.string(), v.string())),
+  listUnsub: v.optional(vListUnsub),
+  expires: v.optional(v.string()),
+  campaignId: v.optional(v.string()),
+  campaignTags: v.optional(v.array(v.string())),
+  campaignType: v.optional(v.string()),
+  compressStyle: v.optional(v.boolean()),
+  forceInlineStyle: v.optional(v.boolean()),
+  dryRun: v.optional(v.boolean()),
+  senderId: v.optional(v.string()),
+  shortenUrls: v.optional(v.boolean()),
+  shortenWithProtocol: v.optional(v.boolean()),
+  bat: v.optional(v.boolean()),
+});
+export type MessageInput = Infer<typeof vMessageInput>;
+
+/* -------------------------------------------------------------------------- */
+/*  Helpers                                                                   */
+/* -------------------------------------------------------------------------- */
+
+// Accepts either a structured address or an RFC-5322-ish "Name <email>" /
+// "email" string and returns { email, name? }.
+export function parseEmailAddress(
+  input: string | EmailAddress,
+): EmailAddress {
+  if (typeof input !== "string") return input;
+  const match = input.match(/^\s*(.*?)\s*<\s*([^>]+)\s*>\s*$/);
+  if (match) {
+    const name = match[1].replace(/^["']|["']$/g, "").trim();
+    const email = match[2].trim();
+    return name ? { email, name } : { email };
+  }
+  return { email: input.trim() };
+}
+
+export function parseEmailAddresses(
+  input: string | EmailAddress | Array<string | EmailAddress>,
+): EmailAddress[] {
+  const list = Array.isArray(input) ? input : [input];
+  return list.map(parseEmailAddress);
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Ctx type utilities                                                        */
+/* -------------------------------------------------------------------------- */
+
+export type QueryCtx = Pick<GenericQueryCtx<GenericDataModel>, "runQuery">;
+export type MutationCtx = Pick<
+  GenericMutationCtx<GenericDataModel>,
+  "runQuery" | "runMutation"
+>;
+export type ActionCtx = Pick<
+  GenericActionCtx<GenericDataModel>,
+  "runQuery" | "runMutation" | "runAction"
+>;

package/src/component/sweego.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, it } from "vitest";
+import {
+  type BuildableMessage,
+  buildSendRequest,
+  PERMANENT_ERROR_CODES,
+  parseSendResponse,
+  sanitizeSweegoError,
+} from "./sweego.js";
+
+const baseEmail: BuildableMessage = {
+  channel: "email",
+  provider: "sweego",
+  bulk: false,
+  from: { email: "a@x.com", name: "A" },
+  subject: "Hi",
+  emailRecipients: [{ email: "b@y.com" }],
+  html: "<p>hi</p>",
+};
+
+describe("buildSendRequest (email)", () => {
+  it("uses /send and hyphenated keys, dropping undefined fields", () => {
+    const { path, body } = buildSendRequest(baseEmail);
+    expect(path).toBe("/send");
+    expect(body.channel).toBe("email");
+    expect(body.provider).toBe("sweego");
+    expect(body["message-html"]).toBe("<p>hi</p>");
+    expect(body.subject).toBe("Hi");
+    expect(body.recipients).toEqual([{ email: "b@y.com" }]);
+    expect(body.from).toEqual({ email: "a@x.com", name: "A" });
+    expect("message-txt" in body).toBe(false);
+    expect("dry-run" in body).toBe(false);
+  });
+
+  it("maps attachments to Sweego's snake_case fields", () => {
+    const { body } = buildSendRequest({
+      ...baseEmail,
+      attachments: [
+        {
+          content: "Zm9v",
+          filename: "f.txt",
+          contentId: "cid",
+          disposition: "inline",
+          isRelated: true,
+        },
+      ],
+    });
+    expect(body.attachments).toEqual([
+      {
+        content: "Zm9v",
+        filename: "f.txt",
+        content_id: "cid",
+        disposition: "inline",
+        is_related: true,
+      },
+    ]);
+  });
+
+  it("includes dry-run when set", () => {
+    const { body } = buildSendRequest({ ...baseEmail, dryRun: true });
+    expect(body["dry-run"]).toBe(true);
+  });
+});
+
+describe("buildSendRequest (bulk email)", () => {
+  it("routes to /send/bulk/email with per-recipient variables and no cc", () => {
+    const { path, body } = buildSendRequest({
+      ...baseEmail,
+      bulk: true,
+      html: undefined,
+      templateId: "tmpl-1",
+      emailRecipients: [
+        { email: "b@y.com", variables: { name: "Bob" } },
+        { email: "c@y.com", variables: { name: "Cara" } },
+      ],
+    });
+    expect(path).toBe("/send/bulk/email");
+    expect(body["template-id"]).toBe("tmpl-1");
+    expect((body.recipients as Array<Record<string, unknown>>)[0]).toEqual({
+      email: "b@y.com",
+      variables: { name: "Bob" },
+    });
+    expect("cc" in body).toBe(false);
+  });
+});
+
+describe("buildSendRequest (sms)", () => {
+  it("builds an SMS payload with required campaign-type and sender-id", () => {
+    const { path, body } = buildSendRequest({
+      channel: "sms",
+      provider: "sweego",
+      bulk: false,
+      smsRecipients: [{ num: "+33600000000", region: "FR" }],
+      text: "hi",
+      campaignType: "transac",
+      senderId: "Acme",
+      shortenUrls: false,
+    });
+    expect(path).toBe("/send");
+    expect(body.channel).toBe("sms");
+    expect(body["campaign-type"]).toBe("transac");
+    expect(body["sender-id"]).toBe("Acme");
+    expect(body["message-txt"]).toBe("hi");
+    expect(body["shorten-urls"]).toBe(false);
+    expect(body.recipients).toEqual([{ num: "+33600000000", region: "FR" }]);
+  });
+});
+
+describe("parseSendResponse", () => {
+  it("extracts swg_uids, transaction_id, credit_left", () => {
+    const r = parseSendResponse({
+      channel: "email",
+      provider: "sweego",
+      swg_uids: { "b@y.com": "uid1" },
+      transaction_id: "tx1",
+      credit_left: "100",
+    });
+    expect(r.swgUids).toEqual({ "b@y.com": "uid1" });
+    expect(r.transactionId).toBe("tx1");
+    expect(r.creditLeft).toBe("100");
+  });
+
+  it("tolerates a missing/empty body", () => {
+    const r = parseSendResponse({});
+    expect(r.swgUids).toEqual({});
+    expect(r.transactionId).toBeUndefined();
+  });
+});
+
+describe("error classification", () => {
+  it("treats 4xx (422) as permanent, 429/5xx as transient", () => {
+    expect(PERMANENT_ERROR_CODES.has(422)).toBe(true);
+    expect(PERMANENT_ERROR_CODES.has(401)).toBe(true);
+    expect(PERMANENT_ERROR_CODES.has(429)).toBe(false);
+    expect(PERMANENT_ERROR_CODES.has(500)).toBe(false);
+  });
+
+  it("returns friendly messages", () => {
+    expect(sanitizeSweegoError(401, "x")).toMatch(/authentication/i);
+    expect(sanitizeSweegoError(429, "x")).toMatch(/rate limit/i);
+  });
+});