@automate.ax/integration-contracts 0.55.0

package/src/outlook/graph.ts

@@ -0,0 +1,132 @@
+import { z } from "zod"
+
+const GRAPH_BASE_URL = "https://graph.microsoft.com/v1.0/"
+const MICROSOFT_SECRET_SCHEMA = z.object({
+  accessToken: z.string().min(1),
+})
+const GRAPH_ERROR_SCHEMA = z.looseObject({
+  error: z
+    .looseObject({
+      code: z.string().optional(),
+      message: z.string().optional(),
+    })
+    .optional(),
+})
+
+/** Options accepted by the authenticated Outlook Graph request helper. */
+export interface OutlookGraphRequestOptions {
+  /** JSON-serializable request body. */
+  body?: unknown
+
+  /** Additional HTTP headers. */
+  headers?: RequestInit["headers"]
+
+  /** HTTP method. */
+  method?: string
+}
+
+/**
+ * Creates a small authenticated Microsoft Graph client for Outlook APIs.
+ *
+ * The raw `fetch` method is an escape hatch for provider features not yet
+ * represented by a built-in action. `request` parses JSON and reports Graph
+ * errors with their provider code and message.
+ *
+ * @param secret - Refreshed Microsoft OAuth integration secret.
+ */
+export function getOutlookGraphApi(secret: Record<string, unknown>) {
+  const { accessToken } = MICROSOFT_SECRET_SCHEMA.parse(secret)
+
+  /**
+   * Performs one authenticated Graph request.
+   *
+   * @param path - Relative or absolute Microsoft Graph URL.
+   * @param init - Standard fetch request options.
+   */
+  async function graphFetch(path: string, init?: RequestInit) {
+    const headers = new Headers(init?.headers)
+    headers.set("Accept", "application/json")
+    headers.set("Authorization", `Bearer ${accessToken}`)
+    if (!headers.has("Prefer")) headers.set("Prefer", 'IdType="ImmutableId"')
+    return fetch(new URL(path.replace(/^\//, ""), GRAPH_BASE_URL), {
+      ...init,
+      headers,
+    })
+  }
+
+  /**
+   * Performs one authenticated Graph JSON request.
+   *
+   * @param path - Relative or absolute Microsoft Graph URL.
+   * @param options - HTTP method, body, and headers.
+   */
+  async function request(
+    path: string,
+    options: OutlookGraphRequestOptions = {},
+  ): Promise<unknown> {
+    const headers = new Headers(options.headers)
+    if (options.body !== undefined) {
+      headers.set("Content-Type", "application/json")
+    }
+    const response = await graphFetch(path, {
+      body:
+        options.body === undefined ? undefined : JSON.stringify(options.body),
+      headers,
+      method: options.method,
+    })
+
+    if (!response.ok) {
+      const payload = GRAPH_ERROR_SCHEMA.safeParse(
+        await response.json().catch(() => undefined),
+      )
+      const graphError = payload.success ? payload.data.error : undefined
+      const detail = [graphError?.code, graphError?.message]
+        .filter(Boolean)
+        .join(": ")
+      throw new Error(
+        `Microsoft Graph request failed with ${response.status} ${response.statusText}${detail ? `: ${detail}` : ""}.`,
+      )
+    }
+
+    if (response.status === 202 || response.status === 204) return undefined
+    return response.json()
+  }
+
+  return {
+    /** Performs an authenticated request and returns the raw Response. */
+    fetch: graphFetch,
+
+    /** Performs an authenticated request and returns its untrusted JSON value. */
+    request,
+  }
+}
+
+/**
+ * Reads Graph collection pages until the requested limit is reached.
+ *
+ * @param request - Authenticated Graph JSON request function.
+ * @param path - Initial relative Graph path.
+ * @param itemSchema - Schema for one collection item.
+ * @param limit - Maximum total items.
+ */
+export async function listOutlookGraphCollection<T>(
+  request: (path: string) => Promise<unknown>,
+  path: string,
+  itemSchema: z.ZodType<T>,
+  limit: number,
+) {
+  const pageSchema = z.object({
+    "@odata.nextLink": z.string().optional(),
+    value: itemSchema.array(),
+  })
+  const items: T[] = []
+  let nextPath: string | undefined = path
+
+  while (nextPath && items.length < limit) {
+    const page = pageSchema.parse(await request(nextPath))
+    items.push(...page.value)
+    nextPath = page["@odata.nextLink"]
+  }
+
+  return items.slice(0, limit)
+}

package/src/outlook/index.ts

@@ -0,0 +1,14 @@
+import { z } from "zod"
+import { OUTLOOK_MESSAGE_SCHEMA } from "./schemas"
+
+export * from "./graph"
+export * from "./schemas"
+
+export const OUTLOOK_TRIGGER_CONFIG_SCHEMA = z.object({})
+
+export const outlookTriggerContracts = {
+  "outlook.email.received": {
+    configSchema: OUTLOOK_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: OUTLOOK_MESSAGE_SCHEMA,
+  },
+} as const

package/src/outlook/schemas.ts

@@ -0,0 +1,388 @@
+import { z } from "zod"
+
+const OPTIONAL_DATE_SCHEMA = z
+  .union([
+    z.date(),
+    z.iso.datetime({ offset: true }).transform((value) => new Date(value)),
+  ])
+  .nullish()
+  .transform((value) => value ?? undefined)
+const OPTIONAL_STRING_SCHEMA = z
+  .string()
+  .nullish()
+  .transform((value) => value ?? undefined)
+
+export const OUTLOOK_BODY_TYPE_SCHEMA = z.enum(["text", "html"])
+export const OUTLOOK_IMPORTANCE_SCHEMA = z.enum(["low", "normal", "high"])
+export const OUTLOOK_FLAG_STATUS_SCHEMA = z.enum([
+  "notFlagged",
+  "complete",
+  "flagged",
+])
+
+export const OUTLOOK_EMAIL_ADDRESS_SCHEMA = z.object({
+  /** SMTP email address. */
+  address: z.string(),
+
+  /** Display name supplied by Microsoft Graph. */
+  name: OPTIONAL_STRING_SCHEMA,
+})
+
+export const OUTLOOK_RECIPIENT_SCHEMA = z.union([
+  z.email(),
+  OUTLOOK_EMAIL_ADDRESS_SCHEMA,
+])
+export const OUTLOOK_RECIPIENTS_SCHEMA = z.union([
+  OUTLOOK_RECIPIENT_SCHEMA,
+  OUTLOOK_RECIPIENT_SCHEMA.array().min(1),
+])
+
+export const OUTLOOK_BODY_SCHEMA = z.object({
+  /** Body content as returned by Graph. */
+  content: z.string(),
+
+  /** Lowercase body media type. */
+  contentType: z
+    .enum(["text", "html"])
+    .or(z.enum(["Text", "HTML"]))
+    .transform((value) =>
+      value === "Text" ? "text" : value === "HTML" ? "html" : value,
+    ),
+})
+
+const OUTLOOK_FOLLOWUP_FLAG_SCHEMA = z.object({
+  /** Date and time the flag was completed. */
+  completedAt: z
+    .object({ dateTime: z.string(), timeZone: z.string() })
+    .nullish()
+    .transform((value) => value ?? undefined),
+
+  /** Due date and its Outlook timezone. */
+  dueAt: z
+    .object({ dateTime: z.string(), timeZone: z.string() })
+    .nullish()
+    .transform((value) => value ?? undefined),
+
+  /** Current follow-up state. */
+  status: OUTLOOK_FLAG_STATUS_SCHEMA,
+})
+
+export const OUTLOOK_MESSAGE_SCHEMA = z.object({
+  /** Outlook categories assigned to the message. */
+  categories: z.string().array().prefault([]),
+
+  /** Opaque conversation identifier shared by related messages. */
+  conversationId: OPTIONAL_STRING_SCHEMA,
+
+  /** Time the message was created in the mailbox. */
+  createdAt: OPTIONAL_DATE_SCHEMA,
+
+  /** Follow-up flag state and dates. */
+  flag: OUTLOOK_FOLLOWUP_FLAG_SCHEMA.optional(),
+
+  /** Sender shown in the From header. */
+  from: OUTLOOK_EMAIL_ADDRESS_SCHEMA.nullish().transform(
+    (value) => value ?? undefined,
+  ),
+
+  /** Whether the message contains one or more attachments. */
+  hasAttachments: z.boolean().prefault(false),
+
+  /** Provider message identifier. */
+  messageId: z.string(),
+
+  /** RFC 5322 Message-ID. */
+  internetMessageId: OPTIONAL_STRING_SCHEMA,
+
+  /** Provider-defined message importance. */
+  importance: OUTLOOK_IMPORTANCE_SCHEMA.prefault("normal"),
+
+  /** Focused Inbox classification. */
+  inferenceClassification: z
+    .enum(["focused", "other"])
+    .nullish()
+    .transform((value) => value ?? undefined),
+
+  /** Whether this message is an unsent draft. */
+  isDraft: z.boolean().prefault(false),
+
+  /** Whether the message has been read. */
+  isRead: z.boolean().prefault(false),
+
+  /** Time the message was last modified. */
+  modifiedAt: OPTIONAL_DATE_SCHEMA,
+
+  /** Opaque containing folder identifier. */
+  parentFolderId: OPTIONAL_STRING_SCHEMA,
+
+  /** Short body preview generated by Outlook. */
+  preview: OPTIONAL_STRING_SCHEMA,
+
+  /** Time the message arrived in the mailbox. */
+  receivedAt: OPTIONAL_DATE_SCHEMA,
+
+  /** Addresses preferred for replies. */
+  replyTo: OUTLOOK_EMAIL_ADDRESS_SCHEMA.array().prefault([]),
+
+  /** Account that submitted the message. */
+  sender: OUTLOOK_EMAIL_ADDRESS_SCHEMA.nullish().transform(
+    (value) => value ?? undefined,
+  ),
+
+  /** Time the message was sent. */
+  sentAt: OPTIONAL_DATE_SCHEMA,
+
+  /** Subject line. */
+  subject: z
+    .string()
+    .nullish()
+    .transform((value) => value ?? ""),
+
+  /** Primary recipients. */
+  to: OUTLOOK_EMAIL_ADDRESS_SCHEMA.array().prefault([]),
+
+  /** Carbon-copy recipients. */
+  cc: OUTLOOK_EMAIL_ADDRESS_SCHEMA.array().prefault([]),
+
+  /** Blind-copy recipients. */
+  bcc: OUTLOOK_EMAIL_ADDRESS_SCHEMA.array().prefault([]),
+
+  /** Outlook web URL for the message. */
+  webLink: OPTIONAL_STRING_SCHEMA,
+
+  /** Message body, when requested from Graph. */
+  body: OUTLOOK_BODY_SCHEMA.nullish().transform((value) => value ?? undefined),
+
+  /** Graph concurrency token. */
+  etag: z.string().optional(),
+})
+
+export const GRAPH_MESSAGE_SCHEMA = z
+  .looseObject({
+    "@odata.etag": z.string().optional(),
+    bccRecipients: z
+      .object({ emailAddress: OUTLOOK_EMAIL_ADDRESS_SCHEMA })
+      .array()
+      .optional(),
+    body: OUTLOOK_BODY_SCHEMA.nullish(),
+    bodyPreview: z.string().nullish(),
+    categories: z.string().array().optional(),
+    ccRecipients: z
+      .object({ emailAddress: OUTLOOK_EMAIL_ADDRESS_SCHEMA })
+      .array()
+      .optional(),
+    conversationId: z.string().nullish(),
+    createdDateTime: z.string().nullish(),
+    flag: z
+      .object({
+        completedDateTime: z
+          .object({ dateTime: z.string(), timeZone: z.string() })
+          .nullish(),
+        dueDateTime: z
+          .object({ dateTime: z.string(), timeZone: z.string() })
+          .nullish(),
+        flagStatus: OUTLOOK_FLAG_STATUS_SCHEMA,
+      })
+      .optional(),
+    from: z.object({ emailAddress: OUTLOOK_EMAIL_ADDRESS_SCHEMA }).nullish(),
+    hasAttachments: z.boolean().optional(),
+    id: z.string(),
+    importance: OUTLOOK_IMPORTANCE_SCHEMA.optional(),
+    inferenceClassification: z.enum(["focused", "other"]).nullish(),
+    internetMessageId: z.string().nullish(),
+    isDraft: z.boolean().optional(),
+    isRead: z.boolean().optional(),
+    lastModifiedDateTime: z.string().nullish(),
+    parentFolderId: z.string().nullish(),
+    receivedDateTime: z.string().nullish(),
+    replyTo: z
+      .object({ emailAddress: OUTLOOK_EMAIL_ADDRESS_SCHEMA })
+      .array()
+      .optional(),
+    sender: z.object({ emailAddress: OUTLOOK_EMAIL_ADDRESS_SCHEMA }).nullish(),
+    sentDateTime: z.string().nullish(),
+    subject: z.string().nullish(),
+    toRecipients: z
+      .object({ emailAddress: OUTLOOK_EMAIL_ADDRESS_SCHEMA })
+      .array()
+      .optional(),
+    webLink: z.string().nullish(),
+  })
+  .transform((message) =>
+    OUTLOOK_MESSAGE_SCHEMA.parse({
+      bcc: message.bccRecipients?.map(({ emailAddress }) => emailAddress),
+      body: message.body,
+      categories: message.categories,
+      cc: message.ccRecipients?.map(({ emailAddress }) => emailAddress),
+      conversationId: message.conversationId,
+      createdAt: message.createdDateTime,
+      etag: message["@odata.etag"],
+      flag: message.flag
+        ? {
+            completedAt: message.flag.completedDateTime,
+            dueAt: message.flag.dueDateTime,
+            status: message.flag.flagStatus,
+          }
+        : undefined,
+      from: message.from?.emailAddress,
+      hasAttachments: message.hasAttachments,
+      importance: message.importance,
+      inferenceClassification: message.inferenceClassification,
+      internetMessageId: message.internetMessageId,
+      isDraft: message.isDraft,
+      isRead: message.isRead,
+      messageId: message.id,
+      modifiedAt: message.lastModifiedDateTime,
+      parentFolderId: message.parentFolderId,
+      preview: message.bodyPreview,
+      receivedAt: message.receivedDateTime,
+      replyTo: message.replyTo?.map(({ emailAddress }) => emailAddress),
+      sender: message.sender?.emailAddress,
+      sentAt: message.sentDateTime,
+      subject: message.subject,
+      to: message.toRecipients?.map(({ emailAddress }) => emailAddress),
+      webLink: message.webLink,
+    }),
+  )
+
+/**
+ * Normalizes an untrusted Microsoft Graph message payload.
+ *
+ * @param payload - Provider message payload.
+ */
+export function normalizeOutlookMessage(payload: unknown) {
+  return GRAPH_MESSAGE_SCHEMA.parse(payload)
+}
+
+export const OUTLOOK_MAIL_FOLDER_SCHEMA = z.object({
+  /** Number of child folders directly beneath this folder. */
+  childFolderCount: z.number().int().prefault(0),
+
+  /** Human-readable folder name. */
+  displayName: z.string(),
+
+  /** Whether the folder is hidden in Outlook. */
+  isHidden: z.boolean().prefault(false),
+
+  /** Opaque provider folder identifier. */
+  folderId: z.string(),
+
+  /** Total messages directly contained in the folder. */
+  totalItemCount: z.number().int().prefault(0),
+
+  /** Unread messages directly contained in the folder. */
+  unreadItemCount: z.number().int().prefault(0),
+})
+
+export const GRAPH_MAIL_FOLDER_SCHEMA = z
+  .looseObject({
+    childFolderCount: z.number().int().optional(),
+    displayName: z.string(),
+    id: z.string(),
+    isHidden: z.boolean().optional(),
+    totalItemCount: z.number().int().optional(),
+    unreadItemCount: z.number().int().optional(),
+  })
+  .transform((folder) =>
+    OUTLOOK_MAIL_FOLDER_SCHEMA.parse({
+      ...folder,
+      folderId: folder.id,
+    }),
+  )
+
+export const OUTLOOK_PROFILE_SCHEMA = z.object({
+  /** User's primary email address, when available. */
+  email: OPTIONAL_STRING_SCHEMA,
+
+  /** Display name configured in Microsoft 365. */
+  displayName: z.string(),
+
+  /** Microsoft Graph user identifier. */
+  userId: z.string(),
+
+  /** User principal name used to sign in. */
+  userPrincipalName: z.string(),
+})
+
+export const GRAPH_PROFILE_SCHEMA = z
+  .looseObject({
+    displayName: z.string(),
+    id: z.string(),
+    mail: z.string().nullish(),
+    userPrincipalName: z.string(),
+  })
+  .transform((profile) =>
+    OUTLOOK_PROFILE_SCHEMA.parse({
+      displayName: profile.displayName,
+      email: profile.mail,
+      userId: profile.id,
+      userPrincipalName: profile.userPrincipalName,
+    }),
+  )
+
+export const OUTLOOK_ATTACHMENT_SCHEMA = z.object({
+  /** Content-ID used by inline HTML content. */
+  contentId: OPTIONAL_STRING_SCHEMA,
+
+  /** Content location supplied by the sender. */
+  contentLocation: OPTIONAL_STRING_SCHEMA,
+
+  /** MIME media type. */
+  contentType: OPTIONAL_STRING_SCHEMA,
+
+  /** Downloaded file contents, when included by Graph. */
+  file: z.instanceof(File).optional(),
+
+  /** Opaque provider attachment identifier. */
+  attachmentId: z.string(),
+
+  /** Whether the attachment is displayed inline. */
+  isInline: z.boolean().prefault(false),
+
+  /** Attachment filename. */
+  name: z.string(),
+
+  /** Attachment size in bytes. */
+  size: z.number().int().nonnegative().prefault(0),
+
+  /** Graph attachment resource kind. */
+  type: z.enum(["file", "item", "reference", "unknown"]),
+})
+
+export const GRAPH_ATTACHMENT_SCHEMA = z
+  .looseObject({
+    "@odata.type": z.string().optional(),
+    contentBytes: z.string().optional(),
+    contentId: z.string().nullish(),
+    contentLocation: z.string().nullish(),
+    contentType: z.string().nullish(),
+    id: z.string(),
+    isInline: z.boolean().optional(),
+    name: z.string(),
+    size: z.number().int().optional(),
+  })
+  .transform((attachment) => {
+    return OUTLOOK_ATTACHMENT_SCHEMA.parse({
+      attachmentId: attachment.id,
+      contentId: attachment.contentId,
+      contentLocation: attachment.contentLocation,
+      contentType: attachment.contentType,
+      file: attachment.contentBytes
+        ? new File(
+            [Buffer.from(attachment.contentBytes, "base64")],
+            attachment.name,
+            { type: attachment.contentType ?? "" },
+          )
+        : undefined,
+      isInline: attachment.isInline,
+      name: attachment.name,
+      size: attachment.size,
+      type: attachment["@odata.type"]?.includes("fileAttachment")
+        ? "file"
+        : attachment["@odata.type"]?.includes("itemAttachment")
+          ? "item"
+          : attachment["@odata.type"]?.includes("referenceAttachment")
+            ? "reference"
+            : "unknown",
+    })
+  })

package/src/resend/index.ts

@@ -0,0 +1,70 @@
+import { z } from "zod"
+import {
+  RESEND_EMAIL_BOUNCED_EVENT_SCHEMA,
+  RESEND_EMAIL_CLICKED_EVENT_SCHEMA,
+  RESEND_EMAIL_COMPLAINED_EVENT_SCHEMA,
+  RESEND_EMAIL_DELIVERED_EVENT_SCHEMA,
+  RESEND_EMAIL_DELIVERY_DELAYED_EVENT_SCHEMA,
+  RESEND_EMAIL_EVENT_SCHEMA,
+  RESEND_EMAIL_FAILED_EVENT_SCHEMA,
+  RESEND_EMAIL_OPENED_EVENT_SCHEMA,
+  RESEND_EMAIL_RECEIVED_EVENT_SCHEMA,
+  RESEND_EMAIL_SCHEDULED_EVENT_SCHEMA,
+  RESEND_EMAIL_SENT_EVENT_SCHEMA,
+  RESEND_EMAIL_SUPPRESSED_EVENT_SCHEMA,
+} from "./schemas"
+
+export * from "./schemas"
+
+export const RESEND_TRIGGER_CONFIG_SCHEMA = z.object({})
+
+export const resendTriggerContracts = {
+  "resend.email.bounced": {
+    configSchema: RESEND_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: RESEND_EMAIL_BOUNCED_EVENT_SCHEMA,
+  },
+  "resend.email.clicked": {
+    configSchema: RESEND_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: RESEND_EMAIL_CLICKED_EVENT_SCHEMA,
+  },
+  "resend.email.complained": {
+    configSchema: RESEND_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: RESEND_EMAIL_COMPLAINED_EVENT_SCHEMA,
+  },
+  "resend.email.delivered": {
+    configSchema: RESEND_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: RESEND_EMAIL_DELIVERED_EVENT_SCHEMA,
+  },
+  "resend.email.deliveryDelayed": {
+    configSchema: RESEND_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: RESEND_EMAIL_DELIVERY_DELAYED_EVENT_SCHEMA,
+  },
+  "resend.email.event": {
+    configSchema: RESEND_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: RESEND_EMAIL_EVENT_SCHEMA,
+  },
+  "resend.email.failed": {
+    configSchema: RESEND_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: RESEND_EMAIL_FAILED_EVENT_SCHEMA,
+  },
+  "resend.email.opened": {
+    configSchema: RESEND_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: RESEND_EMAIL_OPENED_EVENT_SCHEMA,
+  },
+  "resend.email.received": {
+    configSchema: RESEND_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: RESEND_EMAIL_RECEIVED_EVENT_SCHEMA,
+  },
+  "resend.email.scheduled": {
+    configSchema: RESEND_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: RESEND_EMAIL_SCHEDULED_EVENT_SCHEMA,
+  },
+  "resend.email.sent": {
+    configSchema: RESEND_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: RESEND_EMAIL_SENT_EVENT_SCHEMA,
+  },
+  "resend.email.suppressed": {
+    configSchema: RESEND_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: RESEND_EMAIL_SUPPRESSED_EVENT_SCHEMA,
+  },
+} as const