@kubun/connector-google-mail 0.12.0

package/LICENSE.md

@@ -0,0 +1,57 @@
+# The Prosperity Public License 3.0.0
+
+Contributor: Paul Le Cam
+
+Source Code: https://github.com/PaulLeCam/kubun
+
+## Purpose
+
+This license allows you to use and share this software for noncommercial purposes for free and to try this software for commercial purposes for thirty days.
+
+## Agreement
+
+In order to receive this license, you have to agree to its rules.  Those rules are both obligations under that agreement and conditions to your license.  Don't do anything with this software that triggers a rule you can't or won't follow.
+
+## Notices
+
+Make sure everyone who gets a copy of any part of this software from you, with or without changes, also gets the text of this license and the contributor and source code lines above.
+
+## Commercial Trial
+
+Limit your use of this software for commercial purposes to a thirty-day trial period.  If you use this software for work, your company gets one trial period for all personnel, not one trial per person.
+
+## Contributions Back
+
+Developing feedback, changes, or additions that you contribute back to the contributor on the terms of a standardized public software license such as [the Blue Oak Model License 1.0.0](https://blueoakcouncil.org/license/1.0.0), [the Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html), [the MIT license](https://spdx.org/licenses/MIT.html), or [the two-clause BSD license](https://spdx.org/licenses/BSD-2-Clause.html) doesn't count as use for a commercial purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, doesn't count as use for a commercial purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution doesn't count as use for a commercial purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Defense
+
+Don't make any legal claim against anyone accusing this software, with or without changes, alone or with other technology, of infringing any patent.
+
+## Copyright
+
+The contributor licenses you to do everything with this software that would otherwise infringe their copyright in it.
+
+## Patent
+
+The contributor licenses you to do everything with this software that would otherwise infringe any patents they can license or become able to license.
+
+## Reliability
+
+The contributor can't revoke this license.
+
+## Excuse
+
+You're excused for unknowingly breaking [Notices](#notices) if you take all practical steps to comply within thirty days of learning you broke the rule.
+
+## No Liability
+
+***As far as the law allows, this software comes as is, without any warranty or condition, and the contributor won't be liable to anyone for any damages related to this software or this license, under any kind of legal claim.***

package/lib/actions.d.ts

@@ -0,0 +1,9 @@
+import type { ActionHandler } from '@kubun/connector';
+export type GoogleMailActionHandlerConfig = {
+    credential: {
+        accessToken: string;
+        scopes: Array<string>;
+    };
+    fetch?: typeof globalThis.fetch;
+};
+export declare function createGoogleMailActionHandler(config: GoogleMailActionHandlerConfig): ActionHandler;

package/lib/actions.js

@@ -0,0 +1,43 @@
+import { createDraft, createLabel, modifyLabels, sendMessage, updateLabel } from './api.js';
+export function createGoogleMailActionHandler(config) {
+    return {
+        async create (model, params) {
+            if (model === 'GoogleMailLabel') {
+                return createLabel({
+                    accessToken: config.credential.accessToken,
+                    params,
+                    fetch: config.fetch
+                });
+            }
+            if (params.draft === true) {
+                return createDraft({
+                    accessToken: config.credential.accessToken,
+                    params,
+                    fetch: config.fetch
+                });
+            }
+            return sendMessage({
+                accessToken: config.credential.accessToken,
+                params,
+                fetch: config.fetch
+            });
+        },
+        async update (model, sourceID, params) {
+            if (model === 'GoogleMailLabel') {
+                return updateLabel({
+                    accessToken: config.credential.accessToken,
+                    labelID: sourceID,
+                    params,
+                    fetch: config.fetch
+                });
+            }
+            return modifyLabels({
+                accessToken: config.credential.accessToken,
+                messageID: sourceID,
+                addLabelIds: params.addLabelIds,
+                removeLabelIds: params.removeLabelIds,
+                fetch: config.fetch
+            });
+        }
+    };
+}

package/lib/api.d.ts

@@ -0,0 +1,125 @@
+import type { EntityRecord } from '@kubun/connector';
+export declare const MAIL_BASE_URL = "https://gmail.googleapis.com/gmail/v1";
+export declare function parseGoogleError(response: Response): Promise<string>;
+export declare function decodeBase64Url(data: string): string;
+export declare function encodeBase64Url(text: string): string;
+export declare function buildMessagesListURL(params: {
+    query: string;
+    pageToken?: string;
+}): string;
+export declare function buildMessageGetURL(params: {
+    messageID: string;
+}): string;
+export declare function buildHistoryListURL(params: {
+    startHistoryId: string;
+    pageToken?: string;
+}): string;
+export declare function buildProfileURL(): string;
+export declare function buildLabelsListURL(): string;
+export type GmailLabelResource = {
+    id: string;
+    name: string;
+    type?: string;
+    messageListVisibility?: string;
+    labelListVisibility?: string;
+    color?: {
+        textColor?: string;
+        backgroundColor?: string;
+    };
+};
+export type GmailLabelsListResponse = {
+    labels?: Array<GmailLabelResource>;
+};
+export declare function mapLabelToEntity(label: GmailLabelResource): EntityRecord;
+export type GmailHistoryMessageRef = {
+    message: {
+        id: string;
+        threadId: string;
+    };
+};
+export type GmailHistoryRecord = {
+    id: string;
+    messagesAdded?: Array<GmailHistoryMessageRef>;
+    messagesDeleted?: Array<GmailHistoryMessageRef>;
+    labelsAdded?: Array<GmailHistoryMessageRef>;
+    labelsRemoved?: Array<GmailHistoryMessageRef>;
+};
+export type GmailHistoryListResponse = {
+    history?: Array<GmailHistoryRecord>;
+    nextPageToken?: string;
+    historyId?: string;
+};
+export type GmailMessagePart = {
+    mimeType?: string;
+    filename?: string;
+    headers?: Array<{
+        name: string;
+        value: string;
+    }>;
+    body?: {
+        size?: number;
+        data?: string;
+        attachmentId?: string;
+    };
+    parts?: Array<GmailMessagePart>;
+};
+export type GmailMessageResource = {
+    id: string;
+    threadId: string;
+    labelIds?: Array<string>;
+    snippet?: string;
+    historyId?: string;
+    internalDate?: string;
+    payload?: GmailMessagePart;
+};
+export type GmailMessagesListResponse = {
+    messages?: Array<{
+        id: string;
+        threadId: string;
+    }>;
+    nextPageToken?: string;
+    resultSizeEstimate?: number;
+};
+export declare function getHeader(headers: Array<{
+    name: string;
+    value: string;
+}> | undefined, name: string): string | undefined;
+export declare function extractEmail(headerValue: string): string;
+export declare function extractEmails(headerValue: string | undefined): Array<string>;
+export declare function mapMessageToEntity(message: GmailMessageResource): EntityRecord;
+export declare function mapThreadToEntity(threadID: string, subject: string | undefined): EntityRecord;
+export declare function buildRawMessage(params: {
+    to: string | Array<string>;
+    subject: string;
+    body: string;
+    cc?: string | Array<string>;
+    bcc?: string | Array<string>;
+}): string;
+export declare function sendMessage(config: {
+    accessToken: string;
+    params: Record<string, unknown>;
+    fetch?: typeof globalThis.fetch;
+}): Promise<EntityRecord>;
+export declare function createDraft(config: {
+    accessToken: string;
+    params: Record<string, unknown>;
+    fetch?: typeof globalThis.fetch;
+}): Promise<EntityRecord>;
+export declare function modifyLabels(config: {
+    accessToken: string;
+    messageID: string;
+    addLabelIds?: Array<string>;
+    removeLabelIds?: Array<string>;
+    fetch?: typeof globalThis.fetch;
+}): Promise<EntityRecord>;
+export declare function createLabel(config: {
+    accessToken: string;
+    params: Record<string, unknown>;
+    fetch?: typeof globalThis.fetch;
+}): Promise<EntityRecord>;
+export declare function updateLabel(config: {
+    accessToken: string;
+    labelID: string;
+    params: Record<string, unknown>;
+    fetch?: typeof globalThis.fetch;
+}): Promise<EntityRecord>;

package/lib/api.js

@@ -0,0 +1,313 @@
+export const MAIL_BASE_URL = 'https://gmail.googleapis.com/gmail/v1';
+export async function parseGoogleError(response) {
+    try {
+        const body = await response.json();
+        return body.error?.message ?? `${response.status} ${response.statusText}`;
+    } catch  {
+        return `${response.status} ${response.statusText}`;
+    }
+}
+export function decodeBase64Url(data) {
+    return Buffer.from(data, 'base64url').toString('utf8');
+}
+export function encodeBase64Url(text) {
+    return Buffer.from(text, 'utf8').toString('base64url');
+}
+export function buildMessagesListURL(params) {
+    const url = new URL(`${MAIL_BASE_URL}/users/me/messages`);
+    url.searchParams.set('q', params.query);
+    if (params.pageToken != null) url.searchParams.set('pageToken', params.pageToken);
+    return url.toString();
+}
+export function buildMessageGetURL(params) {
+    const url = new URL(`${MAIL_BASE_URL}/users/me/messages/${encodeURIComponent(params.messageID)}`);
+    url.searchParams.set('format', 'full');
+    return url.toString();
+}
+export function buildHistoryListURL(params) {
+    const url = new URL(`${MAIL_BASE_URL}/users/me/history`);
+    url.searchParams.set('startHistoryId', params.startHistoryId);
+    if (params.pageToken != null) url.searchParams.set('pageToken', params.pageToken);
+    return url.toString();
+}
+export function buildProfileURL() {
+    return `${MAIL_BASE_URL}/users/me/profile`;
+}
+export function buildLabelsListURL() {
+    return `${MAIL_BASE_URL}/users/me/labels`;
+}
+export function mapLabelToEntity(label) {
+    return {
+        sourceService: 'google-mail',
+        sourceID: label.id,
+        sourceURL: `https://mail.google.com/mail/u/0/#label/${encodeURIComponent(label.name)}`,
+        name: label.name,
+        type: label.type,
+        messageListVisibility: label.messageListVisibility,
+        labelListVisibility: label.labelListVisibility,
+        textColor: label.color?.textColor,
+        backgroundColor: label.color?.backgroundColor
+    };
+}
+export function getHeader(headers, name) {
+    const lower = name.toLowerCase();
+    return headers?.find((h)=>h.name.toLowerCase() === lower)?.value;
+}
+export function extractEmail(headerValue) {
+    const match = /<([^>]+)>/.exec(headerValue);
+    return (match != null ? match[1] : headerValue).trim();
+}
+export function extractEmails(headerValue) {
+    if (headerValue == null || headerValue.trim() === '') return [];
+    return headerValue.split(',').map((part)=>extractEmail(part));
+}
+function findPartByMime(part, mime) {
+    if (part.mimeType === mime && part.body?.data != null) return part;
+    for (const child of part.parts ?? []){
+        const found = findPartByMime(child, mime);
+        if (found != null) return found;
+    }
+    return undefined;
+}
+function extractBody(payload) {
+    if (payload == null) return '';
+    const plain = findPartByMime(payload, 'text/plain');
+    if (plain?.body?.data != null) return decodeBase64Url(plain.body.data);
+    const html = findPartByMime(payload, 'text/html');
+    if (html?.body?.data != null) return decodeBase64Url(html.body.data);
+    if (payload.body?.data != null) return decodeBase64Url(payload.body.data);
+    return '';
+}
+function extractAttachments(payload) {
+    const out = [];
+    function walk(part) {
+        if (part.filename != null && part.filename !== '' && part.body?.attachmentId != null) {
+            out.push({
+                filename: part.filename,
+                mimeType: part.mimeType ?? 'application/octet-stream'
+            });
+        }
+        for (const child of part.parts ?? [])walk(child);
+    }
+    walk(payload ?? {});
+    return out;
+}
+export function mapMessageToEntity(message) {
+    const headers = message.payload?.headers;
+    const labels = message.labelIds ?? [];
+    const sentAtMs = message.internalDate != null ? Number.parseInt(message.internalDate, 10) : Number.NaN;
+    return {
+        sourceService: 'google-mail',
+        sourceID: message.id,
+        sourceURL: `https://mail.google.com/mail/u/0/#inbox/${message.id}`,
+        body: extractBody(message.payload),
+        sender: extractEmail(getHeader(headers, 'From') ?? ''),
+        subject: getHeader(headers, 'Subject'),
+        snippet: message.snippet,
+        to: extractEmails(getHeader(headers, 'To')),
+        cc: extractEmails(getHeader(headers, 'Cc')),
+        labels,
+        unread: labels.includes('UNREAD'),
+        sentAt: Number.isNaN(sentAtMs) ? undefined : new Date(sentAtMs).toISOString(),
+        attachments: extractAttachments(message.payload),
+        threadID: message.threadId,
+        thread: {
+            sourceService: 'google-mail',
+            sourceID: message.threadId
+        }
+    };
+}
+export function mapThreadToEntity(threadID, subject) {
+    return {
+        sourceService: 'google-mail',
+        sourceID: threadID,
+        sourceURL: `https://mail.google.com/mail/u/0/#inbox/${threadID}`,
+        title: subject
+    };
+}
+function requireNoNewline(value) {
+    if (value.includes('\r') || value.includes('\n')) {
+        throw new Error('Google Mail: header field contains illegal newline');
+    }
+    return value;
+}
+// Recipients arrive either as an array (GraphQL JSON) or a comma-separated string.
+// Normalize to a trimmed, non-empty list; `to` must resolve to at least one address.
+function normalizeRecipients(value, key, required) {
+    let list;
+    if (Array.isArray(value)) {
+        list = value.map((v)=>String(v));
+    } else if (typeof value === 'string') {
+        list = value.split(',');
+    } else if (value == null) {
+        list = [];
+    } else {
+        throw new Error(`Google Mail: "${key}" must be a string or array of strings`);
+    }
+    const cleaned = list.map((s)=>s.trim()).filter((s)=>s !== '');
+    if (required && cleaned.length === 0) {
+        throw new Error(`Google Mail: "${key}" is required`);
+    }
+    return cleaned;
+}
+export function buildRawMessage(params) {
+    const to = normalizeRecipients(params.to, 'to', true).map(requireNoNewline);
+    const cc = normalizeRecipients(params.cc, 'cc', false).map(requireNoNewline);
+    const bcc = normalizeRecipients(params.bcc, 'bcc', false).map(requireNoNewline);
+    const lines = [
+        `To: ${to.join(', ')}`
+    ];
+    if (cc.length > 0) lines.push(`Cc: ${cc.join(', ')}`);
+    if (bcc.length > 0) lines.push(`Bcc: ${bcc.join(', ')}`);
+    lines.push(`Subject: ${requireNoNewline(params.subject)}`, 'Content-Type: text/plain; charset="UTF-8"', 'MIME-Version: 1.0', '', params.body);
+    return encodeBase64Url(lines.join('\r\n'));
+}
+function requireString(params, key) {
+    const value = params[key];
+    if (typeof value !== 'string' || value === '') {
+        throw new Error(`Google Mail: "${key}" is required`);
+    }
+    return value;
+}
+// Gmail's write endpoints (messages.send, drafts.create, messages.modify) return only
+// { id, threadId, labelIds } -- no payload/headers/body. Re-fetch the full message so the
+// mapped entity carries real sender/body/subject/etc. instead of empty placeholders.
+async function fetchAndMapMessage(config) {
+    const fetchFn = config.fetch ?? globalThis.fetch;
+    const response = await fetchFn(buildMessageGetURL({
+        messageID: config.messageID
+    }), {
+        headers: {
+            Authorization: `Bearer ${config.accessToken}`
+        }
+    });
+    if (!response.ok) throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
+    return mapMessageToEntity(await response.json());
+}
+export async function sendMessage(config) {
+    const fetchFn = config.fetch ?? globalThis.fetch;
+    const raw = buildRawMessage({
+        to: config.params.to,
+        cc: config.params.cc,
+        bcc: config.params.bcc,
+        subject: requireString(config.params, 'subject'),
+        body: requireString(config.params, 'body')
+    });
+    const response = await fetchFn(`${MAIL_BASE_URL}/users/me/messages/send`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${config.accessToken}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+            raw
+        })
+    });
+    if (!response.ok) throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
+    const sent = await response.json();
+    return fetchAndMapMessage({
+        accessToken: config.accessToken,
+        messageID: sent.id,
+        fetch: config.fetch
+    });
+}
+export async function createDraft(config) {
+    const fetchFn = config.fetch ?? globalThis.fetch;
+    const raw = buildRawMessage({
+        to: config.params.to,
+        cc: config.params.cc,
+        bcc: config.params.bcc,
+        subject: requireString(config.params, 'subject'),
+        body: requireString(config.params, 'body')
+    });
+    const response = await fetchFn(`${MAIL_BASE_URL}/users/me/drafts`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${config.accessToken}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+            message: {
+                raw
+            }
+        })
+    });
+    if (!response.ok) throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
+    const draft = await response.json();
+    return fetchAndMapMessage({
+        accessToken: config.accessToken,
+        messageID: draft.message.id,
+        fetch: config.fetch
+    });
+}
+export async function modifyLabels(config) {
+    const fetchFn = config.fetch ?? globalThis.fetch;
+    const url = `${MAIL_BASE_URL}/users/me/messages/${encodeURIComponent(config.messageID)}/modify`;
+    const response = await fetchFn(url, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${config.accessToken}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+            addLabelIds: config.addLabelIds ?? [],
+            removeLabelIds: config.removeLabelIds ?? []
+        })
+    });
+    if (!response.ok) throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
+    const modified = await response.json();
+    return fetchAndMapMessage({
+        accessToken: config.accessToken,
+        messageID: modified.id,
+        fetch: config.fetch
+    });
+}
+// Assemble the Gmail Label write body from an action's params, sending only the
+// fields the API accepts. `color` requires BOTH textColor and backgroundColor and
+// only accepts values from Gmail's fixed palette; send it only when both are given.
+function buildLabelBody(params) {
+    const body = {};
+    if (typeof params.name === 'string') body.name = requireNoNewline(params.name);
+    if (typeof params.messageListVisibility === 'string') {
+        body.messageListVisibility = params.messageListVisibility;
+    }
+    if (typeof params.labelListVisibility === 'string') {
+        body.labelListVisibility = params.labelListVisibility;
+    }
+    if (typeof params.textColor === 'string' && typeof params.backgroundColor === 'string') {
+        body.color = {
+            textColor: params.textColor,
+            backgroundColor: params.backgroundColor
+        };
+    }
+    return body;
+}
+export async function createLabel(config) {
+    const fetchFn = config.fetch ?? globalThis.fetch;
+    const body = buildLabelBody(config.params);
+    if (typeof body.name !== 'string') throw new Error('Google Mail: "name" is required');
+    const response = await fetchFn(buildLabelsListURL(), {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${config.accessToken}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(body)
+    });
+    if (!response.ok) throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
+    return mapLabelToEntity(await response.json());
+}
+export async function updateLabel(config) {
+    const fetchFn = config.fetch ?? globalThis.fetch;
+    const url = `${MAIL_BASE_URL}/users/me/labels/${encodeURIComponent(config.labelID)}`;
+    const response = await fetchFn(url, {
+        method: 'PATCH',
+        headers: {
+            Authorization: `Bearer ${config.accessToken}`,
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(buildLabelBody(config.params))
+    });
+    if (!response.ok) throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
+    return mapLabelToEntity(await response.json());
+}

package/lib/connector.d.ts

@@ -0,0 +1,6 @@
+import type { ConnectorDefinition } from '@kubun/connector';
+export type CreateGoogleMailConnectorOptions = {
+    fetch?: typeof globalThis.fetch;
+    query?: string;
+};
+export declare function createGoogleMailConnector(options?: CreateGoogleMailConnectorOptions): ConnectorDefinition;

package/lib/connector.js

@@ -0,0 +1,133 @@
+import { createGoogleMailActionHandler } from './actions.js';
+import { googleMailClusters } from './model.js';
+import { createGoogleMailProvider, DEFAULT_QUERY } from './provider.js';
+export function createGoogleMailConnector(options) {
+    return {
+        name: 'google-mail',
+        version: '1.0.0',
+        clusters: googleMailClusters,
+        syncStrategies: [
+            'on-demand'
+        ],
+        actions: [
+            {
+                name: 'create',
+                description: 'On GoogleMailMessage: send a message (or create a draft when draft is true). On GoogleMailLabel: create a label.',
+                input: {
+                    type: 'object',
+                    properties: {
+                        // GoogleMailMessage
+                        to: {
+                            type: 'array',
+                            items: {
+                                type: 'string'
+                            }
+                        },
+                        cc: {
+                            type: 'array',
+                            items: {
+                                type: 'string'
+                            }
+                        },
+                        bcc: {
+                            type: 'array',
+                            items: {
+                                type: 'string'
+                            }
+                        },
+                        subject: {
+                            type: 'string'
+                        },
+                        body: {
+                            type: 'string'
+                        },
+                        draft: {
+                            type: 'boolean'
+                        },
+                        // GoogleMailLabel
+                        name: {
+                            type: 'string'
+                        },
+                        messageListVisibility: {
+                            type: 'string'
+                        },
+                        labelListVisibility: {
+                            type: 'string'
+                        },
+                        textColor: {
+                            type: 'string'
+                        },
+                        backgroundColor: {
+                            type: 'string'
+                        }
+                    }
+                },
+                requiresCredential: true
+            },
+            {
+                name: 'update',
+                description: 'On GoogleMailMessage: add/remove labels. On GoogleMailLabel: rename or restyle the label.',
+                input: {
+                    type: 'object',
+                    properties: {
+                        // GoogleMailMessage
+                        addLabelIds: {
+                            type: 'array',
+                            items: {
+                                type: 'string'
+                            }
+                        },
+                        removeLabelIds: {
+                            type: 'array',
+                            items: {
+                                type: 'string'
+                            }
+                        },
+                        // GoogleMailLabel
+                        name: {
+                            type: 'string'
+                        },
+                        messageListVisibility: {
+                            type: 'string'
+                        },
+                        labelListVisibility: {
+                            type: 'string'
+                        },
+                        textColor: {
+                            type: 'string'
+                        },
+                        backgroundColor: {
+                            type: 'string'
+                        }
+                    }
+                },
+                requiresCredential: true
+            }
+        ],
+        actionHandler: (config)=>{
+            return createGoogleMailActionHandler({
+                credential: config.credential,
+                fetch: options?.fetch
+            });
+        },
+        auth: {
+            provider: 'google',
+            scopes: [
+                'https://www.googleapis.com/auth/gmail.readonly'
+            ],
+            writeScopes: [
+                'https://www.googleapis.com/auth/gmail.send',
+                'https://www.googleapis.com/auth/gmail.compose',
+                'https://www.googleapis.com/auth/gmail.modify'
+            ]
+        },
+        serverProvider: (config)=>{
+            return createGoogleMailProvider({
+                credential: config.credential,
+                boundary: config.boundary,
+                fetch: options?.fetch,
+                query: options?.query ?? DEFAULT_QUERY
+            });
+        }
+    };
+}