@automate.ax/integration-contracts 0.98.0 → 0.99.0

package/src/resend/action-schemas.ts

@@ -0,0 +1,430 @@
+import * as z from "zod"
+
+export const RESEND_EMAIL_STATUS_SCHEMA = z.enum([
+  "bounced",
+  "canceled",
+  "clicked",
+  "complained",
+  "delivered",
+  "delivery_delayed",
+  "failed",
+  "opened",
+  "queued",
+  "scheduled",
+  "sent",
+  "suppressed",
+])
+
+export const RESEND_TAG_SCHEMA = z.object({
+  name: z.string(),
+  value: z.string(),
+})
+
+export const RESEND_ID_RESPONSE_SCHEMA = z.object({ id: z.string().min(1) })
+
+export const RESEND_MUTATION_RESPONSE_SCHEMA = z.object({
+  id: z.string().min(1),
+  object: z.string(),
+})
+
+export const RESEND_EMAIL_MUTATION_RESPONSE_SCHEMA = z.object({
+  id: z.string().min(1),
+  object: z.literal("email"),
+})
+
+export const RESEND_CONTACT_MUTATION_RESPONSE_SCHEMA = z.object({
+  id: z.string().min(1),
+  object: z.literal("contact"),
+})
+
+export const RESEND_CONTACT_IMPORT_MUTATION_RESPONSE_SCHEMA = z.object({
+  id: z.string().min(1),
+  object: z.literal("contact_import"),
+})
+
+export const RESEND_EVENT_MUTATION_RESPONSE_SCHEMA = z.object({
+  id: z.string().min(1),
+  object: z.literal("event"),
+})
+
+export const RESEND_CONTACT_DELETE_RESPONSE_SCHEMA =
+  RESEND_CONTACT_MUTATION_RESPONSE_SCHEMA.extend({ deleted: z.boolean() })
+
+export const RESEND_EVENT_DELETE_RESPONSE_SCHEMA =
+  RESEND_EVENT_MUTATION_RESPONSE_SCHEMA.extend({ deleted: z.boolean() })
+
+export const RESEND_DELETE_RESPONSE_SCHEMA =
+  RESEND_MUTATION_RESPONSE_SCHEMA.extend({ deleted: z.boolean() })
+
+export const RESEND_EMAIL_SUMMARY_WIRE_SCHEMA = z.object({
+  bcc: z.string().array().nullable().optional(),
+  cc: z.string().array().nullable().optional(),
+  created_at: z.string(),
+  from: z.string(),
+  id: z.string(),
+  last_event: RESEND_EMAIL_STATUS_SCHEMA,
+  message_id: z.string().nullable().optional(),
+  reply_to: z.string().array().nullable().optional(),
+  scheduled_at: z.string().nullable().optional(),
+  subject: z.string(),
+  to: z.string().array(),
+  topic_id: z.string().nullable().optional(),
+})
+
+export const RESEND_EMAIL_SUMMARY_SCHEMA =
+  RESEND_EMAIL_SUMMARY_WIRE_SCHEMA.transform(
+    ({
+      created_at: createdAt,
+      last_event: lastEvent,
+      message_id: messageId,
+      reply_to: replyTo,
+      scheduled_at: scheduledAt,
+      topic_id: topicId,
+      ...email
+    }) => ({
+      ...email,
+      createdAt,
+      lastEvent,
+      messageId,
+      replyTo,
+      scheduledAt,
+      topicId,
+    }),
+  )
+
+export const RESEND_EMAIL_WIRE_SCHEMA = RESEND_EMAIL_SUMMARY_WIRE_SCHEMA.extend(
+  {
+    bcc: z.string().array().nullable().optional(),
+    cc: z.string().array().nullable().optional(),
+    html: z.string().nullable().optional(),
+    object: z.literal("email"),
+    reply_to: z.string().array().nullable().optional(),
+    tags: RESEND_TAG_SCHEMA.array().optional(),
+    text: z.string().nullable().optional(),
+  },
+)
+
+export const RESEND_EMAIL_SCHEMA = RESEND_EMAIL_WIRE_SCHEMA.transform(
+  ({
+    created_at: createdAt,
+    last_event: lastEvent,
+    message_id: messageId,
+    reply_to: replyTo,
+    scheduled_at: scheduledAt,
+    topic_id: topicId,
+    ...email
+  }) => ({
+    ...email,
+    createdAt,
+    lastEvent,
+    messageId,
+    replyTo,
+    scheduledAt,
+    topicId,
+  }),
+)
+
+export const RESEND_ATTACHMENT_WIRE_SCHEMA = z.object({
+  content_disposition: z.enum(["attachment", "inline"]).nullable(),
+  content_id: z.string(),
+  content_type: z.string(),
+  download_url: z.url(),
+  expires_at: z.string(),
+  filename: z.string().nullable(),
+  id: z.string(),
+  size: z.number().int().nonnegative(),
+})
+
+export const RESEND_ATTACHMENT_SCHEMA = RESEND_ATTACHMENT_WIRE_SCHEMA.transform(
+  ({
+    content_disposition: contentDisposition,
+    content_id: contentId,
+    content_type: contentType,
+    download_url: downloadUrl,
+    expires_at: expiresAt,
+    ...attachment
+  }) => ({
+    ...attachment,
+    contentDisposition,
+    contentId,
+    contentType,
+    downloadUrl,
+    expiresAt,
+  }),
+)
+
+const RESEND_RECEIVED_ATTACHMENT_WIRE_SCHEMA = z.object({
+  content_disposition: z.string().nullable(),
+  content_id: z.string().nullable(),
+  content_type: z.string(),
+  filename: z.string().nullable(),
+  id: z.string(),
+  size: z.number().int().nonnegative(),
+})
+
+const RESEND_RECEIVED_ATTACHMENT_SCHEMA =
+  RESEND_RECEIVED_ATTACHMENT_WIRE_SCHEMA.transform(
+    ({
+      content_disposition: contentDisposition,
+      content_id: contentId,
+      content_type: contentType,
+      ...attachment
+    }) => ({ ...attachment, contentDisposition, contentId, contentType }),
+  )
+
+export const RESEND_RECEIVED_EMAIL_SUMMARY_WIRE_SCHEMA = z.object({
+  attachments: RESEND_RECEIVED_ATTACHMENT_WIRE_SCHEMA.array(),
+  bcc: z.string().array().nullable(),
+  cc: z.string().array().nullable(),
+  created_at: z.string(),
+  from: z.string(),
+  id: z.string(),
+  message_id: z.string(),
+  reply_to: z.string().array().nullable(),
+  subject: z.string().nullable(),
+  to: z.string().array(),
+})
+
+export const RESEND_RECEIVED_EMAIL_SUMMARY_SCHEMA =
+  RESEND_RECEIVED_EMAIL_SUMMARY_WIRE_SCHEMA.transform(
+    ({
+      attachments,
+      created_at: createdAt,
+      message_id: messageId,
+      reply_to: replyTo,
+      ...email
+    }) => ({
+      ...email,
+      attachments: attachments.map((attachment) =>
+        RESEND_RECEIVED_ATTACHMENT_SCHEMA.parse(attachment),
+      ),
+      createdAt,
+      messageId,
+      replyTo,
+    }),
+  )
+
+export const RESEND_RECEIVED_EMAIL_WIRE_SCHEMA =
+  RESEND_RECEIVED_EMAIL_SUMMARY_WIRE_SCHEMA.extend({
+    headers: z.record(z.string(), z.string()).nullable(),
+    html: z.string().nullable(),
+    object: z.literal("email"),
+    raw: z
+      .object({ download_url: z.url(), expires_at: z.string() })
+      .nullable()
+      .optional(),
+    received_for: z.string().array().optional(),
+    subject: z.string(),
+    text: z.string().nullable(),
+  })
+
+export const RESEND_RECEIVED_EMAIL_SCHEMA =
+  RESEND_RECEIVED_EMAIL_WIRE_SCHEMA.transform(
+    ({
+      attachments,
+      created_at: createdAt,
+      message_id: messageId,
+      raw,
+      received_for: receivedFor,
+      reply_to: replyTo,
+      ...email
+    }) => ({
+      ...email,
+      attachments: attachments.map((attachment) =>
+        RESEND_RECEIVED_ATTACHMENT_SCHEMA.parse(attachment),
+      ),
+      createdAt,
+      messageId,
+      raw:
+        raw === null || raw === undefined
+          ? raw
+          : { downloadUrl: raw.download_url, expiresAt: raw.expires_at },
+      receivedFor,
+      replyTo,
+    }),
+  )
+
+export const RESEND_CONTACT_SUMMARY_WIRE_SCHEMA = z.object({
+  created_at: z.string(),
+  email: z.email(),
+  first_name: z.string().nullable(),
+  id: z.string(),
+  last_name: z.string().nullable(),
+  unsubscribed: z.boolean(),
+})
+
+export const RESEND_CONTACT_SUMMARY_SCHEMA =
+  RESEND_CONTACT_SUMMARY_WIRE_SCHEMA.transform(
+    ({
+      created_at: createdAt,
+      first_name: firstName,
+      last_name: lastName,
+      ...contact
+    }) => ({ ...contact, createdAt, firstName, lastName }),
+  )
+
+export const RESEND_CONTACT_WIRE_SCHEMA =
+  RESEND_CONTACT_SUMMARY_WIRE_SCHEMA.extend({
+    object: z.literal("contact"),
+    properties: z.record(
+      z.string(),
+      z.discriminatedUnion("type", [
+        z.object({ type: z.literal("number"), value: z.number() }),
+        z.object({ type: z.literal("string"), value: z.string() }),
+      ]),
+    ),
+  })
+
+export const RESEND_CONTACT_SCHEMA = RESEND_CONTACT_WIRE_SCHEMA.transform(
+  ({
+    created_at: createdAt,
+    first_name: firstName,
+    last_name: lastName,
+    ...contact
+  }) => ({ ...contact, createdAt, firstName, lastName }),
+)
+
+export const RESEND_SEGMENT_SUMMARY_WIRE_SCHEMA = z.object({
+  created_at: z.string(),
+  id: z.string(),
+  name: z.string(),
+})
+
+export const RESEND_SEGMENT_SUMMARY_SCHEMA =
+  RESEND_SEGMENT_SUMMARY_WIRE_SCHEMA.transform(
+    ({ created_at: createdAt, ...segment }) => ({ ...segment, createdAt }),
+  )
+
+export const RESEND_CONTACT_IMPORT_COUNTS_SCHEMA = z.object({
+  created: z.number().int().nonnegative(),
+  failed: z.number().int().nonnegative(),
+  skipped: z.number().int().nonnegative(),
+  total: z.number().int().nonnegative(),
+  updated: z.number().int().nonnegative(),
+})
+
+export const RESEND_CONTACT_IMPORT_WIRE_SCHEMA = z.object({
+  completed_at: z.string().nullable().optional(),
+  counts: RESEND_CONTACT_IMPORT_COUNTS_SCHEMA.optional(),
+  created_at: z.string(),
+  id: z.string(),
+  object: z.literal("contact_import"),
+  status: z.enum(["completed", "failed", "in_progress", "queued"]),
+})
+
+export const RESEND_CONTACT_IMPORT_SCHEMA =
+  RESEND_CONTACT_IMPORT_WIRE_SCHEMA.transform(
+    ({
+      completed_at: completedAt,
+      created_at: createdAt,
+      ...contactImport
+    }) => ({ ...contactImport, completedAt, createdAt }),
+  )
+
+export const RESEND_CONTACT_TOPIC_SCHEMA = z.object({
+  description: z.string(),
+  id: z.string(),
+  name: z.string(),
+  subscription: z.enum(["opt_in", "opt_out"]),
+})
+
+export const RESEND_CONTACT_SEGMENT_DELETE_WIRE_SCHEMA = z.object({
+  contact_id: z.string(),
+  deleted: z.boolean(),
+  object: z.literal("contact_segment"),
+  segment_id: z.string(),
+})
+
+export const RESEND_CONTACT_SEGMENT_MUTATION_WIRE_SCHEMA = z.object({
+  contact_id: z.string(),
+  object: z.literal("contact_segment"),
+  segment_id: z.string(),
+})
+
+export const RESEND_CONTACT_SEGMENT_MUTATION_SCHEMA =
+  RESEND_CONTACT_SEGMENT_MUTATION_WIRE_SCHEMA.transform(
+    ({ contact_id: contactId, segment_id: segmentId, ...result }) => ({
+      ...result,
+      contactId,
+      segmentId,
+    }),
+  )
+
+export const RESEND_CONTACT_SEGMENT_DELETE_SCHEMA =
+  RESEND_CONTACT_SEGMENT_DELETE_WIRE_SCHEMA.transform(
+    ({ contact_id: contactId, segment_id: segmentId, ...result }) => ({
+      ...result,
+      contactId,
+      segmentId,
+    }),
+  )
+
+export const RESEND_CONTACT_TOPICS_UPDATE_WIRE_SCHEMA = z.object({
+  contact_id: z.string(),
+  object: z.literal("contact_topics"),
+  topics: z
+    .object({
+      id: z.string(),
+      subscription: z.enum(["opt_in", "opt_out"]),
+    })
+    .array(),
+})
+
+export const RESEND_CONTACT_TOPICS_UPDATE_SCHEMA =
+  RESEND_CONTACT_TOPICS_UPDATE_WIRE_SCHEMA.transform(
+    ({ contact_id: contactId, ...result }) => ({ ...result, contactId }),
+  )
+
+export const RESEND_EVENT_SEND_RESPONSE_SCHEMA = z.object({
+  event: z.string(),
+  object: z.literal("event"),
+})
+
+export const RESEND_EVENT_VALUE_TYPE_SCHEMA = z.enum([
+  "boolean",
+  "date",
+  "number",
+  "string",
+])
+
+export const RESEND_EVENT_DEFINITION_WIRE_SCHEMA = z.object({
+  created_at: z.string(),
+  id: z.string(),
+  name: z.string(),
+  object: z.literal("event").optional(),
+  schema: z.record(z.string(), RESEND_EVENT_VALUE_TYPE_SCHEMA).nullable(),
+  updated_at: z.string().nullable(),
+})
+
+export const RESEND_EVENT_DEFINITION_SCHEMA =
+  RESEND_EVENT_DEFINITION_WIRE_SCHEMA.transform(
+    ({ created_at: createdAt, updated_at: updatedAt, ...event }) => ({
+      ...event,
+      createdAt,
+      updatedAt,
+    }),
+  )
+
+/**
+ * Creates a Resend list response schema for one provider item schema.
+ *
+ * @param item - Provider item schema contained in the list.
+ */
+export function resendListWireSchema<TItem extends z.ZodType>(item: TItem) {
+  return z.object({
+    data: item.array(),
+    has_more: z.boolean(),
+    object: z.literal("list"),
+  })
+}
+
+/**
+ * Creates a normalized Resend list response schema.
+ *
+ * @param item - Normalized item schema contained in the list.
+ */
+export function resendListSchema<TItem extends z.ZodType>(item: TItem) {
+  return resendListWireSchema(item).transform(
+    ({ has_more: hasMore, ...page }) => ({ ...page, hasMore }),
+  )
+}

package/src/resend/api.ts

@@ -0,0 +1,258 @@
+import type { JsonValue } from "type-fest"
+import * as z from "zod"
+
+export * from "./action-schemas"
+
+const RESEND_API_BASE_URL = "https://api.resend.com/"
+const RESEND_API_ORIGIN = new URL(RESEND_API_BASE_URL).origin
+export const RESEND_USER_AGENT = "automate.ax/resend"
+const RESEND_API_KEY_SECRET_SCHEMA = z.object({
+  accessToken: z.never().optional(),
+  apiKey: z.string().min(1),
+})
+const RESEND_OAUTH_SECRET_SCHEMA = z.object({
+  accessToken: z.string().min(1),
+  apiKey: z.never().optional(),
+})
+const RESEND_SECRET_SCHEMA = z.union([
+  RESEND_API_KEY_SECRET_SCHEMA,
+  RESEND_OAUTH_SECRET_SCHEMA,
+])
+const RESEND_ERROR_SCHEMA = z.looseObject({
+  message: z.string().optional(),
+  name: z.string().optional(),
+  statusCode: z.number().int().optional(),
+})
+
+/** Scalar value serialized into a Resend query parameter. */
+type ResendQueryScalar = boolean | number | string
+
+/** Provider rate-limit values returned with a Resend response. */
+export interface ResendRateLimitMetadata {
+  /** Maximum requests allowed in the current window. */
+  limit?: number
+
+  /** Requests remaining in the current window. */
+  remaining?: number
+
+  /** Seconds until the current window resets. */
+  reset?: number
+}
+
+/** Provider email-quota usage returned with a Resend response. */
+export interface ResendQuotaMetadata {
+  /** Used daily quota, when Resend supplies the free-plan header. */
+  daily?: number
+
+  /** Used monthly quota. */
+  monthly?: number
+}
+
+/** Options for one authenticated Resend API call. */
+export interface ResendApiCallOptions<TSchema extends z.ZodType> {
+  /** Provider-native JSON or multipart request body. */
+  body?: FormData | JsonValue
+
+  /** Additional request headers such as `Idempotency-Key`. */
+  headers?: RequestInit["headers"]
+
+  /** HTTP method. Defaults to `POST` with a body and `GET` otherwise. */
+  httpMethod?: "DELETE" | "GET" | "PATCH" | "POST"
+
+  /** Provider-native URL query parameters. Array values are repeated. */
+  query?: Record<string, ResendQueryScalar | ResendQueryScalar[] | undefined>
+
+  /** Schema for the complete successful provider response. */
+  responseSchema: TSchema
+}
+
+/** Authenticated, schema-validating Resend REST API helper. */
+export interface ResendApi {
+  /**
+   * Calls a Resend endpoint and validates its successful response.
+   *
+   * @param path - Resend API path such as `/emails`.
+   * @param options - Request data and response schema.
+   */
+  call<TSchema extends z.ZodType>(
+    path: string,
+    options: ResendApiCallOptions<TSchema>,
+  ): Promise<z.output<TSchema>>
+}
+
+/** Structured failure returned by the Resend API. */
+export class ResendApiError extends Error {
+  /** API path that failed. */
+  readonly path: string
+
+  /** Provider error classification. */
+  readonly providerName?: string
+
+  /** Provider status code from the JSON error body. */
+  readonly providerStatusCode?: number
+
+  /** Email-quota usage returned with the failed response. */
+  readonly quota: ResendQuotaMetadata
+
+  /** Rate-limit values returned with the failed response. */
+  readonly rateLimit: ResendRateLimitMetadata
+
+  /** Delay in seconds before the request should be retried. */
+  readonly retryAfter?: number
+
+  /** HTTP status returned by Resend. */
+  readonly status: number
+
+  /**
+   * Creates a structured Resend provider error.
+   *
+   * @param options - Provider and transport failure details.
+   * @param options.message - Human-readable provider failure.
+   * @param options.path - API path that failed.
+   * @param options.providerName - Provider error classification.
+   * @param options.providerStatusCode - Provider status code from JSON.
+   * @param options.quota - Provider email-quota metadata.
+   * @param options.rateLimit - Provider rate-limit metadata.
+   * @param options.retryAfter - Provider retry delay in seconds.
+   * @param options.status - HTTP status.
+   */
+  constructor(options: {
+    message: string
+    path: string
+    providerName?: string
+    providerStatusCode?: number
+    quota: ResendQuotaMetadata
+    rateLimit: ResendRateLimitMetadata
+    retryAfter?: number
+    status: number
+  }) {
+    super(`Resend ${options.path} failed: ${options.message}`)
+    this.name = "ResendApiError"
+    this.path = options.path
+    this.providerName = options.providerName
+    this.providerStatusCode = options.providerStatusCode
+    this.quota = options.quota
+    this.rateLimit = options.rateLimit
+    this.retryAfter = options.retryAfter
+    this.status = options.status
+  }
+}
+
+/**
+ * Creates a raw authenticated Resend REST client.
+ *
+ * The helper accepts either an API-key secret (`{ apiKey }`) or OAuth secret
+ * (`{ accessToken }`). Callers must supply a response schema for every
+ * request.
+ *
+ * @param secret - Resolved Resend integration secret.
+ */
+export function getResendApi(secret: Record<string, unknown>): ResendApi {
+  const credential = RESEND_SECRET_SCHEMA.parse(secret)
+  const token =
+    "apiKey" in credential ? credential.apiKey : credential.accessToken
+
+  return {
+    call: async (path, options) => {
+      const url = new URL(path, RESEND_API_BASE_URL)
+      if (url.origin !== RESEND_API_ORIGIN) {
+        throw new Error("Resend API paths must use the Resend API origin.")
+      }
+      const normalizedPath = `${url.pathname}${url.search}`
+      for (const [name, value] of Object.entries(options.query ?? {})) {
+        for (const item of Array.isArray(value) ? value : [value]) {
+          if (item !== undefined) url.searchParams.append(name, String(item))
+        }
+      }
+
+      const headers = new Headers(options.headers)
+      headers.set("Accept", "application/json")
+      headers.set("Authorization", `Bearer ${token}`)
+      headers.set("User-Agent", RESEND_USER_AGENT)
+      const body = options.body
+      const isMultipart = body instanceof FormData
+      if (body !== undefined && !isMultipart) {
+        headers.set("Content-Type", "application/json")
+      }
+
+      const response = await fetch(url, {
+        body:
+          body instanceof FormData
+            ? body
+            : body === undefined
+              ? undefined
+              : JSON.stringify(body),
+        headers,
+        method:
+          options.httpMethod ?? (options.body === undefined ? "GET" : "POST"),
+      })
+      const responseText = await response.text()
+      const metadata = getResponseMetadata(response.headers)
+      if (!response.ok) {
+        const result = RESEND_ERROR_SCHEMA.safeParse(parseJson(responseText))
+        throw new ResendApiError({
+          message:
+            (result.success ? result.data.message : undefined) ??
+            (responseText.trim() || `HTTP ${response.status}`),
+          path: normalizedPath,
+          providerName: result.success ? result.data.name : undefined,
+          providerStatusCode: result.success
+            ? result.data.statusCode
+            : undefined,
+          status: response.status,
+          ...metadata,
+        })
+      }
+
+      return options.responseSchema.parse(
+        responseText.trim() ? parseJson(responseText) : undefined,
+      )
+    },
+  }
+}
+
+/**
+ * Parses JSON while preserving useful plain-text error handling.
+ *
+ * @param value - Response text to parse.
+ */
+function parseJson(value: string): unknown {
+  try {
+    return JSON.parse(value)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Extracts retry, rate-limit, and quota headers from one response.
+ *
+ * @param headers - Resend response headers.
+ */
+function getResponseMetadata(headers: Headers) {
+  return {
+    quota: {
+      daily: parseNumberHeader(headers, "x-resend-daily-quota"),
+      monthly: parseNumberHeader(headers, "x-resend-monthly-quota"),
+    },
+    rateLimit: {
+      limit: parseNumberHeader(headers, "ratelimit-limit"),
+      remaining: parseNumberHeader(headers, "ratelimit-remaining"),
+      reset: parseNumberHeader(headers, "ratelimit-reset"),
+    },
+    retryAfter: parseNumberHeader(headers, "retry-after"),
+  }
+}
+
+/**
+ * Parses one numeric response header.
+ *
+ * @param headers - Resend response headers.
+ * @param name - Case-insensitive header name.
+ */
+function parseNumberHeader(headers: Headers, name: string) {
+  const value = headers.get(name)
+  if (value === null) return undefined
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : undefined
+}