@brandlab-digital/site-next 3.12.1 → 3.14.0

package/README.md

@@ -2,6 +2,138 @@
 
 Proprietary software © Brandlab Digital Marketing. All rights reserved. Published for Brandlab client sites.
 
+## Reviews: refresh on change, not every day (3.13.0)
+
+The shared reviews fetch (`getBusinessProfileReviews`, `./google-business-reviews/server`) carries the tags
+`brandlab-reviews` and `brandlab-reviews:<site>`. By default it still keeps a successful answer for one day
+(`BUSINESS_PROFILE_REVIEWS_REVALIDATE_SECONDS`), so a site that installs 3.13.0 for another reason keeps daily reviews.
+
+A site opts into refresh on change by passing `refresh: 'on-change'`, in the same call that already names the site,
+once it has the route below deployed with its secret and is registered with the daily reviews checker:
+
+```ts
+// src/lib/reviews.ts
+getBusinessProfileReviews({ site: 'hr-kitchens', refresh: 'on-change' })
+```
+
+The answer is then kept for 7 days (`BUSINESS_PROFILE_REVIEWS_ON_CHANGE_REVALIDATE_SECONDS`) as a safety net only.
+Once a day the checker hashes each site's feed and, when the reviews have really changed, calls the site's signed
+revalidate route, which refreshes the tag. A new review still shows within a day; pages are rewritten only after a
+real change. If a call fails, pages refresh themselves within the week. The choice sits on the fetch, not in
+brandlab.config.ts, because the fetch is where Next reads it at build time and a site's config file is not imported
+at runtime.
+
+The route, at `src/app/api/brandlab/reviews-revalidate/route.ts`:
+
+```ts
+import { createBrandlabReviewsRevalidateRoute } from '@brandlab-digital/site-next/google-business-reviews/server'
+
+export const { POST } = createBrandlabReviewsRevalidateRoute({ site: 'hr-kitchens' })
+```
+
+Set `BRANDLAB_REVALIDATE_SECRET` (at least 32 characters) in the site's Vercel project and on the checker; never in
+git. The call contract:
+
+| | |
+| --- | --- |
+| Request | `POST /api/brandlab/reviews-revalidate`, body `{"site":"<slug>","hash":"<64 hex>"}` (1 KB at most) |
+| Signature | `x-brandlab-timestamp: <Unix seconds>` and `x-brandlab-signature: v1=<hex HMAC-SHA256 of "<timestamp>.<body>">`; site-core `createBusinessProfileReviewsRevalidateRequest` builds both |
+| Hash | site-core `hashBusinessProfileReviews(feed)`: the rating, the count and each review's id, rating, text, author, times and reply, sorted by id |
+| Who decides | The checker keeps the last hash each site accepted with a 200 and calls only when today's differs. The route also skips a hash it already applied, but only per server instance |
+| 200 | `{ ok: true, revalidated: true }` after `revalidateTag('brandlab-reviews:<site>', 'max')`, or `revalidated: false, reason: 'unchanged'` |
+| Errors | 400 malformed body or another site's slug; 401 missing or wrong signature, or a timestamp more than 5 minutes off; 413 body over 1 KB; 429 with `Retry-After` past 10 requests per IP in 10 minutes; 503 secret not set; 500 refresh failed. The checker records the hash only after a 200 |
+
+Refused requests log one line without the secret or signature, for example
+`{"event":"brandlab_reviews_revalidate","site":"hr-kitchens","result":"refused","reason":"signature"}`.
+
+### Estate segment preset (`./estate-segment`)
+
+Service-in-suburb and suburb pages export `revalidate = false`, written literally because Next reads segment config
+statically, and a site test calls `assertBrandlabEstateSegment(page)`. Deploys and the reviews tag rewrite them. A
+page that shows reviews follows the reviews fetch: daily by default, weekly with `refresh: 'on-change'`. Ready-gate
+check W3 (full tier, from 3.13.0) fails an estate family that refreshes more often than every 7 days, so a full-tier
+estate that shows reviews adopts `on-change` with the route, or records the family in `siteSystem.refreshExceptions`
+in brandlab.config.ts: `{ family, revalidateSeconds, reason, decisionId }`.
+
+## Contact delivery: accepted is not delivered (3.14.0)
+
+When Resend accepts an enquiry it is queued, not delivered. Resend can still bounce it, drop it because the business
+inbox is on the account's suppression list, or have it reported as spam, while the site has already said "sent". That
+is how BL Roofing lost enquiries. `contact_form` keeps its analytics-v4 meaning (Resend accepted the enquiry) and fires
+exactly as before; delivery is now tracked beside it.
+
+**Before sending.** `createBrandlabContactRouteHandler` asks Resend's suppression list about each business inbox
+(`GET /suppressions/{email}`, cached for 5 minutes per inbox, at most 2.5 seconds per lookup). The check only
+records and alerts; it never blocks a send. When an inbox is suppressed the route logs and alerts
+`recipient_suppressed`, and the enquiry still goes to the client's own inbox (never rerouted, never copied to Brandlab)
+with the normal "sent" result and `contact_form` as usual. Keeping the inbox and its email billing in order is the
+client's responsibility; the alert lets Brandlab tell them the same day. A site can opt in to refusing instead with
+`refuseWhenAllSuppressed: true`: when every inbox is suppressed the visitor then gets the form's "could not send,
+please call" answer and no conversion fires. A failed or refused lookup never stops an enquiry: it is
+sent as before and logged once per 5 minutes as `brandlab_contact_suppression_check_unavailable`. The lookup needs a
+full-access key: set `RESEND_LOOKUP_API_KEY` so `RESEND_API_KEY` can stay sending-only (without it the lookup uses
+`RESEND_API_KEY`). A sending-only key is refused with `restricted_api_key`, and the warning line names the missing
+permission (`"needs":"full-access key (RESEND_LOOKUP_API_KEY)"`). `suppressionCheck: false` turns the check off; a
+route that replaces the provider with `createResendSend` (synthetic tests) has it off unless it passes one.
+
+**After sending.** A signed webhook route records what happened to the business copy. Add
+`src/app/api/brandlab/resend-webhook/route.ts`:
+
+```ts
+import { createBrandlabResendWebhookRoute } from '@brandlab-digital/site-next/contact/server'
+import { contactContract } from '@/config/contact'
+
+export const { POST } = createBrandlabResendWebhookRoute({ projectId: contactContract.projectId })
+```
+
+Then, in plain steps:
+
+1. Deploy the route.
+2. In Resend, open Webhooks and add an endpoint: `https://<the site's domain>/api/brandlab/resend-webhook`.
+3. Tick the email events: delivered, delivery delayed, bounced, complained, suppressed and failed.
+4. Open the new webhook and copy its signing secret (it starts with `whsec_`).
+5. In the site's Vercel project, add `RESEND_WEBHOOK_SECRET` with that value for Production (and Preview if previews
+   send real enquiries). Never put it in git or `.env.example` values.
+6. Redeploy, send a test enquiry (`?bl_test=1`), and check the logs show a `brandlab_contact_delivery_status` line
+   with `"state":"delivered"`.
+
+Resend webhooks cover the whole account, so each site's route records only the emails its own contact route sent (the
+`project_id` tag) and answers 200 to the rest. The signature is checked the Svix way Resend documents
+(HMAC-SHA256 over `<svix-id>.<svix-timestamp>.<raw body>`, 5 minutes' clock tolerance); a bad signature gets 401, a
+missing secret 503. Failed attempts are rate-limited per `x-real-ip` (10 in 10 minutes, then 429 with `Retry-After`;
+`rateLimit` adjusts it or `false` turns it off); a correctly signed request never counts. A retry with an `svix-id` the
+instance already recorded answers 200 `duplicate: true` without logging again; that list is small and per instance,
+so it is best effort and the monitor still de-duplicates.
+
+Both halves accept `onDeliveryFailure(failure)`, a same-day alert hook (email, Slack or a durable store). It gets the
+code, source, enquiry reference and Resend email id, never an address or form value. If it throws on a webhook event
+the route answers 500 so Resend retries the event.
+
+| Environment variable | Where | What |
+| --- | --- | --- |
+| `RESEND_API_KEY` | Vercel, Production and Preview | Sends enquiries; can stay a sending-only key |
+| `RESEND_LOOKUP_API_KEY` | Vercel, Production and Preview (optional) | A full-access key used only for the suppression lookup; without it the lookup uses `RESEND_API_KEY` |
+| `RESEND_WEBHOOK_SECRET` | Vercel, Production | The webhook's `whsec_` signing secret |
+| the contract's `delivery.recipientEnv` | Vercel, Production and Preview | The business inbox |
+
+**For the daily delivery monitor (P26).** Read these JSON lines from the site's logs:
+
+| Line | Meaning | Action |
+| --- | --- | --- |
+| `{"event":"brandlab_contact_delivery_failed",…,"code":"recipient_suppressed","source":"pre-send","recipients":"all"}` | The inbox is suppressed; the enquiry was still sent (Resend will drop it) and the visitor saw "sent" (unless the site opted in to `refuseWhenAllSuppressed: true`, when it was not sent and the visitor was asked to call) | Same day: tell the client to fix the inbox, remove it from Resend → Suppressions, tell Romie |
+| same, `"recipients":"some"` | One of several inboxes is suppressed; the others got it | Same day: fix or remove that inbox |
+| `…"code":"recipient_bounced"/"recipient_complained"/"recipient_suppressed"/"provider_failed","source":"webhook"` | Resend accepted it but the business copy did not arrive (`detail` gives Resend's bounce type, suppression type or failure reason) | Same day: the enquiry counted as a `contact_form` but the business never saw it; find it by `submission` (the first 16 characters of the confirmation id) or `emailId` in Resend and forward it |
+| `{"event":"brandlab_contact_delivery_status","state":"delivered"}` / `"state":"delayed"` | Delivered, or Resend is retrying a soft bounce | None; a `delayed` with no later `delivered` or failure within a day needs a look |
+| `brandlab_contact_suppression_check_unavailable` | The pre-send check could not ask Resend (`code` says why; `needs` names a missing permission) | Set a full-access `RESEND_LOOKUP_API_KEY`; enquiries still send |
+| `brandlab_contact_delivery_alert_failed` | The alert hook failed | Check the hook |
+
+De-duplicate webhook lines on `webhookId` (Resend retries an event with the same id). Compare each day's
+`contact_form` count in GA4 with `delivered` lines: every accepted enquiry should end in exactly one `delivered` or one
+failure. Ready-gate check H13 (enquiry tier, from 3.14.0) checks the same inbox before launch: a real sender, MX records,
+the sender domain verified in Resend and the inbox not suppressed. Run `brandlab-ready --launch` with the inbox variable
+and a full-access key (`RESEND_LOOKUP_API_KEY`) set in the shell for that run, never written to a file. Without them H13
+reports "not run" and names what to set: in an ordinary run that does not block the tier, and under `--launch` it fails.
+
 ## Contact route: abuse limits and the test marker (3.10.0)
 
 `createBrandlabContactRouteHandler` limits distinct enquiries per client IP and per email address where enquiries are

package/dist/contact/delivery.d.ts

@@ -0,0 +1,81 @@
+import 'server-only';
+/**
+ * Delivery truth for contact enquiries (3.14.0).
+ *
+ * An enquiry Resend accepts is queued, not delivered: Resend can still bounce it, drop it because the inbox is on the
+ * account's suppression list, or have it reported as spam. `contact_form` keeps its analytics-v4 meaning (the provider
+ * accepted the enquiry) and is unchanged. Delivery is tracked beside it:
+ * - before sending, the business inboxes are checked against Resend's suppression list (`createResendSuppressionCheck`);
+ * - after sending, Resend's signed webhook reports delivered, delayed, bounced, complained, suppressed and failed
+ *   copies (`createBrandlabResendWebhookRoute`).
+ * Every failure writes one `brandlab_contact_delivery_failed` line for the daily delivery monitor and calls the
+ * optional alert hook the same moment. No line carries an address, a name, a form value or a key.
+ */
+export declare const BRANDLAB_CONTACT_DELIVERY_FAILED_EVENT: "brandlab_contact_delivery_failed";
+export declare const BRANDLAB_CONTACT_DELIVERY_STATUS_EVENT: "brandlab_contact_delivery_status";
+export declare const BRANDLAB_CONTACT_SUPPRESSION_UNAVAILABLE_EVENT: "brandlab_contact_suppression_check_unavailable";
+export declare const BRANDLAB_CONTACT_DELIVERY_ALERT_FAILED_EVENT: "brandlab_contact_delivery_alert_failed";
+/** How long one suppression answer (suppressed, clear or unavailable) is reused for an inbox. */
+export declare const BRANDLAB_CONTACT_SUPPRESSION_CACHE_MS: number;
+/** The longest an enquiry waits for the suppression lookup before it is sent anyway. */
+export declare const BRANDLAB_CONTACT_SUPPRESSION_TIMEOUT_MS = 2500;
+/**
+ * An optional full-access Resend key used only for the suppression and domain lookups, so the sending key
+ * (`RESEND_API_KEY`) can stay sending-only. Without it the lookups use `RESEND_API_KEY`.
+ */
+export declare const BRANDLAB_CONTACT_LOOKUP_API_KEY_ENV: "RESEND_LOOKUP_API_KEY";
+/** `suppressed`: Resend will not deliver to the inbox. `unknown`: the lookup could not tell, so the enquiry is sent. */
+export type BrandlabContactSuppressionStatus = 'suppressed' | 'clear' | 'unknown';
+export interface BrandlabContactSuppressionCheck {
+    /** Never throws; `unknown` whenever Resend could not be asked or did not answer clearly (fail open). */
+    check(address: string, context: {
+        apiKey: string;
+    }): Promise<BrandlabContactSuppressionStatus>;
+}
+export type BrandlabContactDeliveryFailureCode = 'recipient_suppressed' | 'recipient_bounced' | 'recipient_complained' | 'provider_failed';
+/** One enquiry copy that did not, or will not, reach a business inbox. Never carries an address or form value. */
+export interface BrandlabContactDeliveryFailure {
+    event: typeof BRANDLAB_CONTACT_DELIVERY_FAILED_EVENT;
+    provider: 'resend';
+    code: BrandlabContactDeliveryFailureCode;
+    /** `pre-send`: the suppression check stopped it before sending. `webhook`: Resend reported it after sending. */
+    source: 'pre-send' | 'webhook';
+    /** Pre-send only: whether every business inbox was suppressed (nothing sent) or only some (sent to the rest). */
+    recipients?: 'all' | 'some';
+    /** The first 16 hex characters of the enquiry's confirmation id (the `submission_hash` tag), when known. */
+    submission?: string;
+    /** Resend's email id, from the webhook. */
+    emailId?: string;
+    /** The webhook's `svix-id`, the same on every retry of one event, for de-duplication. */
+    webhookId?: string;
+    /** Resend's bounce type and subtype, suppression type or failure reason, when it gave a plain one. */
+    detail?: string;
+    /** When the library saw it (ISO 8601). */
+    at: string;
+}
+/**
+ * A same-day alert hook for delivery failures (email, Slack, a durable store): called once per failure after the log
+ * line is written. A hook that throws is logged; the webhook route then answers 500 so Resend retries the event.
+ */
+export type BrandlabContactDeliveryAlert = (failure: BrandlabContactDeliveryFailure) => void | Promise<void>;
+/** Writes the failure line (the daily monitor's input), then calls the alert hook. False when the hook failed. */
+export declare function reportContactDeliveryFailure(failure: BrandlabContactDeliveryFailure, alert?: BrandlabContactDeliveryAlert): Promise<boolean>;
+export interface ResendSuppressionCheckOptions {
+    /** Defaults to the global fetch. */
+    fetch?: typeof globalThis.fetch;
+    /** Defaults to `Date.now`. */
+    now?: () => number;
+    /** Defaults to BRANDLAB_CONTACT_SUPPRESSION_CACHE_MS. */
+    cacheMs?: number;
+    /** Defaults to BRANDLAB_CONTACT_SUPPRESSION_TIMEOUT_MS. */
+    timeoutMs?: number;
+}
+/**
+ * Asks Resend's suppression list about a business inbox before an enquiry is sent (`GET /suppressions/{email}`).
+ * Answers are reused for the cache window per inbox, so a busy form asks at most once per inbox in that window. Any
+ * error, timeout or refusal answers `unknown` and the enquiry is sent: the check can stop a send it knows is lost,
+ * never one it is unsure about. A refusal is logged once per cache window (a sending-only API key answers 401
+ * `restricted_api_key` and the line names the missing permission: set a full-access key in RESEND_LOOKUP_API_KEY).
+ */
+export declare function createResendSuppressionCheck(options?: ResendSuppressionCheckOptions): BrandlabContactSuppressionCheck;
+//# sourceMappingURL=delivery.d.ts.map

package/dist/contact/delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../../src/contact/delivery.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,CAAA;AAIpB;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,sCAAsC,EAAG,kCAA2C,CAAA;AACjG,eAAO,MAAM,sCAAsC,EAAG,kCAA2C,CAAA;AACjG,eAAO,MAAM,8CAA8C,EAAG,gDAAyD,CAAA;AACvH,eAAO,MAAM,4CAA4C,EAAG,wCAAiD,CAAA;AAE7G,iGAAiG;AACjG,eAAO,MAAM,qCAAqC,QAAiB,CAAA;AACnE,wFAAwF;AACxF,eAAO,MAAM,uCAAuC,OAAQ,CAAA;AAI5D;;;GAGG;AACH,eAAO,MAAM,mCAAmC,EAAG,uBAAgC,CAAA;AAGnF,wHAAwH;AACxH,MAAM,MAAM,gCAAgC,GAAG,YAAY,GAAG,OAAO,GAAG,SAAS,CAAA;AAEjF,MAAM,WAAW,+BAA+B;IAC9C,wGAAwG;IACxG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,gCAAgC,CAAC,CAAA;CAC/F;AAED,MAAM,MAAM,kCAAkC,GAC1C,sBAAsB,GACtB,mBAAmB,GACnB,sBAAsB,GACtB,iBAAiB,CAAA;AAErB,kHAAkH;AAClH,MAAM,WAAW,8BAA8B;IAC7C,KAAK,EAAE,OAAO,sCAAsC,CAAA;IACpD,QAAQ,EAAE,QAAQ,CAAA;IAClB,IAAI,EAAE,kCAAkC,CAAA;IACxC,gHAAgH;IAChH,MAAM,EAAE,UAAU,GAAG,SAAS,CAAA;IAC9B,iHAAiH;IACjH,UAAU,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;IAC3B,4GAA4G;IAC5G,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yFAAyF;IACzF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sGAAsG;IACtG,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAA;CACX;AAED;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,OAAO,EAAE,8BAA8B,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAE5G,kHAAkH;AAClH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,8BAA8B,EACvC,KAAK,CAAC,EAAE,4BAA4B,GACnC,OAAO,CAAC,OAAO,CAAC,CA6BlB;AAED,MAAM,WAAW,6BAA6B;IAC5C,oCAAoC;IACpC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IAC/B,8BAA8B;IAC9B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA6CD;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,GAAE,6BAAkC,GAC1C,+BAA+B,CAoCjC"}

package/dist/contact/delivery.js

@@ -0,0 +1,138 @@
+import 'server-only';
+import { RESEND_ERROR_CODES } from './resend.js';
+/**
+ * Delivery truth for contact enquiries (3.14.0).
+ *
+ * An enquiry Resend accepts is queued, not delivered: Resend can still bounce it, drop it because the inbox is on the
+ * account's suppression list, or have it reported as spam. `contact_form` keeps its analytics-v4 meaning (the provider
+ * accepted the enquiry) and is unchanged. Delivery is tracked beside it:
+ * - before sending, the business inboxes are checked against Resend's suppression list (`createResendSuppressionCheck`);
+ * - after sending, Resend's signed webhook reports delivered, delayed, bounced, complained, suppressed and failed
+ *   copies (`createBrandlabResendWebhookRoute`).
+ * Every failure writes one `brandlab_contact_delivery_failed` line for the daily delivery monitor and calls the
+ * optional alert hook the same moment. No line carries an address, a name, a form value or a key.
+ */
+export const BRANDLAB_CONTACT_DELIVERY_FAILED_EVENT = 'brandlab_contact_delivery_failed';
+export const BRANDLAB_CONTACT_DELIVERY_STATUS_EVENT = 'brandlab_contact_delivery_status';
+export const BRANDLAB_CONTACT_SUPPRESSION_UNAVAILABLE_EVENT = 'brandlab_contact_suppression_check_unavailable';
+export const BRANDLAB_CONTACT_DELIVERY_ALERT_FAILED_EVENT = 'brandlab_contact_delivery_alert_failed';
+/** How long one suppression answer (suppressed, clear or unavailable) is reused for an inbox. */
+export const BRANDLAB_CONTACT_SUPPRESSION_CACHE_MS = 5 * 60 * 1_000;
+/** The longest an enquiry waits for the suppression lookup before it is sent anyway. */
+export const BRANDLAB_CONTACT_SUPPRESSION_TIMEOUT_MS = 2_500;
+const RESEND_SUPPRESSIONS_URL = 'https://api.resend.com/suppressions/';
+/**
+ * An optional full-access Resend key used only for the suppression and domain lookups, so the sending key
+ * (`RESEND_API_KEY`) can stay sending-only. Without it the lookups use `RESEND_API_KEY`.
+ */
+export const BRANDLAB_CONTACT_LOOKUP_API_KEY_ENV = 'RESEND_LOOKUP_API_KEY';
+const MAILBOX_PATTERN = /^[^\s<>,@]+@[^\s<>,@]+\.[^\s<>,@]+$/;
+/** Writes the failure line (the daily monitor's input), then calls the alert hook. False when the hook failed. */
+export async function reportContactDeliveryFailure(failure, alert) {
+    console.error(JSON.stringify({
+        event: failure.event,
+        provider: failure.provider,
+        status: null,
+        code: failure.code,
+        source: failure.source,
+        ...(failure.recipients ? { recipients: failure.recipients } : {}),
+        ...(failure.submission ? { submission: failure.submission } : {}),
+        ...(failure.emailId ? { emailId: failure.emailId } : {}),
+        ...(failure.webhookId ? { webhookId: failure.webhookId } : {}),
+        ...(failure.detail ? { detail: failure.detail } : {}),
+    }));
+    if (!alert)
+        return true;
+    try {
+        await alert(failure);
+        return true;
+    }
+    catch (error) {
+        console.error(JSON.stringify({
+            event: BRANDLAB_CONTACT_DELIVERY_ALERT_FAILED_EVENT,
+            code: failure.code,
+            reason: error instanceof Error ? error.name : 'error',
+        }));
+        return false;
+    }
+}
+async function lookupSuppression(fetcher, address, apiKey, timeoutMs) {
+    let response;
+    try {
+        response = await fetcher(`${RESEND_SUPPRESSIONS_URL}${encodeURIComponent(address)}`, {
+            method: 'GET',
+            headers: { authorization: `Bearer ${apiKey}`, accept: 'application/json' },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch {
+        return { status: 'unknown', code: 'lookup_failed' };
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        body = undefined;
+    }
+    const record = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
+    const name = typeof record.name === 'string' ? record.name.trim().toLowerCase() : '';
+    if (response.ok) {
+        return typeof record.email === 'string' && record.email.trim().toLowerCase() === address
+            ? { status: 'suppressed' }
+            : { status: 'unknown', httpStatus: response.status, code: 'unexpected_answer' };
+    }
+    if (response.status === 404)
+        return { status: 'clear' };
+    return {
+        status: 'unknown',
+        httpStatus: response.status,
+        code: RESEND_ERROR_CODES.has(name) ? name : 'provider_rejected',
+    };
+}
+/**
+ * Asks Resend's suppression list about a business inbox before an enquiry is sent (`GET /suppressions/{email}`).
+ * Answers are reused for the cache window per inbox, so a busy form asks at most once per inbox in that window. Any
+ * error, timeout or refusal answers `unknown` and the enquiry is sent: the check can stop a send it knows is lost,
+ * never one it is unsure about. A refusal is logged once per cache window (a sending-only API key answers 401
+ * `restricted_api_key` and the line names the missing permission: set a full-access key in RESEND_LOOKUP_API_KEY).
+ */
+export function createResendSuppressionCheck(options = {}) {
+    const fetcher = options.fetch ?? ((...args) => globalThis.fetch(...args));
+    const now = options.now ?? Date.now;
+    const cacheMs = options.cacheMs ?? BRANDLAB_CONTACT_SUPPRESSION_CACHE_MS;
+    const timeoutMs = options.timeoutMs ?? BRANDLAB_CONTACT_SUPPRESSION_TIMEOUT_MS;
+    const cache = new Map();
+    return Object.freeze({
+        async check(address, context) {
+            const normalized = typeof address === 'string' ? address.trim().toLowerCase() : '';
+            if (!MAILBOX_PATTERN.test(normalized) || normalized.length > 320 || !context?.apiKey)
+                return 'unknown';
+            const at = now();
+            const cached = cache.get(normalized);
+            if (cached && cached.until > at)
+                return cached.status;
+            let lookup;
+            try {
+                lookup = await lookupSuppression(fetcher, normalized, context.apiKey, timeoutMs);
+            }
+            catch {
+                lookup = { status: 'unknown', code: 'lookup_failed' };
+            }
+            if (lookup.status === 'unknown') {
+                console.warn(JSON.stringify({
+                    event: BRANDLAB_CONTACT_SUPPRESSION_UNAVAILABLE_EVENT,
+                    provider: 'resend',
+                    status: lookup.httpStatus ?? null,
+                    code: lookup.code ?? 'unknown',
+                    ...(lookup.code === 'restricted_api_key' ? { needs: `full-access key (${BRANDLAB_CONTACT_LOOKUP_API_KEY_ENV})` } : {}),
+                }));
+            }
+            if (cache.size > 64)
+                cache.clear();
+            cache.set(normalized, { status: lookup.status, until: at + cacheMs });
+            return lookup.status;
+        },
+    });
+}
+//# sourceMappingURL=delivery.js.map

package/dist/contact/delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.js","sourceRoot":"","sources":["../../src/contact/delivery.ts"],"names":[],"mappings":"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","sourcesContent":["import 'server-only'\n\nimport { RESEND_ERROR_CODES } from './resend.js'\n\n/**\n * Delivery truth for contact enquiries (3.14.0).\n *\n * An enquiry Resend accepts is queued, not delivered: Resend can still bounce it, drop it because the inbox is on the\n * account's suppression list, or have it reported as spam. `contact_form` keeps its analytics-v4 meaning (the provider\n * accepted the enquiry) and is unchanged. Delivery is tracked beside it:\n * - before sending, the business inboxes are checked against Resend's suppression list (`createResendSuppressionCheck`);\n * - after sending, Resend's signed webhook reports delivered, delayed, bounced, complained, suppressed and failed\n *   copies (`createBrandlabResendWebhookRoute`).\n * Every failure writes one `brandlab_contact_delivery_failed` line for the daily delivery monitor and calls the\n * optional alert hook the same moment. No line carries an address, a name, a form value or a key.\n */\n\nexport const BRANDLAB_CONTACT_DELIVERY_FAILED_EVENT = 'brandlab_contact_delivery_failed' as const\nexport const BRANDLAB_CONTACT_DELIVERY_STATUS_EVENT = 'brandlab_contact_delivery_status' as const\nexport const BRANDLAB_CONTACT_SUPPRESSION_UNAVAILABLE_EVENT = 'brandlab_contact_suppression_check_unavailable' as const\nexport const BRANDLAB_CONTACT_DELIVERY_ALERT_FAILED_EVENT = 'brandlab_contact_delivery_alert_failed' as const\n\n/** How long one suppression answer (suppressed, clear or unavailable) is reused for an inbox. */\nexport const BRANDLAB_CONTACT_SUPPRESSION_CACHE_MS = 5 * 60 * 1_000\n/** The longest an enquiry waits for the suppression lookup before it is sent anyway. */\nexport const BRANDLAB_CONTACT_SUPPRESSION_TIMEOUT_MS = 2_500\n\nconst RESEND_SUPPRESSIONS_URL = 'https://api.resend.com/suppressions/'\n\n/**\n * An optional full-access Resend key used only for the suppression and domain lookups, so the sending key\n * (`RESEND_API_KEY`) can stay sending-only. Without it the lookups use `RESEND_API_KEY`.\n */\nexport const BRANDLAB_CONTACT_LOOKUP_API_KEY_ENV = 'RESEND_LOOKUP_API_KEY' as const\nconst MAILBOX_PATTERN = /^[^\\s<>,@]+@[^\\s<>,@]+\\.[^\\s<>,@]+$/\n\n/** `suppressed`: Resend will not deliver to the inbox. `unknown`: the lookup could not tell, so the enquiry is sent. */\nexport type BrandlabContactSuppressionStatus = 'suppressed' | 'clear' | 'unknown'\n\nexport interface BrandlabContactSuppressionCheck {\n  /** Never throws; `unknown` whenever Resend could not be asked or did not answer clearly (fail open). */\n  check(address: string, context: { apiKey: string }): Promise<BrandlabContactSuppressionStatus>\n}\n\nexport type BrandlabContactDeliveryFailureCode =\n  | 'recipient_suppressed'\n  | 'recipient_bounced'\n  | 'recipient_complained'\n  | 'provider_failed'\n\n/** One enquiry copy that did not, or will not, reach a business inbox. Never carries an address or form value. */\nexport interface BrandlabContactDeliveryFailure {\n  event: typeof BRANDLAB_CONTACT_DELIVERY_FAILED_EVENT\n  provider: 'resend'\n  code: BrandlabContactDeliveryFailureCode\n  /** `pre-send`: the suppression check stopped it before sending. `webhook`: Resend reported it after sending. */\n  source: 'pre-send' | 'webhook'\n  /** Pre-send only: whether every business inbox was suppressed (nothing sent) or only some (sent to the rest). */\n  recipients?: 'all' | 'some'\n  /** The first 16 hex characters of the enquiry's confirmation id (the `submission_hash` tag), when known. */\n  submission?: string\n  /** Resend's email id, from the webhook. */\n  emailId?: string\n  /** The webhook's `svix-id`, the same on every retry of one event, for de-duplication. */\n  webhookId?: string\n  /** Resend's bounce type and subtype, suppression type or failure reason, when it gave a plain one. */\n  detail?: string\n  /** When the library saw it (ISO 8601). */\n  at: string\n}\n\n/**\n * A same-day alert hook for delivery failures (email, Slack, a durable store): called once per failure after the log\n * line is written. A hook that throws is logged; the webhook route then answers 500 so Resend retries the event.\n */\nexport type BrandlabContactDeliveryAlert = (failure: BrandlabContactDeliveryFailure) => void | Promise<void>\n\n/** Writes the failure line (the daily monitor's input), then calls the alert hook. False when the hook failed. */\nexport async function reportContactDeliveryFailure(\n  failure: BrandlabContactDeliveryFailure,\n  alert?: BrandlabContactDeliveryAlert,\n): Promise<boolean> {\n  console.error(\n    JSON.stringify({\n      event: failure.event,\n      provider: failure.provider,\n      status: null,\n      code: failure.code,\n      source: failure.source,\n      ...(failure.recipients ? { recipients: failure.recipients } : {}),\n      ...(failure.submission ? { submission: failure.submission } : {}),\n      ...(failure.emailId ? { emailId: failure.emailId } : {}),\n      ...(failure.webhookId ? { webhookId: failure.webhookId } : {}),\n      ...(failure.detail ? { detail: failure.detail } : {}),\n    }),\n  )\n  if (!alert) return true\n  try {\n    await alert(failure)\n    return true\n  } catch (error) {\n    console.error(\n      JSON.stringify({\n        event: BRANDLAB_CONTACT_DELIVERY_ALERT_FAILED_EVENT,\n        code: failure.code,\n        reason: error instanceof Error ? error.name : 'error',\n      }),\n    )\n    return false\n  }\n}\n\nexport interface ResendSuppressionCheckOptions {\n  /** Defaults to the global fetch. */\n  fetch?: typeof globalThis.fetch\n  /** Defaults to `Date.now`. */\n  now?: () => number\n  /** Defaults to BRANDLAB_CONTACT_SUPPRESSION_CACHE_MS. */\n  cacheMs?: number\n  /** Defaults to BRANDLAB_CONTACT_SUPPRESSION_TIMEOUT_MS. */\n  timeoutMs?: number\n}\n\ninterface SuppressionLookup {\n  status: BrandlabContactSuppressionStatus\n  httpStatus?: number\n  code?: string\n}\n\nasync function lookupSuppression(\n  fetcher: typeof globalThis.fetch,\n  address: string,\n  apiKey: string,\n  timeoutMs: number,\n): Promise<SuppressionLookup> {\n  let response: Response\n  try {\n    response = await fetcher(`${RESEND_SUPPRESSIONS_URL}${encodeURIComponent(address)}`, {\n      method: 'GET',\n      headers: { authorization: `Bearer ${apiKey}`, accept: 'application/json' },\n      signal: AbortSignal.timeout(timeoutMs),\n    })\n  } catch {\n    return { status: 'unknown', code: 'lookup_failed' }\n  }\n  let body: unknown\n  try {\n    body = await response.json()\n  } catch {\n    body = undefined\n  }\n  const record = body && typeof body === 'object' && !Array.isArray(body) ? (body as Record<string, unknown>) : {}\n  const name = typeof record.name === 'string' ? record.name.trim().toLowerCase() : ''\n  if (response.ok) {\n    return typeof record.email === 'string' && record.email.trim().toLowerCase() === address\n      ? { status: 'suppressed' }\n      : { status: 'unknown', httpStatus: response.status, code: 'unexpected_answer' }\n  }\n  if (response.status === 404) return { status: 'clear' }\n  return {\n    status: 'unknown',\n    httpStatus: response.status,\n    code: RESEND_ERROR_CODES.has(name) ? name : 'provider_rejected',\n  }\n}\n\n/**\n * Asks Resend's suppression list about a business inbox before an enquiry is sent (`GET /suppressions/{email}`).\n * Answers are reused for the cache window per inbox, so a busy form asks at most once per inbox in that window. Any\n * error, timeout or refusal answers `unknown` and the enquiry is sent: the check can stop a send it knows is lost,\n * never one it is unsure about. A refusal is logged once per cache window (a sending-only API key answers 401\n * `restricted_api_key` and the line names the missing permission: set a full-access key in RESEND_LOOKUP_API_KEY).\n */\nexport function createResendSuppressionCheck(\n  options: ResendSuppressionCheckOptions = {},\n): BrandlabContactSuppressionCheck {\n  const fetcher = options.fetch ?? ((...args: Parameters<typeof globalThis.fetch>) => globalThis.fetch(...args))\n  const now = options.now ?? Date.now\n  const cacheMs = options.cacheMs ?? BRANDLAB_CONTACT_SUPPRESSION_CACHE_MS\n  const timeoutMs = options.timeoutMs ?? BRANDLAB_CONTACT_SUPPRESSION_TIMEOUT_MS\n  const cache = new Map<string, { status: BrandlabContactSuppressionStatus; until: number }>()\n\n  return Object.freeze({\n    async check(address: string, context: { apiKey: string }): Promise<BrandlabContactSuppressionStatus> {\n      const normalized = typeof address === 'string' ? address.trim().toLowerCase() : ''\n      if (!MAILBOX_PATTERN.test(normalized) || normalized.length > 320 || !context?.apiKey) return 'unknown'\n      const at = now()\n      const cached = cache.get(normalized)\n      if (cached && cached.until > at) return cached.status\n      let lookup: SuppressionLookup\n      try {\n        lookup = await lookupSuppression(fetcher, normalized, context.apiKey, timeoutMs)\n      } catch {\n        lookup = { status: 'unknown', code: 'lookup_failed' }\n      }\n      if (lookup.status === 'unknown') {\n        console.warn(\n          JSON.stringify({\n            event: BRANDLAB_CONTACT_SUPPRESSION_UNAVAILABLE_EVENT,\n            provider: 'resend',\n            status: lookup.httpStatus ?? null,\n            code: lookup.code ?? 'unknown',\n            ...(lookup.code === 'restricted_api_key' ? { needs: `full-access key (${BRANDLAB_CONTACT_LOOKUP_API_KEY_ENV})` } : {}),\n          }),\n        )\n      }\n      if (cache.size > 64) cache.clear()\n      cache.set(normalized, { status: lookup.status, until: at + cacheMs })\n      return lookup.status\n    },\n  })\n}\n"]}

package/dist/contact/resend-webhook.d.ts

@@ -0,0 +1,72 @@
+import 'server-only';
+import { type BrandlabContactDeliveryAlert } from './delivery.js';
+import { type BrandlabContactRateLimitRule } from './rate-limit.js';
+/**
+ * The signed Resend webhook route (3.14.0): it learns, the same day, when the business's copy of an enquiry bounced,
+ * was suppressed, was reported as spam or failed, and records each as a delivery failure. Serve it at
+ * `src/app/api/brandlab/resend-webhook/route.ts`:
+ *
+ * ```ts
+ * import { createBrandlabResendWebhookRoute } from '@brandlab-digital/site-next/contact/server'
+ * import { contactContract } from '@/config/contact'
+ *
+ * export const { POST } = createBrandlabResendWebhookRoute({ projectId: contactContract.projectId })
+ * ```
+ *
+ * Resend signs every event with Svix (`svix-id`, `svix-timestamp`, `svix-signature`): HMAC-SHA256 over
+ * `<svix-id>.<svix-timestamp>.<raw body>` keyed with the base64 part of the endpoint's `whsec_` signing secret, held in
+ * `RESEND_WEBHOOK_SECRET` and never logged. Webhooks are account-wide, so the route records only the emails this site's
+ * contact route sent (their `project_id` tag) and answers 200 to everything else so Resend stops retrying it.
+ *
+ * Answers: 200 `{ ok: true, recorded }` (`duplicate: true` for a retry this instance already recorded); 400 for an
+ * unreadable body; 401 for a missing or wrong signature or a timestamp more than 5 minutes off; 413 for a body over
+ * 256 KB; 429 with `Retry-After` once one client IP (`x-real-ip`) has failed those checks past the rate limit; 503 when
+ * the secret is not set; 500 when the alert hook failed (Resend retries).
+ *
+ * Retries are de-duplicated by `svix-id` in a small in-memory list per server instance: best effort only, so the daily
+ * monitor still de-duplicates on `webhookId`. Only failed attempts count towards the rate limit, so Resend's correctly
+ * signed requests are never refused with 429, and without `x-real-ip` nothing is rate-limited.
+ */
+export declare const BRANDLAB_RESEND_WEBHOOK_SECRET_ENV: "RESEND_WEBHOOK_SECRET";
+/** Failed attempts (bad signature, stale timestamp, oversized body) per client IP before the route answers 429. */
+export declare const BRANDLAB_RESEND_WEBHOOK_RATE_LIMIT: Readonly<{
+    limit: 10;
+    windowMs: number;
+}>;
+export interface BrandlabResendWebhookRouteOptions {
+    /** The contact contract's canonical project id; only emails tagged with it are recorded. */
+    projectId: string;
+    /** Defaults to `process.env`, read on each request: `RESEND_WEBHOOK_SECRET` (the endpoint's `whsec_` secret). */
+    environment?: Readonly<Record<string, string | undefined>>;
+    /** The same-day alert for a bounced, suppressed, complained or failed business copy. */
+    onDeliveryFailure?: BrandlabContactDeliveryAlert;
+    /**
+     * Failed attempts per client IP (`x-real-ip`) before the route answers 429, held in memory per server instance
+     * (BRANDLAB_RESEND_WEBHOOK_RATE_LIMIT by default); `false` turns it off. Correctly signed requests never count.
+     */
+    rateLimit?: BrandlabContactRateLimitRule | false;
+    /** Defaults to `Date.now`. */
+    now?: () => number;
+}
+export interface BrandlabResendWebhookRoute {
+    POST(request: Request): Promise<Response>;
+}
+/**
+ * Verifies a Resend (Svix) webhook signature: one `v1,<base64>` entry in the space-separated `svix-signature` list must
+ * equal HMAC-SHA256 of `<id>.<timestamp>.<body>`, and the timestamp must be within 5 minutes of `now` (milliseconds).
+ */
+export declare function verifyResendWebhookSignature(input: {
+    secret: string;
+    id: string;
+    timestamp: string;
+    signature: string;
+    body: string;
+    now: number;
+}): Promise<boolean>;
+/**
+ * Creates the signed Resend webhook route for one site. Create it once at module level. In Resend, add a webhook to
+ * `https://<site>/api/brandlab/resend-webhook` with the email events (at least delivered, delivery delayed, bounced,
+ * complained, suppressed and failed) and copy its signing secret into `RESEND_WEBHOOK_SECRET`.
+ */
+export declare function createBrandlabResendWebhookRoute(options: BrandlabResendWebhookRouteOptions): BrandlabResendWebhookRoute;
+//# sourceMappingURL=resend-webhook.d.ts.map

package/dist/contact/resend-webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resend-webhook.d.ts","sourceRoot":"","sources":["../../src/contact/resend-webhook.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,CAAA;AAGpB,OAAO,EAIL,KAAK,4BAA4B,EAElC,MAAM,eAAe,CAAA;AACtB,OAAO,EAAoC,KAAK,4BAA4B,EAAE,MAAM,iBAAiB,CAAA;AAGrG;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,eAAO,MAAM,kCAAkC,EAAG,uBAAgC,CAAA;AAWlF,mHAAmH;AACnH,eAAO,MAAM,kCAAkC;;;EAA0D,CAAA;AAazG,MAAM,WAAW,iCAAiC;IAChD,4FAA4F;IAC5F,SAAS,EAAE,MAAM,CAAA;IACjB,iHAAiH;IACjH,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;IAC1D,wFAAwF;IACxF,iBAAiB,CAAC,EAAE,4BAA4B,CAAA;IAChD;;;OAGG;IACH,SAAS,CAAC,EAAE,4BAA4B,GAAG,KAAK,CAAA;IAChD,8BAA8B;IAC9B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC1C;AAgDD;;;GAGG;AACH,wBAAsB,4BAA4B,CAAC,KAAK,EAAE;IACxD,MAAM,EAAE,MAAM,CAAA;IACd,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;CACZ,GAAG,OAAO,CAAC,OAAO,CAAC,CAmBnB;AA4DD;;;;GAIG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,iCAAiC,GACzC,0BAA0B,CAqH5B"}