@easybits.cloud/mailmask 0.4.12 → 0.6.1

package/README.md

@@ -81,6 +81,166 @@ import { verifyWebhookSignature } from "@easybits.cloud/mailmask";
 const ok = await verifyWebhookSignature(secret, { signature: req.headers["x-mailmask-signature"], timestamp: req.headers["x-mailmask-timestamp"] }, rawBody);
 ```
 
+## Partners
+
+For apps that send email **on behalf of their own customers** (each customer is a *tenant* with its
+own domain, quota and reputation). Uses a partner credential (`mmk_…` + `mms_…` secret), not an `mk_`
+key. Every request is signed with HMAC-SHA256 automatically; `send`/`batch` get an `idempotencyKey`
+when you don't pass one (the same key on every retry).
+
+Transport (0.6):
+
+- **Retries** on rate-limit 429, 5xx, network errors and timeouts — exponential backoff with jitter
+  (`retryBaseMs` 500 → 250–500 ms, 500–1000 ms, …), honoring `Retry-After`. Only safe requests are
+  retried: GET/PUT/DELETE, `tenants.pause`/`resume`, `domains.add` and `send`/`batch` (they always
+  carry an idempotency key). `webhook.rotateSecret` and `webhook.test` are never retried. If
+  `Retry-After` asks for more than `retryMaxDelayMs` (default 30 s) the error is thrown with
+  `retryAfterMs` so you decide. `maxRetries` default 3, max 10; `onRetry` hook for your logs.
+- **Timeout** per attempt with `AbortController` (`timeoutMs`, default 30 s) → `TimeoutError`.
+- **Secrets stay out of logs**: the secret is not a property of the client (`console.log(mm)` can't
+  print it) and no error message carries it.
+
+```ts
+const mm = new MailMaskPartner({
+  keyId: process.env.MAILMASK_KEY_ID!, secret: process.env.MAILMASK_SECRET!,
+  timeoutMs: 10_000, maxRetries: 5,
+  onRetry: ({ attempt, delayMs, error }) => console.warn(`mailmask retry ${attempt} in ${delayMs} ms`, error.kind, error.requestId),
+});
+```
+
+Example: Formmy sending a newsletter from its customer's domain.
+
+```ts
+import {
+  MailMaskPartner, PausedError, QuotaError, RecipientSuppressedError, ReputationHoldError, ValidationError, verifyWebhook,
+} from "@easybits.cloud/mailmask";
+
+const mm = new MailMaskPartner({ keyId: process.env.MAILMASK_KEY_ID!, secret: process.env.MAILMASK_SECRET! });
+
+// 1. One tenant per Formmy customer (idempotent: call it on every sign-up/update)
+await mm.tenants.put("formmy-user-42", { name: "Panadería La Espiga" });
+
+// 2. Their domain: show these DNS records to the customer, then poll the status
+const { records } = await mm.domains.add("formmy-user-42", "laespiga.mx");
+// records: [{ type: "TXT", name: "_amazonses", value: "…", level: "requerido" }, …]
+const { state } = await mm.domains.status("formmy-user-42", "laespiga.mx"); // "pending" | "verified" | "failed"
+
+// 3. Send (pass your own idempotencyKey to make retries across processes safe).
+//    `stream`: "transactional" (default for send: receipts, reminders; no unsubscribe link) or
+//    "broadcast" (newsletters: one-click List-Unsubscribe; an unsubscribe only silences broadcast).
+try {
+  await mm.send("formmy-user-42", {
+    from: "La Espiga <hola@laespiga.mx>",
+    to: "reader@example.com",
+    subject: "Pan de muerto ya disponible",
+    html: "<p>Desde hoy…</p>",
+    tags: { campaign: "oct-26" },
+    stream: "broadcast",
+    idempotencyKey: "campaign-oct-26:reader@example.com",
+  });
+} catch (e) {
+  if (e instanceof RecipientSuppressedError) { /* e.reason, e.stream, e.recipient: mark the reader, don't retry */ }
+  else if (e instanceof PausedError) { /* tenant paused (bounces/complaints): stop until resume */ }
+  else if (e instanceof QuotaError) { /* e.limit, e.resetsAt */ }
+  else if (e instanceof ValidationError) { /* e.field */ }
+  else throw e;
+}
+
+// Up to 10,000 recipients in the background (stream defaults to "broadcast"; suppressed ones are
+// skipped). Recipients are plain addresses or { to, vars }: {{name}} in subject/html/text is replaced
+// per recipient (escaped inside html). Broadcasts get {{unsubscribe_url}} (or a footer if unused).
+const job = await mm.batch("formmy-user-42", {
+  from: "hola@laespiga.mx", subject: "Hola {{nombre}}", html: "<p>{{nombre}}, tu cupón: {{cupon}}</p>",
+  recipients: ["ana@example.com", { to: "bea@example.com", vars: { nombre: "Bea", cupon: "OCT10" } }],
+});
+const st = await mm.batchStatus("formmy-user-42", job.batchId);
+// st.sent / failed / skippedSuppressed, then (for up to 7 days) delivered / bounced / complained / unsubscribed
+
+// Test mode: validates everything (signature, domain, suppression, quota) without sending or billing
+await mm.send("formmy-user-42", { from: "hola@laespiga.mx", to: "x@example.com", subject: "s", text: "t" }, { test: true });
+
+// Preview exactly what one recipient gets — same function the server uses, no network
+import { previewMessage } from "@easybits.cloud/mailmask";
+const p = previewMessage({ subject: "Hola {{nombre}}", html: "<p>{{nombre}}</p>", stream: "broadcast", vars: { nombre: "Ana" } });
+// p.subject, p.html, p.unsubscribeFooter, p.missingVars, p.unusedVars
+
+// Monthly usage (active tenants = at least one send this month)
+await mm.usage({ month: "2026-10" });
+
+// 4. Webhook: the whsec_ secret comes back only the FIRST time (later `set` calls return null:
+//    changing the URL doesn't rotate it)
+const { secret } = await mm.webhook.set({ url: "https://formmy.app/api/mailmask/events" });
+await mm.webhook.test(); // sends a `ping`
+
+// Rotate without losing events: during the grace period (default 24 h) every delivery carries both
+// signatures; pass both secrets to verifyWebhook until you've deployed the new one.
+const { secret: next, previousValidUntil } = await mm.webhook.rotateSecret({ graceMinutes: 60 });
+
+// Pausing: tenants.resume only lifts a pause YOU set (pausedBy "partner"). A reputation pause
+// (pausedBy "mailmask" | "ses") throws ReputationHoldError: MailMask lifts it after review.
+try { await mm.tenants.resume("formmy-user-42"); } catch (e) { if (!(e instanceof ReputationHoldError)) throw e; }
+```
+
+Webhook handler — the one-liner (Workers, Deno, Bun, Next.js route handlers, Hono…): verifies the
+signature on the raw body, answers 401 / 200, and 500 if your `onEvent` throws (MailMask retries):
+
+```ts
+import { createWebhookHandler } from "@easybits.cloud/mailmask";
+export const POST = createWebhookHandler({
+  secret: [process.env.MAILMASK_WEBHOOK_SECRET!, process.env.MAILMASK_WEBHOOK_SECRET_OLD ?? ""],
+  onEvent: async (event) => { /* dedupe by event.id */ },
+});
+```
+
+Or by hand (Remix/React Router, anything with a `Request`):
+
+```ts
+export async function action({ request }: { request: Request }) {
+  const rawBody = await request.text(); // the RAW body, before JSON.parse
+  const event = await verifyWebhook({ rawBody, headers: request.headers, secret: [process.env.MAILMASK_WEBHOOK_SECRET!, process.env.MAILMASK_WEBHOOK_SECRET_OLD ?? ""] });
+  if (!event) return new Response("bad signature", { status: 401 });
+  // event.id is the delivery id: use it to drop duplicates
+  switch (event.event) {
+    case "email.bounced":
+    case "contact.unsubscribed":
+      // mark the reader as unsubscribed for event.externalId
+      break;
+    case "tenant.paused":
+      // notify the customer
+      break;
+  }
+  return new Response("ok");
+}
+```
+
+Errors: all extend `MailMaskError` (`status`, `code`, `requestId`, `retryable`) and `PartnerApiError`
+(`body`, `retryAfterMs` and a `kind` discriminant for a plain `switch`):
+
+| Class | `status` | `kind` | Retried by the SDK |
+|---|---|---|---|
+| `AuthError` | 401 | `auth` | no — `clockSkewMs` + a hint in the message if your clock is off |
+| `ForbiddenError` | 403 | `forbidden` | no |
+| `ReputationHoldError` (extends `ForbiddenError`) | 403 | `reputation_hold` | no |
+| `NotFoundError` | 404 | `not_found` | no |
+| `ConflictError` | 409 | `conflict` | no |
+| `ValidationError` (`field`) | 422 | `validation` | no |
+| `RecipientSuppressedError` (`reason`, `stream`, `recipient`) | 422 | `suppressed` | no |
+| `PausedError` | 423 | `paused` | no |
+| `QuotaError` (`limit`, `resetsAt`) | 429 `quota_exceeded` | `quota` | no |
+| `RateLimitError` (extends `QuotaError`) | 429 `rate_limited` | `rate_limit` | yes |
+| `PartnerApiError` | 5xx | `server` | yes (safe requests) |
+| `NetworkError` / `TimeoutError` | 0 | `network` / `timeout` | yes (safe requests) |
+
+`requestId` comes from `X-Request-Id` / `Fly-Request-Id`: quote it when asking for support.
+
+Admin routes (your `mk_` owner key, not the partner credential): `MailMaskPartnerAdmin` —
+`listPartners`, `listCredentials`, `createCredential`, `rotateCredential`, `revokeCredential`,
+`getFallbackZone` and, for MailMask staff only, `createPartner`, `setReputationPolicy`, `resumeTenant`,
+`setFallbackZone` (registers the partner's fallback zone, e.g. `marketing.denik.me`, and returns the
+4 NS to delegate; then `domains.add(id, "<label>.marketing.denik.me")` writes its DNS and verifies on
+its own). Issuing and rotating
+are never retried (a lost response would hide a secret nobody saw).
+
 ## TypeScript
 
 Los tipos publicados se pueden consumir desde **TypeScript 4.9 en adelante**, también con

package/dist/client.d.ts

@@ -1,7 +1,24 @@
 import type { MailMaskConfig, Domain, DomainCreated, DomainVerification, Alias, AliasCreated, MailboxCreated, CreateAliasInput, UpdateAliasInput, Rule, CreateRuleInput, UpdateRuleInput, EmailLog, SendEmailInput, BulkSendInput, BulkJob, BulkJobCreated, SmtpCredential, SmtpCredentialCreated, ApiKey, SendOptions, UploadAttachmentInput, UploadedAttachment, Suppression, Webhook, WebhookCreated, CreateWebhookInput, UpdateWebhookInput, WebhookDelivery, DnsRecordType, DnsListResponse, DnsZoneCreated, DnsDelegation, DnsImportResult, DnsAudit, DnsLookup, DnsLookupType, HttpsCheck, RegistrationInfo, DnsChangeResult, DnsPreset, DnsPresetPreview, DnsSetup, WebsiteStatus, PublishEasyBitsSiteInput, EasyBitsPublishResult, EasyBitsSiteStatus, EasyBitsUnpublishResult, BillingStatus, AddonsResponse, CheckoutLink, DomainSearchResult, TldPrice, DomainRegistrationCreated, DomainRegistration, TransferCheck, TransferDnsInventory, RenewalLink, DomainMember, DomainInvite, CannedReply, AccountProfile, AccountMe, AccountExport, InboxPage, InboxListOptions, InboxConversation, InboxConversationDetail, InboxComposeInput, InboxReplyInput, InboxUpdateInput, InboxNote, OrdersPage, ReferralStats, UploadedEmailImage } from "./types.js";
+/** Opciones extra de `MailMaskError`; todas opcionales para no romper `new MailMaskError(status, msg)`. */
+export interface MailMaskErrorOptions {
+    /** Código estable de la API (`not_found`, `rate_limited`…), si la respuesta lo trae. */
+    code?: string;
+    /** Id de la petición (`X-Request-Id` o `Fly-Request-Id`): cítalo al pedir soporte. */
+    requestId?: string;
+    /** Si vale la pena reintentar la MISMA petición. Default: 0 (red), 429 o 5xx. */
+    retryable?: boolean;
+    cause?: unknown;
+}
+/**
+ * Error de la API. `status` 0 = no hubo respuesta (red o tiempo agotado). Nunca lleva la llave ni
+ * el secreto: el mensaje sale del servidor o del runtime, y no se guardan los headers enviados.
+ */
 declare class MailMaskError extends Error {
     status: number;
-    constructor(status: number, message: string);
+    code: string | undefined;
+    requestId: string | undefined;
+    retryable: boolean;
+    constructor(status: number, message: string, opts?: MailMaskErrorOptions);
 }
 export declare class MailMask {
     private baseUrl;