@automate.ax/integration-contracts 0.98.0 → 0.99.0

package/dist/resend/action-schemas.js

@@ -0,0 +1,273 @@
+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(item) {
+    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(item) {
+    return resendListWireSchema(item).transform(({ has_more: hasMore, ...page }) => ({ ...page, hasMore }));
+}

package/dist/resend/api.d.ts

@@ -0,0 +1,95 @@
+import type { JsonValue } from "type-fest";
+import * as z from "zod";
+export * from "./action-schemas.js";
+export declare const RESEND_USER_AGENT = "automate.ax/resend";
+/** 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 declare 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;
+    });
+}
+/**
+ * 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 declare function getResendApi(secret: Record<string, unknown>): ResendApi;

package/dist/resend/api.js

@@ -0,0 +1,171 @@
+import * as z from "zod";
+export * from "./action-schemas.js";
+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(),
+});
+/** Structured failure returned by the Resend API. */
+export class ResendApiError extends Error {
+    /** API path that failed. */
+    path;
+    /** Provider error classification. */
+    providerName;
+    /** Provider status code from the JSON error body. */
+    providerStatusCode;
+    /** Email-quota usage returned with the failed response. */
+    quota;
+    /** Rate-limit values returned with the failed response. */
+    rateLimit;
+    /** Delay in seconds before the request should be retried. */
+    retryAfter;
+    /** HTTP status returned by Resend. */
+    status;
+    /**
+     * 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) {
+        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) {
+    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) {
+    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) {
+    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, name) {
+    const value = headers.get(name);
+    if (value === null)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}