automate.ax 0.3.1 → 0.4.1

package/dist/components/gmail/lib/gmail.d.ts

@@ -0,0 +1,178 @@
+import { type gmail_v1 } from "@googleapis/gmail";
+import { type Address } from "postal-mime";
+import { z } from "zod";
+import { ATTACHMENT_INPUT_SCHEMA, DRAFT_IDENTIFIER_SCHEMA, LABEL_SCHEMA, MESSAGE_METADATA_SCHEMA, MESSAGE_SCHEMA, RECIPIENT_SCHEMA, REPLY_OPTIONS_SCHEMA } from "./schemas.js";
+/** 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 declare function getGmailApi(secret: Record<string, unknown>): gmail_v1.Gmail;
+/**
+ * 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 declare function buildRawMessage(options: BuildMessageOptions): Promise<string>;
+/**
+ * Resolves a Gmail label name or ID to its canonical ID.
+ *
+ * @param gmailApi - Authenticated Gmail client.
+ * @param labelSearch - Label display name or ID.
+ */
+export declare function findLabelId(gmailApi: gmail_v1.Gmail, labelSearch: string): Promise<string>;
+/**
+ * Resolves Gmail label names or IDs with one label-list request.
+ *
+ * @param gmailApi - Authenticated Gmail client.
+ * @param labelSearches - Label display names or IDs.
+ */
+export declare function findLabelIds(gmailApi: gmail_v1.Gmail, labelSearches: string[]): Promise<string[]>;
+/**
+ * Normalizes a raw Gmail API message into the public message representation.
+ *
+ * @param rawMessage - Gmail message fetched with `format: "raw"`.
+ */
+export declare function getGmailMessage(rawMessage: gmail_v1.Schema$Message): Promise<z.output<typeof MESSAGE_SCHEMA>>;
+/**
+ * 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 declare function getReplyOptions(gmailApi: gmail_v1.Gmail, message: gmail_v1.Schema$Message, replyAll: boolean): Promise<{
+    cc: string[] | undefined;
+    inReplyTo: string;
+    references: string[];
+    subject: string;
+    threadId: string;
+    to: string;
+}>;
+/**
+ * Parses a raw Gmail message with MIME charset and attachment handling.
+ *
+ * @param raw - Base64url-encoded RFC 5322 message.
+ */
+export declare function parseRawMessage(raw: string): Promise<import("postal-mime").Email>;
+/**
+ * Converts one or many message IDs to the array required by Gmail batch APIs.
+ *
+ * @param messageIds - One Gmail message ID or an existing array.
+ */
+export declare function normalizeMessageIds(messageIds: string | string[]): string[];
+/**
+ * Converts optional singular or plural recipients to an array.
+ *
+ * @param recipients - One recipient, many recipients, or no recipients.
+ */
+export declare function normalizeRecipients(recipients: z.input<typeof RECIPIENT_SCHEMA> | z.input<typeof RECIPIENT_SCHEMA>[] | undefined): (string | {
+    address: string;
+    name?: string | undefined;
+})[];
+/**
+ * Fetches the metadata needed for message predicates and replies.
+ *
+ * @param gmailApi - Authenticated Gmail client.
+ * @param messageId - Immutable Gmail message ID.
+ */
+export declare function getMessageMetadata(gmailApi: gmail_v1.Gmail, messageId: string): Promise<gmail_v1.Schema$Message>;
+/**
+ * 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 declare function toMessageMetadata(message: gmail_v1.Schema$Message, operation: string): z.output<typeof MESSAGE_METADATA_SCHEMA>;
+/**
+ * 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 declare function sendReply(gmailApi: gmail_v1.Gmail, original: gmail_v1.Schema$Message, input: z.input<typeof REPLY_OPTIONS_SCHEMA>): Promise<{
+    messageId: string;
+    threadId: string;
+    labelIds: string[];
+    historyId?: string | undefined;
+}>;
+/**
+ * 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 declare function getReplyMessageOptions(reply: Awaited<ReturnType<typeof getReplyOptions>>, input: z.input<typeof REPLY_OPTIONS_SCHEMA>): {
+    attachments: (File | {
+        file: File;
+        contentId?: string | undefined;
+        disposition?: "attachment" | "inline" | undefined;
+        filename?: string | undefined;
+    })[] | undefined;
+    cc: (string | {
+        address: string;
+        name?: string | undefined;
+    })[];
+    inReplyTo: string;
+    references: string[];
+    subject: string;
+    to: (string | {
+        address: string;
+        name?: string | undefined;
+    })[];
+};
+/**
+ * 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 declare function toDraftIdentifier(draft: gmail_v1.Schema$Draft, operation: string): z.output<typeof DRAFT_IDENTIFIER_SCHEMA>;
+/**
+ * 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 declare function toGmailLabel(label: gmail_v1.Schema$Label): z.output<typeof LABEL_SCHEMA>;
+/**
+ * Formats one PostalMime address or group.
+ *
+ * @param address - Parsed address.
+ */
+export declare function formatAddress(address: Address): string;
+//# sourceMappingURL=gmail.d.ts.map

package/dist/components/gmail/lib/gmail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gmail.d.ts","sourceRoot":"","sources":["../../../../src/components/gmail/lib/gmail.ts"],"names":[],"mappings":"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"}

package/dist/components/gmail/lib/gmail.js

@@ -0,0 +1,411 @@
+import { auth, gmail } from "@googleapis/gmail";
+import { compile } from "html-to-text";
+import MailComposer from "nodemailer/lib/mail-composer";
+import PostalMime, { addressParser, } from "postal-mime";
+import { z } from "zod";
+const AUTOMATE_EMAIL_HEADERS = {
+    "X-Mailer": "Automate.ax",
+    "X-Sent-From-Automate-Ax": "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"]);
+/**
+ * Creates the official Gmail client from a resolved Google integration secret.
+ *
+ * @param secret - Refreshed Google integration secret.
+ */
+export function getGmailApi(secret) {
+    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) {
+    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, labelSearch) {
+    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, labelSearches) {
+    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) {
+    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, message, replyAll) {
+    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) {
+    return await PostalMime.parse(Buffer.from(raw, "base64url"), {
+        attachmentEncoding: "arraybuffer",
+        rfc822Attachments: true,
+    });
+}
+// FIX: this could just be zippy castArray
+/**
+ * Converts one or many message IDs to the array required by Gmail batch APIs.
+ *
+ * @param messageIds - One Gmail message ID or an existing array.
+ */
+export function normalizeMessageIds(messageIds) {
+    return typeof messageIds === "string" ? [messageIds] : messageIds;
+}
+/**
+ * Converts optional singular or plural recipients to an array.
+ *
+ * @param recipients - One recipient, many recipients, or no recipients.
+ */
+export function normalizeRecipients(recipients) {
+    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, messageId) {
+    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, operation) {
+    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, original, input) {
+    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, input) {
+    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, operation) {
+    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) {
+    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) {
+    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)
+                : 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) {
+    return (Array.isArray(addresses) ? addresses : addresses ? [addresses] : [])
+        .flatMap((address) => address.group ?? [address])
+        .filter((address) => Boolean(address.address))
+        .map(({ address, name }) => ({
+        address,
+        ...(name && { name }),
+    }));
+}
+/**
+ * Formats one PostalMime address or group.
+ *
+ * @param address - Parsed address.
+ */
+export function formatAddress(address) {
+    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) {
+    return new Map(headers
+        ?.filter((header) => Boolean(header.name && header.value))
+        .map((header) => [header.name.toLowerCase(), header.value]) ??
+        []);
+}
+/**
+ * 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, headers, replyAddress) {
+    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) => Boolean(address.address && !excluded.has(address.address)))
+            .map((address) => [address.address, formatAddress(address)])).values(),
+    ];
+}