@stribley/comms

Attribution wrapper for outbound email (Resend), SMS (Twilio) and push (Expo) that reports every send to the Stribley Comms Hub. Zero runtime dependencies. CJS + ESM + types.

It adds three things a provider webhook can never tell you: which app sent the message, which template it was, and the rendered body as the recipient will see it. It never throws on a hub failure, bounds every hub call with a short timeout, and returns the provider SDK's own result untouched, so adopting it is a wrapper change, not a behaviour change.

Install

pnpm add @stribley/comms

Use

import { createComms } from "@stribley/comms";
import { Resend } from "resend";
import twilio from "twilio";

const comms = createComms({
  app: "sitedesk",              // shows as the `app` column in the hub feed
  venture: "boo",               // 'boo' | 'ranges' | 'ow' | 'clynr'
  hubUrl: process.env.COMMS_HUB_URL!,
  hubToken: process.env.COMMS_HUB_INGEST_TOKEN!,
  resend: new Resend(process.env.RESEND_API_KEY),
  twilio: twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN),
  expoAccessToken: process.env.EXPO_ACCESS_TOKEN,
});

await comms.sendEmail({
  to: "[email protected]",
  from: "Bolt On Ops <[email protected]>",
  subject: "Your invite",
  html,
  templateKey: "invite",
  entityRefs: { projectId: 42 },
});

await comms.sendSms({ to: "+61400000000", body: "On our way", templateKey: "eta" });
await comms.sendPush({ tokens, title: "Job assigned", body: "See details" });

Every result is { ok, id, error, correlationId, raw }. ok reflects the provider only; hub reporting never affects it. raw is the provider SDK's untouched response.

Options

| Option | Meaning | |---|---| | timeoutMs | Cap on each hub call. Short by default; the hub must never slow a send. | | waitForHub | Await the hub post. Keep true on Vercel, Lambda and other serverless hosts. Set false only in a long-lived server. | | onError | Called when a hub report fails. Silent by default. Never throws. | | suppressionCheck | Ask the hub whether the recipient is suppressed before sending. Default true. The check fails open — a slow or unreachable hub sends anyway — so leaving it on cannot break a send. Set false only where the repo already enforces its own suppression list. |

Repos that cannot take the SDK still get attribution by adding Resend tags (app, template_key, cid) or a Twilio statusCallback; see the hub's docs/PLAN.md.

Suppression

A hard bounce, a spam complaint or an Expo DeviceNotRegistered writes a row on the hub's suppression list, scoped to one venture: an address that died on a Ranges reminder has not opted out of an Oscar White invoice.

From 0.2.0 every sendEmail, sendSms and sendPush asks the hub about the recipient before calling the provider. When the hub says the recipient is suppressed:

• no provider call is made;
• one row is reported with status suppressed, so the refusal is visible in the feed rather than being an email that silently never happened;
• the result is { ok: true, suppressed: true } and carries no id.

ok stays true because nothing went wrong. Adopting repos guard on ok and throw when it is false, so reporting a correct refusal as a failure would turn suppression into an exception in the middle of a client's booking.

A push to several devices drops only the dead tokens. The live devices in the same batch still get the notification.

The check fails open. A timeout, a 500, a 401, a hub mid-deploy or no network at all all mean "send it". The hub is an observer, and a monitoring outage must never become a business outage. The cost is that a dead address may get one more message during an outage; the cost of the alternative is a client not hearing from us at all, which nobody notices until they complain.