@automate.ax/integration-contracts 0.55.0

package/src/brevo/api.ts

@@ -0,0 +1,89 @@
+import { z } from "zod"
+
+const BREVO_API_BASE_URL = "https://api.brevo.com/v3/"
+const BREVO_API_ORIGIN = new URL(BREVO_API_BASE_URL).origin
+const BREVO_SECRET_SCHEMA = z.object({
+  apiKey: z.string().min(1),
+})
+const BREVO_ERROR_SCHEMA = z.looseObject({
+  code: z.string().optional(),
+  message: z.string().optional(),
+})
+
+/** Options accepted by the authenticated Brevo request helper. */
+export interface BrevoRequestOptions extends RequestInit {
+  /** Query parameters appended to the request URL. */
+  query?: Record<
+    string,
+    boolean | number | readonly (number | string)[] | string | undefined
+  >
+}
+
+/**
+ * Creates a small authenticated Brevo REST client.
+ *
+ * The returned helper is an escape hatch for provider endpoints that do not yet
+ * have a dedicated action. It returns the native `Response` after checking for
+ * provider errors.
+ *
+ * @param secret - Resolved Brevo integration secret.
+ */
+export function getBrevoApi(secret: Record<string, unknown>) {
+  const { apiKey } = BREVO_SECRET_SCHEMA.parse(secret)
+
+  return {
+    /**
+     * Sends an authenticated request to the Brevo v3 API.
+     *
+     * @param path - Relative API path.
+     * @param options - Native fetch options and optional query parameters.
+     */
+    async request(path: string, options: BrevoRequestOptions = {}) {
+      const { query, ...requestInit } = options
+      const url = new URL(path.replace(/^\//, ""), BREVO_API_BASE_URL)
+      if (url.origin !== BREVO_API_ORIGIN) {
+        throw new Error("Brevo API paths must use the Brevo API origin.")
+      }
+      for (const [name, value] of Object.entries(query ?? {})) {
+        if (value !== undefined) {
+          url.searchParams.set(
+            name,
+            Array.isArray(value) ? value.join(",") : String(value),
+          )
+        }
+      }
+
+      const headers = new Headers(requestInit.headers)
+      headers.set("api-key", apiKey)
+      headers.set("Accept", "application/json")
+      if (requestInit.body !== undefined && !headers.has("Content-Type")) {
+        headers.set("Content-Type", "application/json")
+      }
+
+      const response = await fetch(url, { ...requestInit, headers })
+      if (response.ok) return response
+
+      const error = BREVO_ERROR_SCHEMA.safeParse(
+        await response.json().catch(() => ({})),
+      )
+      throw new Error(
+        error.success && error.data.message
+          ? `Brevo API error (${response.status}): ${error.data.message}`
+          : `Brevo API request failed with status ${response.status}.`,
+      )
+    },
+  }
+}
+
+/**
+ * Parses one successful Brevo JSON response.
+ *
+ * @param response - Checked provider response.
+ * @param schema - Schema describing the provider response.
+ */
+export async function parseBrevoResponse<T extends z.ZodType>(
+  response: Response,
+  schema: T,
+): Promise<z.output<T>> {
+  return schema.parse(await response.json())
+}

package/src/brevo/index.ts

@@ -0,0 +1,66 @@
+import { z } from "zod"
+import {
+  BREVO_EMAIL_BLOCKED_EVENT_SCHEMA,
+  BREVO_EMAIL_CLICKED_EVENT_SCHEMA,
+  BREVO_EMAIL_DEFERRED_EVENT_SCHEMA,
+  BREVO_EMAIL_DELIVERED_EVENT_SCHEMA,
+  BREVO_EMAIL_HARD_BOUNCED_EVENT_SCHEMA,
+  BREVO_EMAIL_MARKED_AS_SPAM_EVENT_SCHEMA,
+  BREVO_EMAIL_OPENED_EVENT_SCHEMA,
+  BREVO_EMAIL_SENT_EVENT_SCHEMA,
+  BREVO_EMAIL_SOFT_BOUNCED_EVENT_SCHEMA,
+  BREVO_EMAIL_UNSUBSCRIBED_EVENT_SCHEMA,
+  BREVO_TRANSACTIONAL_EVENT_SCHEMA,
+} from "./schemas"
+
+export * from "./api"
+export * from "./schemas"
+
+export const BREVO_TRIGGER_CONFIG_SCHEMA = z.object({})
+
+export const brevoTriggerContracts = {
+  "brevo.transactional.blocked": {
+    configSchema: BREVO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: BREVO_EMAIL_BLOCKED_EVENT_SCHEMA,
+  },
+  "brevo.transactional.clicked": {
+    configSchema: BREVO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: BREVO_EMAIL_CLICKED_EVENT_SCHEMA,
+  },
+  "brevo.transactional.deferred": {
+    configSchema: BREVO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: BREVO_EMAIL_DEFERRED_EVENT_SCHEMA,
+  },
+  "brevo.transactional.delivered": {
+    configSchema: BREVO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: BREVO_EMAIL_DELIVERED_EVENT_SCHEMA,
+  },
+  "brevo.transactional.event": {
+    configSchema: BREVO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: BREVO_TRANSACTIONAL_EVENT_SCHEMA,
+  },
+  "brevo.transactional.hardBounced": {
+    configSchema: BREVO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: BREVO_EMAIL_HARD_BOUNCED_EVENT_SCHEMA,
+  },
+  "brevo.transactional.markedAsSpam": {
+    configSchema: BREVO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: BREVO_EMAIL_MARKED_AS_SPAM_EVENT_SCHEMA,
+  },
+  "brevo.transactional.opened": {
+    configSchema: BREVO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: BREVO_EMAIL_OPENED_EVENT_SCHEMA,
+  },
+  "brevo.transactional.sent": {
+    configSchema: BREVO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: BREVO_EMAIL_SENT_EVENT_SCHEMA,
+  },
+  "brevo.transactional.softBounced": {
+    configSchema: BREVO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: BREVO_EMAIL_SOFT_BOUNCED_EVENT_SCHEMA,
+  },
+  "brevo.transactional.unsubscribed": {
+    configSchema: BREVO_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: BREVO_EMAIL_UNSUBSCRIBED_EVENT_SCHEMA,
+  },
+} as const

package/src/brevo/schemas.ts

@@ -0,0 +1,449 @@
+import { z } from "zod"
+
+export const BREVO_TRANSACTIONAL_EVENT_TYPES = [
+  "blocked",
+  "click",
+  "deferred",
+  "delivered",
+  "error",
+  "hard_bounce",
+  "invalid_email",
+  "opened",
+  "request",
+  "soft_bounce",
+  "spam",
+  "unique_opened",
+  "unsubscribed",
+] as const
+
+const BREVO_PROVIDER_EVENT_BASE_SCHEMA = z
+  .looseObject({
+    /** Custom header supplied with the original email. */
+    "X-Mailin-custom": z.string().optional(),
+
+    /** Provider-local formatted date for the event. */
+    date: z.string().optional(),
+
+    /** Recipient email address. */
+    email: z.string().optional(),
+
+    /** Brevo webhook ID that delivered the event. */
+    id: z.number().int().nonnegative(),
+
+    /** Provider message identity. */
+    "message-id": z.string().optional(),
+
+    /** Email subject. */
+    subject: z.string().optional(),
+
+    /** Tags supplied with the original email. */
+    tags: z.string().array().optional(),
+
+    /** Internal template ID used to send the email. */
+    template_id: z.number().int().nonnegative().optional(),
+
+    /** Unix timestamp in seconds for the underlying email event. */
+    ts: z.number().int().nonnegative().optional(),
+
+    /** Unix timestamp in seconds when Brevo emitted the webhook event. */
+    ts_event: z.number().int().nonnegative(),
+  })
+  .catchall(z.json())
+
+const BREVO_PROVIDER_DELIVERY_METADATA_SCHEMA = z.object({
+  /** Sending IP used for the message. */
+  sending_ip: z.string().optional(),
+
+  /** Provider timestamp in milliseconds. */
+  ts_epoch: z.number().int().nonnegative().optional(),
+})
+
+const BREVO_PROVIDER_ENGAGEMENT_METADATA_SCHEMA = z.object({
+  /** Brevo contact ID, or zero when the recipient is not a contact. */
+  contact_id: z.number().int().nonnegative().optional(),
+
+  /** Device category reported for the interaction. */
+  device_used: z.string().optional(),
+
+  /** Brevo log preview URL. */
+  mirror_link: z.string().optional(),
+
+  /** Browser or email-client user agent. */
+  user_agent: z.string().optional(),
+})
+
+const BREVO_PROVIDER_SENT_EVENT_SCHEMA =
+  BREVO_PROVIDER_EVENT_BASE_SCHEMA.extend({
+    ...BREVO_PROVIDER_DELIVERY_METADATA_SCHEMA.shape,
+    ...BREVO_PROVIDER_ENGAGEMENT_METADATA_SCHEMA.pick({
+      contact_id: true,
+      mirror_link: true,
+    }).shape,
+    event: z.literal("request"),
+  })
+
+const BREVO_PROVIDER_DELIVERED_EVENT_SCHEMA =
+  BREVO_PROVIDER_EVENT_BASE_SCHEMA.extend({
+    ...BREVO_PROVIDER_DELIVERY_METADATA_SCHEMA.shape,
+    event: z.literal("delivered"),
+  })
+
+const BREVO_PROVIDER_HARD_BOUNCED_EVENT_SCHEMA =
+  BREVO_PROVIDER_EVENT_BASE_SCHEMA.extend({
+    ...BREVO_PROVIDER_DELIVERY_METADATA_SCHEMA.shape,
+    event: z.literal("hard_bounce"),
+    reason: z.string().optional(),
+  })
+
+const BREVO_PROVIDER_SOFT_BOUNCED_EVENT_SCHEMA =
+  BREVO_PROVIDER_EVENT_BASE_SCHEMA.extend({
+    ...BREVO_PROVIDER_DELIVERY_METADATA_SCHEMA.shape,
+    event: z.literal("soft_bounce"),
+    reason: z.string().optional(),
+  })
+
+const BREVO_PROVIDER_BLOCKED_EVENT_SCHEMA =
+  BREVO_PROVIDER_EVENT_BASE_SCHEMA.extend({
+    event: z.literal("blocked"),
+    ts_epoch: z.number().int().nonnegative().optional(),
+  })
+
+const BREVO_PROVIDER_DEFERRED_EVENT_SCHEMA =
+  BREVO_PROVIDER_EVENT_BASE_SCHEMA.extend({
+    ...BREVO_PROVIDER_DELIVERY_METADATA_SCHEMA.shape,
+    event: z.literal("deferred"),
+    reason: z.string().optional(),
+  })
+
+const BREVO_PROVIDER_OPENED_EVENT_SCHEMA =
+  BREVO_PROVIDER_EVENT_BASE_SCHEMA.extend({
+    ...BREVO_PROVIDER_DELIVERY_METADATA_SCHEMA.shape,
+    ...BREVO_PROVIDER_ENGAGEMENT_METADATA_SCHEMA.shape,
+    event: z.literal("opened"),
+  })
+
+const BREVO_PROVIDER_UNIQUE_OPENED_EVENT_SCHEMA =
+  BREVO_PROVIDER_EVENT_BASE_SCHEMA.extend({
+    ...BREVO_PROVIDER_DELIVERY_METADATA_SCHEMA.shape,
+    ...BREVO_PROVIDER_ENGAGEMENT_METADATA_SCHEMA.shape,
+    event: z.literal("unique_opened"),
+  })
+
+const BREVO_PROVIDER_CLICKED_EVENT_SCHEMA =
+  BREVO_PROVIDER_EVENT_BASE_SCHEMA.extend({
+    ...BREVO_PROVIDER_DELIVERY_METADATA_SCHEMA.shape,
+    ...BREVO_PROVIDER_ENGAGEMENT_METADATA_SCHEMA.shape,
+    event: z.literal("click"),
+    link: z.string().optional(),
+  })
+
+const BREVO_PROVIDER_SPAM_EVENT_SCHEMA =
+  BREVO_PROVIDER_EVENT_BASE_SCHEMA.extend({ event: z.literal("spam") })
+
+const BREVO_PROVIDER_UNSUBSCRIBED_EVENT_SCHEMA =
+  BREVO_PROVIDER_EVENT_BASE_SCHEMA.extend({
+    ...BREVO_PROVIDER_DELIVERY_METADATA_SCHEMA.shape,
+    ...BREVO_PROVIDER_ENGAGEMENT_METADATA_SCHEMA.shape,
+    event: z.literal("unsubscribed"),
+    tag: z.string().optional(),
+  })
+
+const BREVO_PROVIDER_INVALID_EMAIL_EVENT_SCHEMA =
+  BREVO_PROVIDER_EVENT_BASE_SCHEMA.extend({
+    event: z.literal("invalid_email"),
+    ts_epoch: z.number().int().nonnegative().optional(),
+  })
+
+const BREVO_PROVIDER_ERROR_EVENT_SCHEMA =
+  BREVO_PROVIDER_EVENT_BASE_SCHEMA.extend({
+    event: z.literal("error"),
+    ts_epoch: z.number().int().nonnegative().optional(),
+  })
+
+const BREVO_PROVIDER_TRANSACTIONAL_EVENT_SCHEMA = z.discriminatedUnion(
+  "event",
+  [
+    BREVO_PROVIDER_BLOCKED_EVENT_SCHEMA,
+    BREVO_PROVIDER_CLICKED_EVENT_SCHEMA,
+    BREVO_PROVIDER_DEFERRED_EVENT_SCHEMA,
+    BREVO_PROVIDER_DELIVERED_EVENT_SCHEMA,
+    BREVO_PROVIDER_ERROR_EVENT_SCHEMA,
+    BREVO_PROVIDER_HARD_BOUNCED_EVENT_SCHEMA,
+    BREVO_PROVIDER_INVALID_EMAIL_EVENT_SCHEMA,
+    BREVO_PROVIDER_OPENED_EVENT_SCHEMA,
+    BREVO_PROVIDER_SENT_EVENT_SCHEMA,
+    BREVO_PROVIDER_SOFT_BOUNCED_EVENT_SCHEMA,
+    BREVO_PROVIDER_SPAM_EVENT_SCHEMA,
+    BREVO_PROVIDER_UNIQUE_OPENED_EVENT_SCHEMA,
+    BREVO_PROVIDER_UNSUBSCRIBED_EVENT_SCHEMA,
+  ],
+)
+
+const BREVO_EVENT_BASE_SCHEMA = z.object({
+  /** Custom header supplied with the original email. */
+  customHeader: z.string().optional(),
+
+  /** Provider-local formatted date for the event. */
+  date: z.string().optional(),
+
+  /** Recipient email address. */
+  email: z.string().optional(),
+
+  /** Provider message identity. */
+  messageId: z.string().optional(),
+
+  /** Unix timestamp in seconds when Brevo emitted the webhook event. */
+  occurredAt: z.number().int().nonnegative(),
+
+  /** Email subject. */
+  subject: z.string().optional(),
+
+  /** Tags supplied with the original email. */
+  tags: z.string().array().optional(),
+
+  /** Internal template ID used to send the email. */
+  templateId: z.number().int().nonnegative().optional(),
+
+  /** Unix timestamp in seconds for the underlying email event. */
+  timestamp: z.number().int().nonnegative().optional(),
+
+  /** Brevo webhook ID that delivered the event. */
+  webhookId: z.number().int().nonnegative(),
+})
+
+const BREVO_DELIVERY_METADATA_SCHEMA = z.object({
+  /** Sending IP used for the message. */
+  sendingIp: z.string().optional(),
+
+  /** Provider timestamp in milliseconds. */
+  timestampMilliseconds: z.number().int().nonnegative().optional(),
+})
+
+const BREVO_ENGAGEMENT_METADATA_SCHEMA = z.object({
+  /** Brevo contact ID, or zero when the recipient is not a contact. */
+  contactId: z.number().int().nonnegative().optional(),
+
+  /** Device category reported for the interaction. */
+  deviceUsed: z.string().optional(),
+
+  /** Brevo log preview URL. */
+  mirrorLink: z.string().optional(),
+
+  /** Browser or email-client user agent. */
+  userAgent: z.string().optional(),
+})
+
+export const BREVO_EMAIL_SENT_EVENT_SCHEMA = BREVO_EVENT_BASE_SCHEMA.extend({
+  ...BREVO_DELIVERY_METADATA_SCHEMA.shape,
+  ...BREVO_ENGAGEMENT_METADATA_SCHEMA.pick({
+    contactId: true,
+    mirrorLink: true,
+  }).shape,
+
+  /** Original provider webhook payload. */
+  event: BREVO_PROVIDER_SENT_EVENT_SCHEMA,
+
+  /** Brevo transactional event category. */
+  type: z.literal("request"),
+})
+
+export const BREVO_EMAIL_DELIVERED_EVENT_SCHEMA =
+  BREVO_EVENT_BASE_SCHEMA.extend({
+    ...BREVO_DELIVERY_METADATA_SCHEMA.shape,
+
+    /** Original provider webhook payload. */
+    event: BREVO_PROVIDER_DELIVERED_EVENT_SCHEMA,
+
+    /** Brevo transactional event category. */
+    type: z.literal("delivered"),
+  })
+
+export const BREVO_EMAIL_HARD_BOUNCED_EVENT_SCHEMA =
+  BREVO_EVENT_BASE_SCHEMA.extend({
+    ...BREVO_DELIVERY_METADATA_SCHEMA.shape,
+
+    /** Original provider webhook payload. */
+    event: BREVO_PROVIDER_HARD_BOUNCED_EVENT_SCHEMA,
+
+    /** Provider explanation for the permanent delivery failure. */
+    reason: z.string().optional(),
+
+    /** Brevo transactional event category. */
+    type: z.literal("hard_bounce"),
+  })
+
+export const BREVO_EMAIL_SOFT_BOUNCED_EVENT_SCHEMA =
+  BREVO_EVENT_BASE_SCHEMA.extend({
+    ...BREVO_DELIVERY_METADATA_SCHEMA.shape,
+
+    /** Original provider webhook payload. */
+    event: BREVO_PROVIDER_SOFT_BOUNCED_EVENT_SCHEMA,
+
+    /** Provider explanation for the temporary delivery failure. */
+    reason: z.string().optional(),
+
+    /** Brevo transactional event category. */
+    type: z.literal("soft_bounce"),
+  })
+
+export const BREVO_EMAIL_BLOCKED_EVENT_SCHEMA = BREVO_EVENT_BASE_SCHEMA.extend({
+  /** Original provider webhook payload. */
+  event: BREVO_PROVIDER_BLOCKED_EVENT_SCHEMA,
+
+  /** Provider timestamp in milliseconds. */
+  timestampMilliseconds: z.number().int().nonnegative().optional(),
+
+  /** Brevo transactional event category. */
+  type: z.literal("blocked"),
+})
+
+export const BREVO_EMAIL_DEFERRED_EVENT_SCHEMA = BREVO_EVENT_BASE_SCHEMA.extend(
+  {
+    ...BREVO_DELIVERY_METADATA_SCHEMA.shape,
+
+    /** Original provider webhook payload. */
+    event: BREVO_PROVIDER_DEFERRED_EVENT_SCHEMA,
+
+    /** Provider explanation for the delayed delivery attempt. */
+    reason: z.string().optional(),
+
+    /** Brevo transactional event category. */
+    type: z.literal("deferred"),
+  },
+)
+
+const BREVO_EMAIL_OPENED_EVENT_MEMBER_SCHEMA = BREVO_EVENT_BASE_SCHEMA.extend({
+  ...BREVO_DELIVERY_METADATA_SCHEMA.shape,
+  ...BREVO_ENGAGEMENT_METADATA_SCHEMA.shape,
+
+  /** Original provider webhook payload. */
+  event: BREVO_PROVIDER_OPENED_EVENT_SCHEMA,
+
+  /** Brevo transactional event category. */
+  type: z.literal("opened"),
+})
+
+const BREVO_EMAIL_UNIQUE_OPENED_EVENT_MEMBER_SCHEMA =
+  BREVO_EVENT_BASE_SCHEMA.extend({
+    ...BREVO_DELIVERY_METADATA_SCHEMA.shape,
+    ...BREVO_ENGAGEMENT_METADATA_SCHEMA.shape,
+
+    /** Original provider webhook payload. */
+    event: BREVO_PROVIDER_UNIQUE_OPENED_EVENT_SCHEMA,
+
+    /** Brevo transactional event category. */
+    type: z.literal("unique_opened"),
+  })
+
+export const BREVO_EMAIL_OPENED_EVENT_SCHEMA = z.discriminatedUnion("type", [
+  BREVO_EMAIL_OPENED_EVENT_MEMBER_SCHEMA,
+  BREVO_EMAIL_UNIQUE_OPENED_EVENT_MEMBER_SCHEMA,
+])
+
+export const BREVO_EMAIL_CLICKED_EVENT_SCHEMA = BREVO_EVENT_BASE_SCHEMA.extend({
+  ...BREVO_DELIVERY_METADATA_SCHEMA.shape,
+  ...BREVO_ENGAGEMENT_METADATA_SCHEMA.shape,
+
+  /** Original provider webhook payload. */
+  event: BREVO_PROVIDER_CLICKED_EVENT_SCHEMA,
+
+  /** URL followed by the recipient. */
+  link: z.string().optional(),
+
+  /** Brevo transactional event category. */
+  type: z.literal("click"),
+})
+
+export const BREVO_EMAIL_MARKED_AS_SPAM_EVENT_SCHEMA =
+  BREVO_EVENT_BASE_SCHEMA.extend({
+    /** Original provider webhook payload. */
+    event: BREVO_PROVIDER_SPAM_EVENT_SCHEMA,
+
+    /** Brevo transactional event category. */
+    type: z.literal("spam"),
+  })
+
+export const BREVO_EMAIL_UNSUBSCRIBED_EVENT_SCHEMA =
+  BREVO_EVENT_BASE_SCHEMA.extend({
+    ...BREVO_DELIVERY_METADATA_SCHEMA.shape,
+    ...BREVO_ENGAGEMENT_METADATA_SCHEMA.shape,
+
+    /** Original provider webhook payload. */
+    event: BREVO_PROVIDER_UNSUBSCRIBED_EVENT_SCHEMA,
+
+    /** Provider-native serialized tag value for the unsubscribe. */
+    tag: z.string().optional(),
+
+    /** Brevo transactional event category. */
+    type: z.literal("unsubscribed"),
+  })
+
+const BREVO_INVALID_EMAIL_EVENT_SCHEMA = BREVO_EVENT_BASE_SCHEMA.extend({
+  /** Original provider webhook payload. */
+  event: BREVO_PROVIDER_INVALID_EMAIL_EVENT_SCHEMA,
+
+  /** Provider timestamp in milliseconds. */
+  timestampMilliseconds: z.number().int().nonnegative().optional(),
+
+  /** Brevo transactional event category. */
+  type: z.literal("invalid_email"),
+})
+
+const BREVO_ERROR_EVENT_SCHEMA = BREVO_EVENT_BASE_SCHEMA.extend({
+  /** Original provider webhook payload. */
+  event: BREVO_PROVIDER_ERROR_EVENT_SCHEMA,
+
+  /** Provider timestamp in milliseconds. */
+  timestampMilliseconds: z.number().int().nonnegative().optional(),
+
+  /** Brevo transactional event category. */
+  type: z.literal("error"),
+})
+
+export const BREVO_TRANSACTIONAL_EVENT_SCHEMA = z.discriminatedUnion("type", [
+  BREVO_EMAIL_BLOCKED_EVENT_SCHEMA,
+  BREVO_EMAIL_CLICKED_EVENT_SCHEMA,
+  BREVO_EMAIL_DEFERRED_EVENT_SCHEMA,
+  BREVO_EMAIL_DELIVERED_EVENT_SCHEMA,
+  BREVO_ERROR_EVENT_SCHEMA,
+  BREVO_EMAIL_HARD_BOUNCED_EVENT_SCHEMA,
+  BREVO_INVALID_EMAIL_EVENT_SCHEMA,
+  BREVO_EMAIL_OPENED_EVENT_MEMBER_SCHEMA,
+  BREVO_EMAIL_SENT_EVENT_SCHEMA,
+  BREVO_EMAIL_SOFT_BOUNCED_EVENT_SCHEMA,
+  BREVO_EMAIL_MARKED_AS_SPAM_EVENT_SCHEMA,
+  BREVO_EMAIL_UNIQUE_OPENED_EVENT_MEMBER_SCHEMA,
+  BREVO_EMAIL_UNSUBSCRIBED_EVENT_SCHEMA,
+])
+
+/**
+ * Normalizes one provider-native Brevo transactional webhook.
+ *
+ * @param value - Untrusted provider webhook payload.
+ */
+export function normalizeBrevoTransactionalEvent(value: unknown) {
+  const event = BREVO_PROVIDER_TRANSACTIONAL_EVENT_SCHEMA.parse(value)
+  return BREVO_TRANSACTIONAL_EVENT_SCHEMA.parse({
+    contactId: event.contact_id,
+    customHeader: event["X-Mailin-custom"],
+    date: event.date,
+    deviceUsed: event.device_used,
+    email: event.email,
+    event,
+    link: event.link,
+    messageId: event["message-id"],
+    mirrorLink: event.mirror_link,
+    occurredAt: event.ts_event,
+    reason: event.reason,
+    sendingIp: event.sending_ip,
+    subject: event.subject,
+    tag: event.tag,
+    tags: event.tags,
+    templateId: event.template_id,
+    timestamp: event.ts,
+    timestampMilliseconds: event.ts_epoch,
+    type: event.event,
+    userAgent: event.user_agent,
+    webhookId: event.id,
+  })
+}