@awsmbiz/inbis-notifications 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,207 @@
-# Temporary Holding Version
+# @awsmbiz/inbis-notifications
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Delivery adapters and templates for Inbis apps. They implement the `EmailSender`, `SmsSender`
+and `AuthEmailTemplates` interfaces from `@awsmbiz/inbis-core`, so other packages (such as
+`@awsmbiz/inbis-auth`) never depend on a provider.
+
+All real email and SMS go through **AWSM's shared communication service**
+(`awsmbiz/biz-cloud-communication-service`), reached over a Cloudflare service binding. The
+service owns quotas, suspension, provider credentials (Cloudflare Email Sending, Chatico) and
+retries; this package does not duplicate them. Log adapters cover local development.
+
+| Export | Contents |
+|---|---|
+| `createCommunicationServiceEmailSender({ binding, appId, from?, replyTo?, smtp? })` | `EmailSender` over the service's `sendEmail`. Returns `{ messageId }` when the service gives one. |
+| `createCommunicationServiceSmsSender({ binding, appId, smsHeader?, templates, requiredTemplates?, formatRecipient? })` | `SmsSender` over the service's `sendSms`. Returns `{ messageId }` (Chatico's message ID, else the submission ID). |
+| `CommunicationServiceBinding`, `communicationServiceBinding(fetcher)` | The service's RPC surface as Inbis uses it (typed structurally; no dependency on the service repo), and a helper that types a `Fetcher` binding as it. |
+| `SmsTemplateConfig`, `SmtpCredentials` | Per-message-type DLT settings; per-app SMTP credentials. |
+| `e164DigitsRecipient` (default), `indianTenDigitRecipient` | Phone number formatters for the service (see below). |
+| `createLogEmailSender({ print?, from?, keep? })` | Development `EmailSender`. Prints every email in full and keeps the most recent `keep` (default 50) in memory for `recent()`. |
+| `createLogSmsSender({ print?, keep? })` | Development `SmsSender` (options type `LogSmsSenderOptions`). Prints every SMS and keeps the most recent `keep` (default 50) for `recent()`. |
+| `EmailDeliveryError`, `SmsDeliveryError` | `AppError`s thrown by the adapters, with `code`, `retryable` (and `providerCode` / `providerStatus`) and the service error as `cause`. |
+| `authEmailTemplates`, `createAuthEmailTemplates(messages?)` | The verification, password-reset and invitation emails, as HTML + plain text. |
+| `renderBrandedEmail(content)` | The branded layout behind those templates, for other emails that have one action button (`content`: a `BrandedEmailContent`). |
+| `emailMessages`, `EmailMessageKey`, `EmailMessages` | Every template string by message key (English only for now). |
+
+Depends only on `@awsmbiz/inbis-core`. Tested in workerd, against a fake binding (the real service is
+never called).
+
+## Setting up the communication service
+
+1. **Bind the service** in each deployed environment of `wrangler.jsonc` (service bindings and
+   vars are not inherited by `env.*`, so repeat them per environment):
+
+   ```jsonc
+   "services": [{ "binding": "COMMUNICATION_SERVICE", "service": "biz-cloud-communication-service" }]
+   ```
+
+   The calling Worker must be in AWSM's Cloudflare account. Keep local development on the log
+   adapters; there is nothing to bind locally.
+2. **`APP_ID`** is set by the platform on every deployed app. Always pass `env.APP_ID` as
+   `appId`; never hardcode it or take it from user input. Both factories throw at startup when
+   it is missing or blank.
+3. **Register the app** with the service before its first send (an AWSM admin, from Command
+   Center): `registerApp(appId, { emailMonthlyQuota, smsMonthlyQuota })`. Until then every send
+   fails with `EMAIL_APP_NOT_REGISTERED` / `SMS_APP_NOT_REGISTERED`.
+4. **Email:** the `from` domain must be onboarded and verified in Cloudflare Email Sending on
+   AWSM's account (else `EMAIL_SENDER_NOT_VERIFIED`).
+5. **SMS:** the SMS quota defaults to `0`, which means SMS is off; ask for it to be raised
+   (`setAppLimits(appId, { smsMonthlyQuota })`). Register the sender header and every SMS
+   template on DLT under AWSM (the registered DLT entity) and configure them per message type
+   (below).
+
+`wrangler types` types a service binding as a plain `Fetcher` unless it can see the service's
+source; wrap it with `communicationServiceBinding(...)`:
+
+```ts
+import { requireBinding } from "@awsmbiz/inbis-cloudflare";
+import { communicationServiceBinding } from "@awsmbiz/inbis-notifications";
+
+const binding = communicationServiceBinding(requireBinding(env, "COMMUNICATION_SERVICE"));
+```
+
+## Email
+
+```ts
+import { createCommunicationServiceEmailSender } from "@awsmbiz/inbis-notifications";
+
+const email = createCommunicationServiceEmailSender({
+  binding,
+  appId: env.APP_ID,
+  from: "no-reply@billing.example.com", // default; a message's own `from` wins
+});
+```
+
+- **Metered path (default):** AWSM's Cloudflare Email Sending, counted against the app's
+  monthly email quota and retried by the service on delivery failure. It takes only plain-string
+  addresses: `from`, one recipient, an optional reply-to (sent as `reply`), `subject`, `text`
+  and `html`. A display name (`Billing <no-reply@…>`) is dropped to the bare address on this
+  path. Nothing else is ever sent.
+- **SMTP path:** pass the app's own SMTP server as `smtp: { host, port, secure?, username,
+  password }`, read from Worker secrets (`requireSecret`). Every email then goes through it,
+  unmetered, with the display name kept. The service never stores the credentials, never retries
+  SMTP failures, and neither the service nor this adapter logs them.
+- **Placeholder addresses** of phone-only users (any reserved `.invalid` domain, see
+  `isPlaceholderEmail` in `@awsmbiz/inbis-core`) are refused by both email adapters with
+  `EMAIL_RECIPIENT_PLACEHOLDER` (400, not retryable); nothing is sent or logged.
+- `EmailMessage.idempotencyKey` is accepted but not deduplicated.
+
+## SMS
+
+```ts
+import { requiredAuthSmsTemplates } from "@awsmbiz/inbis-auth";
+import { createCommunicationServiceSmsSender } from "@awsmbiz/inbis-notifications";
+
+const sms = createCommunicationServiceSmsSender({
+  binding,
+  appId: env.APP_ID,
+  smsHeader: "AWSMIN", // default DLT sender header
+  templates: {
+    // Message template key (from @awsmbiz/inbis-auth) -> the app's DLT registration.
+    "auth.phone-otp": {
+      templateId: "1107000000000000001",
+      text: "{code} is your {appName} sign-in code. It expires in {minutes} minutes.",
+    },
+    "auth.invitation": {
+      smsHeader: "AWSMIV", // optional per-type header
+      templateId: "1107000000000000002",
+      text: "{inviter} invited you to {appName}. Sign in with this phone number to join: {url}",
+    },
+  },
+  requiredTemplates: requiredAuthSmsTemplates(config), // startup check
+});
+```
+
+- **The text must match the registered DLT template exactly**, so it is the app's to configure.
+  `text` is the registered template with `{name}` placeholders where DLT has `{#var#}`; the
+  sender fills them from the message's `template.variables` (`SmsMessage.template.id` picks the
+  entry). The message's own `text` is not sent. Chatico rejects a mismatch
+  (`SMS_TEMPLATE_MISMATCH`). Keep each variable within DLT's limit (commonly 30 characters per
+  `{#var#}`; check your registration), and remember a variable can be blank (e.g. an invitation
+  without an inviter name) when wording the template.
+- `@awsmbiz/inbis-auth` sends `auth.phone-otp` (`code`, `appName`, `minutes`) and `auth.invitation`
+  (`appName`, `inviter`, `url`); `AUTH_SMS_TEMPLATES` names them and
+  `requiredAuthSmsTemplates(config)` lists those a config needs (both, when phone OTP is on).
+- **Startup checks** (throw, naming the template, never content): `appId` present; every
+  `requiredTemplates` key configured; every template has a sender header (its own or the
+  default), a template ID and text.
+- **Phone numbers:** messages carry E.164 (`+919876543210`); anything else is
+  `SMS_RECIPIENT_INVALID` and nothing is sent. The service passes numbers to Chatico unchanged,
+  so `formatRecipient` converts them: `e164DigitsRecipient` (default, `919876543210`, country
+  code first) or `indianTenDigitRecipient` (`9876543210` for `+91` numbers). The AWSM Chatico
+  account expects the default, country code first without `+` (confirmed by the platform
+  owner); keep `e164DigitsRecipient` unless that account changes.
+- **DLT (India):** AWSM is the registered DLT entity. The app registers its sender header(s)
+  and content templates under AWSM's entity, then configures the header, template ID and exact
+  text here. The service does not check them.
+- The service bills one unit per message part per recipient (GSM-7: 160 characters, then 153
+  per part; Unicode: 70, then 67), so keep texts short and in GSM-7 where possible.
+
+## Errors
+
+Nothing is swallowed: every failure is thrown as an `EmailDeliveryError` or `SmsDeliveryError`.
+Their messages are caller-safe (no addresses, numbers, content, codes or credentials); the
+service's error is kept as `cause` for logs. The service's errors cross RPC as plain `Error`s, so
+they are mapped by message:
+
+| Service error (message) | Email `code` | SMS `code` | `retryable` |
+|---|---|---|---|
+| `No app registered with app_id "…"` | `EMAIL_APP_NOT_REGISTERED` | `SMS_APP_NOT_REGISTERED` | no |
+| `App "…" is suspended` | `EMAIL_APP_SUSPENDED` | `SMS_APP_SUSPENDED` | no |
+| `App "…" has exceeded its monthly quota` | `EMAIL_QUOTA_EXCEEDED` | `SMS_QUOTA_EXCEEDED` | yes (after a reset) |
+| `The Cloudflare send path does not support "…"` | `EMAIL_UNSUPPORTED_FIELD` | | no |
+| message with `E_SENDER_NOT_VERIFIED` / `E_RECIPIENT_NOT_ALLOWED` | `EMAIL_SENDER_NOT_VERIFIED` / `EMAIL_RECIPIENT_NOT_ALLOWED` | | no |
+| message with `E_RATE_LIMIT_EXCEEDED` / `E_DAILY_LIMIT_EXCEEDED` | `EMAIL_RATE_LIMITED` / `EMAIL_DAILY_LIMIT_EXCEEDED` | | yes |
+| `InvalidSms…` (`sendSms needs at least one recipient…`) | | `SMS_INVALID` | no |
+| `Chatico send failed (409): …` | | `SMS_TEMPLATE_MISMATCH` | no |
+| `Chatico send failed (5xx / 402 / 408 / 413): …` | | `SMS_PROVIDER_UNAVAILABLE` | yes |
+| other `Chatico send failed (…)` | | `SMS_DELIVERY_FAILED` | no |
+| anything else | `EMAIL_DELIVERY_FAILED` | `SMS_DELIVERY_FAILED` | no |
+
+Refused before the service is called: `EMAIL_RECIPIENT_PLACEHOLDER`, `EMAIL_SENDER_MISSING`,
+`SMS_TEMPLATE_NOT_CONFIGURED`, `SMS_TEMPLATE_VARIABLE_MISSING`, `SMS_RECIPIENT_INVALID`.
+
+`retryable` means a later attempt may succeed; it does not mean the caller should resend. The
+service already retries Cloudflare and Chatico delivery failures on its own cron (Chatico has no
+idempotency key, so resending may deliver twice).
+
+## Log adapters (local development)
+
+```ts
+const email = createLogEmailSender(); // prints to console.info
+email.recent(); // LoggedEmail[]: { messageId, sentAt, to, from, replyTo, subject, text, html, links }
+
+const sms = createLogSmsSender(); // prints to console.info
+sms.recent(); // LoggedSms[]: { messageId, sentAt, to, text, templateId }
+```
+
+Each email is printed with its sender, recipient, reply-to, subject, the full text body and
+every http(s) link from both parts; each SMS with its recipient, template key and text. Nothing
+is discarded silently. Use them only where nobody expects real delivery: their output contains
+live verification and reset links and sign-in codes. The playground serves `recent()` as local
+outboxes (`GET /api/dev/outbox`, `GET /api/dev/sms-outbox`, on localhost only).
+
+## Templates
+
+```ts
+import { authEmailTemplates } from "@awsmbiz/inbis-notifications";
+
+createInbisAuth({ config, env, db, email, emailTemplates: authEmailTemplates, ... });
+```
+
+`@awsmbiz/inbis-auth` renders its emails with the injected `AuthEmailTemplates` and the brand from its
+config (`emails.brand`). Each email has a subject, a plain-text part and an HTML part:
+
+- **Layout:** table-based with inline styles, so it works in most email clients. It shows the
+  brand name or logo, a heading, a greeting, an action button, the link again as text, a note on
+  how long the link works, and an optional footer.
+- **Branding (`EmailBrand`):** `name`, `logoUrl` (shown only if it is https), `accentColor`
+  (used only if it matches `#rrggbb`; otherwise a neutral colour) and `footer`. Every value is
+  HTML-escaped, so branding and user names cannot inject markup or CSS.
+- **Message keys:** every string comes from `emailMessages` (`auth.verifyEmail.*`,
+  `auth.resetPassword.*`, `auth.invitation.*`, `duration.*`, `email.*`), with `{appName}`,
+  `{name}`, `{minutes}`, `{inviter}` and `{duration}` placeholders.
+- **Invitation email** (`invitation({ brand, recipientName, url, expiresInMinutes, inviterName, role })`):
+  "{inviter} invited you to {appName}", a note when the role is `admin`, and how long the link
+  works in days, hours or minutes. A blank inviter name gets a neutral wording.
+  To add a locale, pass a complete catalogue: `createAuthEmailTemplates(frenchMessages)`.

package/dist/index.d.ts

@@ -0,0 +1,354 @@
+import { AppError, AuthEmailTemplates, EmailBrand, EmailSender, RenderedEmail, SmsSender } from "@awsmbiz/inbis-core";
+/**
+ * Every string of the email templates, by message key. English only in the
+ * baseline; another locale is another catalogue passed to
+ * `createAuthEmailTemplates`. `{name}` placeholders are filled at render time.
+ */
+export declare const emailMessages: {
+  readonly "email.greeting": "Hi {name},";
+  readonly "email.greetingNoName": "Hi,";
+  readonly "email.linkFallback": "If the button does not work, copy this link into your browser:";
+  readonly "email.signOff": "— The {appName} team";
+  readonly "auth.verifyEmail.subject": "Verify your email address for {appName}";
+  readonly "auth.verifyEmail.heading": "Verify your email address";
+  readonly "auth.verifyEmail.intro": "Confirm that this is your email address to finish setting up your {appName} account.";
+  readonly "auth.verifyEmail.action": "Verify email address";
+  readonly "auth.verifyEmail.expiry": "This link works for {minutes} minutes.";
+  readonly "auth.verifyEmail.ignore": "If you did not create an account, you can ignore this email.";
+  readonly "auth.resetPassword.subject": "Reset your {appName} password";
+  readonly "auth.resetPassword.heading": "Reset your password";
+  readonly "auth.resetPassword.intro": "Someone asked to reset the password of your {appName} account.";
+  readonly "auth.resetPassword.action": "Reset password";
+  readonly "auth.resetPassword.expiry": "This link works for {minutes} minutes and can be used once.";
+  readonly "auth.resetPassword.ignore": "If you did not ask for this, ignore this email: your password stays the same.";
+  readonly "auth.invitation.subject": "{inviter} invited you to {appName}";
+  readonly "auth.invitation.subjectNoInviter": "You are invited to {appName}";
+  readonly "auth.invitation.heading": "You are invited to {appName}";
+  readonly "auth.invitation.intro": "{inviter} invited you to join {appName}.";
+  readonly "auth.invitation.introNoInviter": "You have been invited to join {appName}.";
+  readonly "auth.invitation.introAdmin": "You will join as an administrator.";
+  readonly "auth.invitation.action": "Accept invitation";
+  readonly "auth.invitation.expiry": "This invitation works for {duration} and can be used once.";
+  readonly "auth.invitation.ignore": "If you were not expecting this invitation, you can ignore this email.";
+  readonly "duration.minutes": "{count} minutes";
+  readonly "duration.hours": "{count} hours";
+  readonly "duration.days": "{count} days";
+};
+type EmailMessageKey = keyof typeof emailMessages;
+/** A complete message catalogue (one locale). */
+type EmailMessages = Record<EmailMessageKey, string>;
+/** Auth email templates over a message catalogue (one locale). */
+export declare function createAuthEmailTemplates(messages?: EmailMessages): AuthEmailTemplates;
+/** The English auth email templates; pass to `createInbisAuth({ emailTemplates })`. */
+export declare const authEmailTemplates: AuthEmailTemplates;
+/** Content of a branded transactional email with one call to action. */
+interface BrandedEmailContent {
+  brand: EmailBrand;
+  subject: string;
+  /** Greeting line, e.g. "Hi Ada,". */
+  greeting: string;
+  heading: string;
+  /** Paragraphs before the button. */
+  intro: readonly string[];
+  action: {
+    label: string;
+    url: string;
+  };
+  /** Line under the button explaining how to copy the link. */
+  linkFallback: string;
+  /** Paragraphs after the button (expiry, "ignore if not you"). */
+  outro: readonly string[];
+  signOff: string;
+}
+/**
+ * Renders a branded email as plain text and HTML. All text is escaped; the
+ * accent colour must be `#rrggbb` and the logo an https URL, otherwise they
+ * are left out. Table-based, inline-styled HTML for broad client support.
+ */
+export declare function renderBrandedEmail(content: BrandedEmailContent): RenderedEmail;
+/**
+ * The RPC surface of AWSM's shared communication service
+ * (`biz-cloud-communication-service`, entrypoint `CommunicationService`) that
+ * Inbis apps use, typed structurally so nothing depends on the private
+ * service repo. Apps reach it over a service binding, conventionally named
+ * `COMMUNICATION_SERVICE`, and always pass their platform-set `APP_ID`.
+ */
+/** A mailbox on the SMTP path; the metered Cloudflare path takes plain strings only. */
+interface CommunicationServiceMailbox {
+  name?: string;
+  email: string;
+}
+/**
+ * The subset of the service's email message (`@workermailer/smtp`
+ * `EmailOptions`) that Inbis sends: one recipient, optional reply-to.
+ */
+interface CommunicationServiceEmail {
+  from: string | CommunicationServiceMailbox;
+  to: string;
+  reply?: string;
+  subject: string;
+  text?: string;
+  html?: string;
+}
+/** Per-app SMTP credentials. Pass them from Worker secrets; they are never stored or logged. */
+interface SmtpCredentials {
+  host: string;
+  port: number;
+  /** Implicit TLS (port 465). Omit for STARTTLS (port 587). */
+  secure?: boolean;
+  username: string;
+  password: string;
+  authType?: "plain" | "login" | "cram-md5" | ("plain" | "login" | "cram-md5")[];
+}
+/** One SMS to send through AWSM's Chatico account. */
+interface CommunicationServiceSms {
+  /** DLT sender header, registered by the app. */
+  smsHeader: string;
+  /** DLT template ID for that header. */
+  templateId: string;
+  /** Numbers in the format the Chatico account expects. */
+  recipients: string[];
+  /** Must match the registered DLT template text. */
+  message: string;
+}
+interface CommunicationServiceSmsResult {
+  submissionId: string;
+  messageIds: string[];
+  smsCount: number;
+}
+/**
+ * The service binding as Inbis uses it. A `Service<CommunicationService>`
+ * stub satisfies it; a binding typed as a plain `Fetcher` (no service types)
+ * needs a cast to this interface.
+ */
+interface CommunicationServiceBinding {
+  sendEmail(appId: string, message: CommunicationServiceEmail, smtp?: SmtpCredentials): Promise<unknown>;
+  sendSms(appId: string, message: CommunicationServiceSms): Promise<CommunicationServiceSmsResult>;
+}
+/**
+ * Types a service binding as the communication service. `wrangler types`
+ * types a service binding without the service's source as a plain `Fetcher`;
+ * at runtime its RPC methods are callable all the same.
+ */
+export declare function communicationServiceBinding(binding: Fetcher | CommunicationServiceBinding): CommunicationServiceBinding;
+interface CommunicationServiceEmailSenderOptions {
+  /** The `COMMUNICATION_SERVICE` service binding. */
+  binding: CommunicationServiceBinding;
+  /** The app's platform-set `APP_ID` (`env.APP_ID`). Never user input. */
+  appId: string;
+  /** Default sender, e.g. `Billing <no-reply@billing.example.com>`. A message's own `from` wins. */
+  from?: string;
+  /** Default reply-to address. A message's own `replyTo` wins. */
+  replyTo?: string;
+  /**
+   * The app's own SMTP server (from Worker secrets). When set, every email takes
+   * the unmetered SMTP path; otherwise AWSM's metered Cloudflare path.
+   */
+  smtp?: SmtpCredentials;
+}
+/**
+ * {@link EmailSender} over AWSM's shared communication service. Without `smtp`
+ * it uses the metered Cloudflare path, which takes only plain-string addresses:
+ * a display name in `from` is dropped there (kept on the SMTP path). Quota,
+ * suspension and retries belong to the service. Every failure is thrown as an
+ * {@link EmailDeliveryError}; nothing is swallowed or logged.
+ */
+export declare function createCommunicationServiceEmailSender(options: CommunicationServiceEmailSenderOptions): EmailSender;
+/**
+ * One SMS type (e.g. `auth.phone-otp`) as registered on DLT. The rendered text
+ * must match the registered template exactly, or Chatico rejects it.
+ */
+interface SmsTemplateConfig {
+  /** DLT sender header for this type. Defaults to the sender's `smsHeader`. */
+  smsHeader?: string;
+  /** The DLT template ID. */
+  templateId: string;
+  /**
+   * The registered template text with `{name}` placeholders for the message's
+   * variables, e.g. `"{code} is your {appName} sign-in code. Valid for {minutes} minutes."`.
+   * Each placeholder fills one `{#var#}` slot of the DLT template.
+   */
+  text: string;
+}
+interface CommunicationServiceSmsSenderOptions {
+  /** The `COMMUNICATION_SERVICE` service binding. */
+  binding: CommunicationServiceBinding;
+  /** The app's platform-set `APP_ID` (`env.APP_ID`). Never user input. */
+  appId: string;
+  /** Default DLT sender header for templates that do not set their own. */
+  smsHeader?: string;
+  /** Message template key (`SmsMessage.template.id`) to its DLT configuration. */
+  templates: Record<string, SmsTemplateConfig>;
+  /**
+   * Template keys that must be configured, checked at startup, e.g.
+   * `requiredAuthSmsTemplates(config)` from `@awsmbiz/inbis-auth`.
+   */
+  requiredTemplates?: readonly string[];
+  /**
+   * Converts an E.164 number (`+919876543210`) to the format the service's
+   * Chatico account expects. Default: {@link e164DigitsRecipient} (`919876543210`).
+   */
+  formatRecipient?: (e164: string) => string;
+}
+/** `+919876543210` → `919876543210` (country code first, no `+`). The default. */
+export declare function e164DigitsRecipient(e164: string): string;
+/** `+919876543210` → `9876543210` (Indian numbers without the country code); other numbers as {@link e164DigitsRecipient}. */
+export declare function indianTenDigitRecipient(e164: string): string;
+/**
+ * {@link SmsSender} over AWSM's shared communication service (Chatico, AWSM as
+ * the DLT entity). The message's `template.id` picks the app's DLT
+ * configuration; the text sent is that template's text with the message's
+ * variables filled in (the message's own `text` is not sent). Quota,
+ * suspension and retries belong to the service. Every failure is thrown as an
+ * {@link SmsDeliveryError}; nothing is swallowed or logged.
+ */
+export declare function createCommunicationServiceSmsSender(options: CommunicationServiceSmsSenderOptions): SmsSender;
+/** Stable codes of {@link EmailDeliveryError}. */
+type EmailDeliveryErrorCode =
+/** The communication service has no app registered under this `APP_ID`. */
+"EMAIL_APP_NOT_REGISTERED" |
+/** The app's email channel is suspended in the communication service. */
+"EMAIL_APP_SUSPENDED" |
+/** The app has used its monthly email quota; sending works again once it is reset or raised. */
+"EMAIL_QUOTA_EXCEEDED" |
+/** The metered (Cloudflare) path cannot send this message; it needs the SMTP path. */
+"EMAIL_UNSUPPORTED_FIELD" |
+/** The sending address/domain is not onboarded or verified (`E_SENDER_NOT_VERIFIED`). */
+"EMAIL_SENDER_NOT_VERIFIED" |
+/** The recipient is not allowed (`E_RECIPIENT_NOT_ALLOWED`). */
+"EMAIL_RECIPIENT_NOT_ALLOWED" |
+/** Short-term rate limit hit (`E_RATE_LIMIT_EXCEEDED`); the service retries it. */
+"EMAIL_RATE_LIMITED" |
+/** The sending account's daily quota is used up (`E_DAILY_LIMIT_EXCEEDED`); the service retries it. */
+"EMAIL_DAILY_LIMIT_EXCEEDED" |
+/** No `from` address on the message or the sender. */
+"EMAIL_SENDER_MISSING" |
+/** The recipient is a phone-only user's placeholder (`.invalid`) address; nothing is sent. */
+"EMAIL_RECIPIENT_PLACEHOLDER" |
+/** Anything else, including unknown service or provider errors. */
+"EMAIL_DELIVERY_FAILED";
+interface EmailDeliveryErrorOptions {
+  code: EmailDeliveryErrorCode;
+  /** The provider's own code (e.g. `E_RATE_LIMIT_EXCEEDED`), when the service error carried one. */
+  providerCode?: string;
+  cause?: unknown;
+}
+/**
+ * An email that was not accepted for delivery. Never swallowed: adapters throw it.
+ * The message is caller-safe (no addresses or content); the service's error
+ * is kept as `cause` for logs.
+ */
+export declare class EmailDeliveryError extends AppError {
+  readonly code: EmailDeliveryErrorCode;
+  readonly providerCode: string | undefined;
+  /** True when sending the same message later may succeed (rate, daily or monthly limits). */
+  readonly retryable: boolean;
+  constructor(options: EmailDeliveryErrorOptions);
+}
+/** Stable codes of {@link SmsDeliveryError}. */
+type SmsDeliveryErrorCode =
+/** The message has no template, or its template key is not configured. */
+"SMS_TEMPLATE_NOT_CONFIGURED" |
+/** The template text needs a variable the message does not carry. */
+"SMS_TEMPLATE_VARIABLE_MISSING" |
+/** The recipient is not an E.164 number. */
+"SMS_RECIPIENT_INVALID" |
+/** The communication service has no app registered under this `APP_ID`. */
+"SMS_APP_NOT_REGISTERED" |
+/** The app's SMS channel is suspended in the communication service. */
+"SMS_APP_SUSPENDED" |
+/** The app has used its monthly SMS quota (a quota of 0 means SMS is off). */
+"SMS_QUOTA_EXCEEDED" |
+/** The service refused the message as empty or without recipients (`InvalidSmsError`). */
+"SMS_INVALID" |
+/** Chatico rejected the text as not matching the DLT template (HTTP 409). */
+"SMS_TEMPLATE_MISMATCH" |
+/** Chatico failed in a way the service retries on its own (5xx, 408, 402, 413). */
+"SMS_PROVIDER_UNAVAILABLE" |
+/** Anything else: another Chatico rejection, or an unknown service error. */
+"SMS_DELIVERY_FAILED";
+interface SmsDeliveryErrorOptions {
+  code: SmsDeliveryErrorCode;
+  /** Chatico's HTTP status, when the service relayed one. */
+  providerStatus?: number;
+  cause?: unknown;
+}
+/**
+ * An SMS that was not accepted for delivery, or that could not be sent as configured.
+ * Never swallowed: adapters throw it. The message is caller-safe (no numbers or
+ * content); the service's error is kept as `cause` for logs.
+ */
+export declare class SmsDeliveryError extends AppError {
+  readonly code: SmsDeliveryErrorCode;
+  readonly providerStatus: number | undefined;
+  /** True when sending the same message later may succeed. */
+  readonly retryable: boolean;
+  constructor(options: SmsDeliveryErrorOptions);
+}
+/** An email as the log adapter recorded it. */
+interface LoggedEmail {
+  messageId: string;
+  /** ISO timestamp. */
+  sentAt: string;
+  to: string;
+  from: string | undefined;
+  replyTo: string | undefined;
+  subject: string;
+  text: string;
+  html: string | undefined;
+  /** Every http(s) link in the text and HTML parts, in order, each once. */
+  links: string[];
+}
+interface LogEmailSenderOptions {
+  /** Where the rendered email goes. Default `console.info`. */
+  print?: (text: string) => void;
+  /** Default sender address, as a real adapter would use. */
+  from?: string;
+  /** How many recent emails {@link LogEmailSender.recent} keeps. Default 50. */
+  keep?: number;
+}
+interface LogEmailSender extends EmailSender {
+  /** The most recent emails, newest last (for a local outbox viewer). */
+  recent(): readonly LoggedEmail[];
+}
+/**
+ * Development {@link EmailSender} that prints every email in full (addresses,
+ * subject, text body and links) instead of delivering it, and keeps the recent
+ * ones for an outbox viewer. Nothing is silently discarded.
+ *
+ * Never use it where real users expect email: it delivers nothing, and its
+ * output (and outbox) contains live verification and reset links.
+ */
+export declare function createLogEmailSender(options?: LogEmailSenderOptions): LogEmailSender;
+/** An SMS as the log adapter recorded it. */
+interface LoggedSms {
+  messageId: string;
+  /** ISO timestamp. */
+  sentAt: string;
+  /** E.164 recipient. */
+  to: string;
+  text: string;
+  /** The message's template key (e.g. `auth.phone-otp`), when it has one. */
+  templateId: string | undefined;
+}
+interface LogSmsSenderOptions {
+  /** Where the message goes. Default `console.info`. */
+  print?: (text: string) => void;
+  /** How many recent messages {@link LogSmsSender.recent} keeps. Default 50. */
+  keep?: number;
+}
+interface LogSmsSender extends SmsSender {
+  /** The most recent messages, newest last (for a local outbox viewer). */
+  recent(): readonly LoggedSms[];
+}
+/**
+ * Development {@link SmsSender} that prints every message in full instead of
+ * delivering it, and keeps the recent ones for an outbox viewer. Nothing is
+ * silently discarded.
+ *
+ * Never use it where real users expect SMS: it delivers nothing, and its
+ * output (and outbox) contains live sign-in codes.
+ */
+export declare function createLogSmsSender(options?: LogSmsSenderOptions): LogSmsSender;
+export type { BrandedEmailContent, CommunicationServiceBinding, CommunicationServiceEmail, CommunicationServiceEmailSenderOptions, CommunicationServiceMailbox, CommunicationServiceSms, CommunicationServiceSmsResult, CommunicationServiceSmsSenderOptions, EmailDeliveryErrorCode, EmailDeliveryErrorOptions, EmailMessageKey, EmailMessages, LogEmailSender, LogEmailSenderOptions, LogSmsSender, LogSmsSenderOptions, LoggedEmail, LoggedSms, SmsDeliveryErrorCode, SmsDeliveryErrorOptions, SmsTemplateConfig, SmtpCredentials };
+//# sourceMappingURL=index.d.ts.map