@automate.ax/integration-contracts 0.55.0

package/src/gmail/gmail.ts

@@ -0,0 +1,577 @@
+import { auth, gmail, type gmail_v1 } from "@googleapis/gmail"
+import { compile } from "html-to-text"
+import MailComposer from "nodemailer/lib/mail-composer"
+import PostalMime, {
+  addressParser,
+  type Address,
+  type Attachment,
+} from "postal-mime"
+import { z } from "zod"
+import {
+  ATTACHMENT_INPUT_SCHEMA,
+  DRAFT_IDENTIFIER_SCHEMA,
+  LABEL_SCHEMA,
+  MAILBOX_SCHEMA,
+  MESSAGE_METADATA_SCHEMA,
+  MESSAGE_SCHEMA,
+  RECIPIENT_SCHEMA,
+  REPLY_OPTIONS_SCHEMA,
+} from "./schemas"
+
+export const AUTOMATE_AX_EMAIL_HEADER = "X-Sent-From-Automate-Ax"
+const AUTOMATE_EMAIL_HEADERS = {
+  "X-Mailer": "Automate.ax",
+  [AUTOMATE_AX_EMAIL_HEADER]: "true",
+}
+const HTML_TO_TEXT = compile({ wordwrap: false })
+const GMAIL_SECRET_SCHEMA = z.object({
+  accessToken: z.string().min(1),
+})
+const LABEL_LIST_VISIBILITY_SCHEMA = z.enum([
+  "labelHide",
+  "labelShow",
+  "labelShowIfUnread",
+])
+const MESSAGE_LIST_VISIBILITY_SCHEMA = z.enum(["hide", "show"])
+const LABEL_TYPE_SCHEMA = z.enum(["system", "user"])
+
+/** Internal options for constructing one RFC 5322 message. */
+export interface BuildMessageOptions {
+  /** Files and inline MIME parts attached to the message. */
+  attachments?: z.input<typeof ATTACHMENT_INPUT_SCHEMA>[]
+
+  /** Blind-copy recipients. */
+  bcc?: z.input<typeof RECIPIENT_SCHEMA> | z.input<typeof RECIPIENT_SCHEMA>[]
+
+  /** Carbon-copy recipients. */
+  cc?: z.input<typeof RECIPIENT_SCHEMA> | z.input<typeof RECIPIENT_SCHEMA>[]
+
+  /** Sender address or configured Gmail send-as alias. */
+  from?: z.input<typeof RECIPIENT_SCHEMA>
+
+  /** Additional RFC 5322 headers. */
+  headers?: Record<string, string>
+
+  /** HTML message body. */
+  html?: string
+
+  /** RFC 5322 Message-ID this message replies to. */
+  inReplyTo?: string
+
+  /** Importance priority encoded into standard message headers. */
+  priority?: "high" | "normal" | "low"
+
+  /** RFC 5322 Message-IDs in the conversation ancestry. */
+  references?: string[]
+
+  /** Addresses that should receive replies. */
+  replyTo?:
+    | z.input<typeof RECIPIENT_SCHEMA>
+    | z.input<typeof RECIPIENT_SCHEMA>[]
+
+  /** Message subject line. */
+  subject?: string
+
+  /** Plain-text message body. */
+  text?: string
+
+  /** Primary recipients. */
+  to?: z.input<typeof RECIPIENT_SCHEMA> | z.input<typeof RECIPIENT_SCHEMA>[]
+}
+
+/**
+ * Creates the official Gmail client from a resolved Google integration secret.
+ *
+ * @param secret - Refreshed Google integration secret.
+ */
+export function getGmailApi(secret: Record<string, unknown>) {
+  const { accessToken } = GMAIL_SECRET_SCHEMA.parse(secret)
+  return gmail({
+    auth: new auth.OAuth2({
+      credentials: { access_token: accessToken },
+    }),
+    version: "v1",
+  })
+}
+
+/**
+ * Builds the RFC 5322 message Gmail expects in its `raw` field.
+ *
+ * Missing plain text is derived from HTML.
+ *
+ * @param options - Message recipients, content, headers, and attachments.
+ */
+export async function buildRawMessage(options: BuildMessageOptions) {
+  const message = new MailComposer({
+    attachments: await Promise.all(
+      (options.attachments ?? []).map(async (attachment) => {
+        const { contentId, disposition, file, filename } =
+          attachment instanceof File ? { file: attachment } : attachment
+        return {
+          cid: contentId,
+          content: Buffer.from(await file.arrayBuffer()),
+          contentDisposition: disposition,
+          contentType: file.type || undefined,
+          filename: filename ?? file.name,
+        }
+      }),
+    ),
+    bcc: options.bcc,
+    cc: options.cc,
+    from: options.from,
+    headers: {
+      ...options.headers,
+      ...AUTOMATE_EMAIL_HEADERS,
+    },
+    html: options.html,
+    inReplyTo: options.inReplyTo,
+    priority: options.priority,
+    references: options.references,
+    replyTo: options.replyTo,
+    subject: options.subject ?? "",
+    text:
+      options.text ??
+      (options.html === undefined ? undefined : HTML_TO_TEXT(options.html)),
+    to: options.to,
+  }).compile()
+
+  // Gmail derives Bcc delivery recipients from the raw message headers.
+  message.keepBcc = true
+  return (await message.build()).toString("base64url")
+}
+
+/**
+ * Resolves a Gmail label name or ID to its canonical ID.
+ *
+ * @param gmailApi - Authenticated Gmail client.
+ * @param labelSearch - Label display name or ID.
+ */
+export async function findLabelId(
+  gmailApi: gmail_v1.Gmail,
+  labelSearch: string,
+) {
+  return (await findLabelIds(gmailApi, [labelSearch]))[0]!
+}
+
+/**
+ * Resolves Gmail label names or IDs with one label-list request.
+ *
+ * @param gmailApi - Authenticated Gmail client.
+ * @param labelSearches - Label display names or IDs.
+ */
+export async function findLabelIds(
+  gmailApi: gmail_v1.Gmail,
+  labelSearches: string[],
+) {
+  const {
+    data: { labels = [] },
+  } = await gmailApi.users.labels.list({ userId: "me" })
+
+  return labelSearches.map((labelSearch) => {
+    const normalizedSearch = labelSearch.trim().toLowerCase()
+    const labelId =
+      labels.find((label) => label.id === labelSearch)?.id ??
+      labels.find(
+        (label) => label.name?.trim().toLowerCase() === normalizedSearch,
+      )?.id
+
+    if (!labelId) {
+      throw new Error(`Gmail label "${labelSearch}" was not found.`)
+    }
+    return labelId
+  })
+}
+
+/**
+ * Normalizes a raw Gmail API message into the public message representation.
+ *
+ * @param rawMessage - Gmail message fetched with `format: "raw"`.
+ */
+export async function getGmailMessage(
+  rawMessage: gmail_v1.Schema$Message,
+): Promise<z.output<typeof MESSAGE_SCHEMA>> {
+  if (!rawMessage.id || !rawMessage.threadId || !rawMessage.raw) {
+    throw new Error("Gmail returned an incomplete message.")
+  }
+
+  const parsed = await parseRawMessage(rawMessage.raw)
+  const sentAt = parsed.date ? new Date(parsed.date) : undefined
+  return {
+    attachments: parsed.attachments.map(toAttachment),
+    bcc: flattenAddresses(parsed.bcc),
+    cc: flattenAddresses(parsed.cc),
+    deliveredTo: parsed.deliveredTo,
+    from: flattenAddresses(parsed.from).at(0),
+    headers: parsed.headers.map(({ originalKey, value }) => ({
+      name: originalKey,
+      value,
+    })),
+    historyId: rawMessage.historyId ?? undefined,
+    html: parsed.html,
+    inReplyTo: parsed.inReplyTo,
+    labelIds: rawMessage.labelIds ?? [],
+    messageId: rawMessage.id,
+    receivedAt: rawMessage.internalDate
+      ? new Date(Number(rawMessage.internalDate))
+      : null,
+    references: parsed.references?.trim().split(/\s+/) ?? [],
+    replyTo: flattenAddresses(parsed.replyTo),
+    returnPath: parsed.returnPath,
+    rfc822MessageId: parsed.messageId,
+    sender: flattenAddresses(parsed.sender).at(0),
+    ...(sentAt && !Number.isNaN(sentAt.getTime()) ? { sentAt } : {}),
+    sizeEstimate: rawMessage.sizeEstimate ?? undefined,
+    snippet: rawMessage.snippet ?? undefined,
+    subject: parsed.subject ?? "",
+    text:
+      parsed.text ??
+      (parsed.html === undefined ? undefined : HTML_TO_TEXT(parsed.html)),
+    threadId: rawMessage.threadId,
+    to: flattenAddresses(parsed.to),
+  }
+}
+
+/**
+ * Resolves the headers and recipients needed to create a reply.
+ *
+ * @param gmailApi - Authenticated Gmail client.
+ * @param message - Gmail message receiving the reply.
+ * @param replyAll - Whether to include the original To and Cc recipients.
+ */
+export async function getReplyOptions(
+  gmailApi: gmail_v1.Gmail,
+  message: gmail_v1.Schema$Message,
+  replyAll: boolean,
+) {
+  if (!message.threadId) throw new Error("Gmail message has no thread ID.")
+
+  const headers = getHeadersAsMap(message.payload?.headers)
+  const inReplyTo = headers.get("message-id")
+  const replyAddress = headers.get("reply-to") ?? headers.get("from")
+  const subject = headers.get("subject")
+  if (!inReplyTo || !replyAddress || !subject) {
+    throw new Error("Gmail message is missing required reply headers.")
+  }
+
+  return {
+    cc: replyAll
+      ? await getReplyAllCc(gmailApi, headers, replyAddress)
+      : undefined,
+    inReplyTo,
+    references: [
+      ...(headers.get("references")?.trim().split(/\s+/) ?? []),
+      inReplyTo,
+    ],
+    subject,
+    threadId: message.threadId,
+    to: replyAddress,
+  }
+}
+
+/**
+ * Parses a raw Gmail message with MIME charset and attachment handling.
+ *
+ * @param raw - Base64url-encoded RFC 5322 message.
+ */
+export async function parseRawMessage(raw: string) {
+  return await PostalMime.parse(Buffer.from(raw, "base64url"), {
+    attachmentEncoding: "arraybuffer",
+    rfc822Attachments: true,
+  })
+}
+
+/**
+ * Converts optional singular or plural recipients to an array.
+ *
+ * @param recipients - One recipient, many recipients, or no recipients.
+ */
+export function normalizeRecipients(
+  recipients:
+    | z.input<typeof RECIPIENT_SCHEMA>
+    | z.input<typeof RECIPIENT_SCHEMA>[]
+    | undefined,
+) {
+  return recipients === undefined
+    ? []
+    : Array.isArray(recipients)
+      ? recipients
+      : [recipients]
+}
+
+/**
+ * Fetches the metadata needed for message predicates and replies.
+ *
+ * @param gmailApi - Authenticated Gmail client.
+ * @param messageId - Immutable Gmail message ID.
+ */
+export async function getMessageMetadata(
+  gmailApi: gmail_v1.Gmail,
+  messageId: string,
+) {
+  return (
+    await gmailApi.users.messages.get({
+      format: "metadata",
+      id: messageId,
+      userId: "me",
+    })
+  ).data
+}
+
+/**
+ * Requires Gmail to identify a created or mutated message.
+ *
+ * @param message - Gmail message response.
+ * @param operation - Operation named in failure output.
+ * @throws When Gmail omits the message or thread ID.
+ */
+export function toMessageMetadata(
+  message: gmail_v1.Schema$Message,
+  operation: string,
+): z.output<typeof MESSAGE_METADATA_SCHEMA> {
+  if (!message.id || !message.threadId) {
+    throw new Error(`Gmail did not identify the ${operation}.`)
+  }
+  return {
+    historyId: message.historyId ?? undefined,
+    labelIds: message.labelIds ?? [],
+    messageId: message.id,
+    threadId: message.threadId,
+  }
+}
+
+/**
+ * Builds and sends a reply for one resolved Gmail message.
+ *
+ * @param gmailApi - Authenticated Gmail client.
+ * @param original - Message receiving the reply.
+ * @param input - Reply body, recipients, headers, and attachments.
+ */
+export async function sendReply(
+  gmailApi: gmail_v1.Gmail,
+  original: gmail_v1.Schema$Message,
+  input: z.input<typeof REPLY_OPTIONS_SCHEMA>,
+) {
+  const replyOptions = await getReplyOptions(
+    gmailApi,
+    original,
+    input.replyAll ?? false,
+  )
+  return toMessageMetadata(
+    (
+      await gmailApi.users.messages.send({
+        requestBody: {
+          raw: await buildRawMessage({
+            ...getReplyMessageOptions(replyOptions, input),
+            bcc: input.bcc,
+            from: input.from,
+            headers: input.headers,
+            html: input.html,
+            priority: input.priority,
+            replyTo: input.replyTo,
+            text: input.text,
+          }),
+          threadId: replyOptions.threadId,
+        },
+        userId: "me",
+      })
+    ).data,
+    "reply",
+  )
+}
+
+/**
+ * Combines derived reply headers with caller-supplied recipients.
+ *
+ * @param reply - Reply fields derived from the original message.
+ * @param input - Optional reply overrides and additional recipients.
+ */
+export function getReplyMessageOptions(
+  reply: Awaited<ReturnType<typeof getReplyOptions>>,
+  input: z.input<typeof REPLY_OPTIONS_SCHEMA>,
+) {
+  return {
+    attachments: input.attachments,
+    cc: [...(reply.cc ?? []), ...normalizeRecipients(input.cc)],
+    inReplyTo: reply.inReplyTo,
+    references: reply.references,
+    subject: reply.subject,
+    to: [reply.to, ...normalizeRecipients(input.to)],
+  }
+}
+
+/**
+ * Requires Gmail to identify a created or updated draft and its message.
+ *
+ * @param draft - Gmail draft response.
+ * @param operation - Operation named in failure output.
+ * @throws When Gmail omits the draft, message, or thread identity.
+ */
+export function toDraftIdentifier(
+  draft: gmail_v1.Schema$Draft,
+  operation: string,
+): z.output<typeof DRAFT_IDENTIFIER_SCHEMA> {
+  if (!draft.id || !draft.message) {
+    throw new Error(`Gmail did not identify the ${operation}.`)
+  }
+  return {
+    draftId: draft.id,
+    ...toMessageMetadata(draft.message, `${operation} message`),
+  }
+}
+
+/**
+ * Converts a Gmail label resource to its documented public representation.
+ *
+ * @param label - Gmail label resource.
+ * @throws When Gmail omits required label fields or returns invalid metadata.
+ */
+export function toGmailLabel(
+  label: gmail_v1.Schema$Label,
+): z.output<typeof LABEL_SCHEMA> {
+  if (!label.id || !label.name) {
+    throw new Error("Gmail returned an incomplete label.")
+  }
+  return {
+    ...(label.color?.backgroundColor &&
+      label.color.textColor && {
+        color: {
+          backgroundColor: label.color.backgroundColor,
+          textColor: label.color.textColor,
+        },
+      }),
+    labelId: label.id,
+    labelListVisibility: label.labelListVisibility
+      ? LABEL_LIST_VISIBILITY_SCHEMA.parse(label.labelListVisibility)
+      : undefined,
+    messageListVisibility:
+      label.messageListVisibility === null ||
+      label.messageListVisibility === undefined
+        ? undefined
+        : MESSAGE_LIST_VISIBILITY_SCHEMA.parse(label.messageListVisibility),
+    messagesTotal: label.messagesTotal ?? undefined,
+    messagesUnread: label.messagesUnread ?? undefined,
+    name: label.name,
+    threadsTotal: label.threadsTotal ?? undefined,
+    threadsUnread: label.threadsUnread ?? undefined,
+    type: label.type ? LABEL_TYPE_SCHEMA.parse(label.type) : undefined,
+  }
+}
+
+/**
+ * Converts one parsed PostalMime attachment into a File-backed attachment.
+ *
+ * @param attachment - Parsed MIME attachment.
+ */
+function toAttachment(attachment: Attachment) {
+  const mimeType = attachment.mimeType || "application/octet-stream"
+  const filename = attachment.filename || "attachment"
+  return {
+    contentId: attachment.contentId,
+    description: attachment.description,
+    disposition: attachment.disposition ?? undefined,
+    file: new File(
+      [
+        attachment.content instanceof ArrayBuffer
+          ? new Uint8Array(attachment.content)
+          : typeof attachment.content === "string"
+            ? attachment.content
+            : Uint8Array.from(attachment.content),
+      ],
+      filename,
+      { type: mimeType },
+    ),
+    filename,
+    mimeType,
+    related: attachment.related ?? false,
+  }
+}
+
+/**
+ * Flattens parsed mailbox groups into code-friendly mailbox values.
+ *
+ * @param addresses - One parsed address or an address list.
+ */
+function flattenAddresses(
+  addresses: Address | Address[] | undefined,
+): z.output<typeof MAILBOX_SCHEMA>[] {
+  return (Array.isArray(addresses) ? addresses : addresses ? [addresses] : [])
+    .flatMap((address) => address.group ?? [address])
+    .filter((address): address is Address & { address: string } =>
+      Boolean(address.address),
+    )
+    .map(({ address, name }) => ({
+      address,
+      ...(name && { name }),
+    }))
+}
+
+/**
+ * Formats one PostalMime address or group.
+ *
+ * @param address - Parsed address.
+ */
+export function formatAddress(address: Address): string {
+  if (address.group) {
+    return `${address.name}: ${address.group.map(formatAddress).join(", ")}`
+  }
+  if (!address.address) return address.name
+  return address.name ? `${address.name} <${address.address}>` : address.address
+}
+
+/**
+ * Converts MIME headers into a lowercase-keyed map.
+ *
+ * @param headers - Gmail MIME headers.
+ */
+function getHeadersAsMap(
+  headers: gmail_v1.Schema$MessagePartHeader[] | undefined,
+) {
+  return new Map(
+    headers
+      ?.filter(
+        (
+          header,
+        ): header is {
+          name: string
+          value: string
+        } => Boolean(header.name && header.value),
+      )
+      .map((header) => [header.name.toLowerCase(), header.value] as const) ??
+      [],
+  )
+}
+
+/**
+ * Builds a deduplicated reply-all Cc list.
+ *
+ * @param gmailApi - Authenticated Gmail client.
+ * @param headers - Original message headers.
+ * @param replyAddress - Primary reply recipient.
+ */
+async function getReplyAllCc(
+  gmailApi: gmail_v1.Gmail,
+  headers: Map<string, string>,
+  replyAddress: string,
+) {
+  const {
+    data: { emailAddress },
+  } = await gmailApi.users.getProfile({ userId: "me" })
+  const excluded = new Set([
+    ...(emailAddress ? [emailAddress] : []),
+    ...addressParser(replyAddress, { flatten: true }).flatMap((address) =>
+      address.address ? [address.address] : [],
+    ),
+  ])
+  return [
+    ...new Map(
+      [headers.get("to"), headers.get("cc")]
+        .flatMap((header) =>
+          header ? addressParser(header, { flatten: true }) : [],
+        )
+        .filter((address): address is Address & { address: string } =>
+          Boolean(address.address && !excluded.has(address.address)),
+        )
+        .map((address) => [address.address, formatAddress(address)]),
+    ).values(),
+  ]
+}

package/src/gmail/index.ts

@@ -0,0 +1,26 @@
+import { z } from "zod"
+import { LABEL_CHANGE_SCHEMA, MESSAGE_SCHEMA } from "./schemas"
+
+export * from "./gmail"
+export * from "./schemas"
+
+export const GMAIL_TRIGGER_CONFIG_SCHEMA = z.object({})
+
+export const gmailTriggerContracts = {
+  "gmail.label.added": {
+    configSchema: GMAIL_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: LABEL_CHANGE_SCHEMA,
+  },
+  "gmail.label.removed": {
+    configSchema: GMAIL_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: LABEL_CHANGE_SCHEMA,
+  },
+  "gmail.message.received": {
+    configSchema: GMAIL_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: MESSAGE_SCHEMA,
+  },
+  "gmail.message.sent": {
+    configSchema: GMAIL_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: MESSAGE_SCHEMA,
+  },
+} as const