@kubun/connector-google-mail 0.12.0

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+export { createGoogleMailActionHandler, type GoogleMailActionHandlerConfig } from './actions.js';
+export { buildHistoryListURL, buildLabelsListURL, buildMessageGetURL, buildMessagesListURL, buildProfileURL, buildRawMessage, createDraft, createLabel, decodeBase64Url, encodeBase64Url, extractEmail, extractEmails, type GmailHistoryListResponse, type GmailHistoryRecord, type GmailLabelResource, type GmailLabelsListResponse, type GmailMessagePart, type GmailMessageResource, type GmailMessagesListResponse, getHeader, mapLabelToEntity, mapMessageToEntity, mapThreadToEntity, modifyLabels, sendMessage, updateLabel, } from './api.js';
+export { type CreateGoogleMailConnectorOptions, createGoogleMailConnector } from './connector.js';
+export { googleMailClusters, googleMailLabelDefinition, googleMailMessageDefinition, googleMailThreadDefinition, } from './model.js';
+export { createGoogleMailProvider, DEFAULT_QUERY, type GoogleMailProviderConfig, type MailCheckpoint, } from './provider.js';

package/lib/index.js

@@ -0,0 +1,5 @@
+export { createGoogleMailActionHandler } from './actions.js';
+export { buildHistoryListURL, buildLabelsListURL, buildMessageGetURL, buildMessagesListURL, buildProfileURL, buildRawMessage, createDraft, createLabel, decodeBase64Url, encodeBase64Url, extractEmail, extractEmails, getHeader, mapLabelToEntity, mapMessageToEntity, mapThreadToEntity, modifyLabels, sendMessage, updateLabel } from './api.js';
+export { createGoogleMailConnector } from './connector.js';
+export { googleMailClusters, googleMailLabelDefinition, googleMailMessageDefinition, googleMailThreadDefinition } from './model.js';
+export { createGoogleMailProvider, DEFAULT_QUERY } from './provider.js';

package/lib/model.d.ts

@@ -0,0 +1,227 @@
+export declare const googleMailThreadDefinition: {
+    readonly name: "GoogleMailThread";
+    readonly behavior: "default";
+    readonly interfaces: [string, string];
+    readonly schema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly title: {
+                readonly type: "string";
+                readonly maxLength: 200;
+            };
+            readonly sourceService: {
+                readonly $ref: "#/definitions/SourceService";
+            };
+            readonly sourceID: {
+                readonly $ref: "#/definitions/SourceID";
+            };
+            readonly sourceURL: {
+                readonly $ref: "#/definitions/SourceURL";
+            };
+            readonly lastSyncedAt: {
+                readonly $ref: "#/definitions/DateTime";
+            };
+        };
+        readonly required: ["sourceService", "sourceID", "lastSyncedAt"];
+        readonly additionalProperties: false;
+        readonly definitions: {
+            readonly SourceService: {
+                readonly type: "string";
+                readonly title: "SourceService";
+                readonly minLength: 1;
+                readonly maxLength: 50;
+            };
+            readonly SourceID: {
+                readonly type: "string";
+                readonly title: "SourceID";
+                readonly minLength: 1;
+                readonly maxLength: 500;
+            };
+            readonly SourceURL: import("json-schema-typed").JSONSchema.String;
+            readonly DateTime: import("json-schema-typed").JSONSchema.String;
+        };
+    };
+    readonly fieldsMeta: {};
+};
+export declare const googleMailMessageDefinition: {
+    readonly name: "GoogleMailMessage";
+    readonly behavior: "default";
+    readonly interfaces: [string, string];
+    readonly schema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly body: {
+                readonly type: "string";
+            };
+            readonly sender: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 320;
+            };
+            readonly subject: {
+                readonly type: "string";
+            };
+            readonly snippet: {
+                readonly type: "string";
+            };
+            readonly to: {
+                readonly type: "array";
+                readonly title: "To";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly cc: {
+                readonly type: "array";
+                readonly title: "Cc";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly labels: {
+                readonly type: "array";
+                readonly title: "Labels";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly sentAt: {
+                readonly $ref: "#/definitions/DateTime";
+            };
+            readonly unread: {
+                readonly type: "boolean";
+            };
+            readonly attachments: {
+                readonly type: "array";
+                readonly title: "Attachments";
+                readonly items: {
+                    readonly $ref: "#/definitions/Attachment";
+                };
+            };
+            readonly threadID: {
+                readonly type: "string";
+            };
+            readonly thread: {
+                readonly $ref: "#/definitions/ThreadDocID";
+            };
+            readonly sourceService: {
+                readonly $ref: "#/definitions/SourceService";
+            };
+            readonly sourceID: {
+                readonly $ref: "#/definitions/SourceID";
+            };
+            readonly sourceURL: {
+                readonly $ref: "#/definitions/SourceURL";
+            };
+            readonly lastSyncedAt: {
+                readonly $ref: "#/definitions/DateTime";
+            };
+        };
+        readonly required: ["body", "sender", "threadID", "thread", "sourceService", "sourceID", "lastSyncedAt"];
+        readonly additionalProperties: false;
+        readonly definitions: {
+            readonly ThreadDocID: import("json-schema-typed").JSONSchema.String;
+            readonly Attachment: {
+                readonly type: "object";
+                readonly title: "Attachment";
+                readonly properties: {
+                    readonly filename: {
+                        readonly type: "string";
+                    };
+                    readonly mimeType: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: ["filename", "mimeType"];
+                readonly additionalProperties: false;
+            };
+            readonly SourceService: {
+                readonly type: "string";
+                readonly title: "SourceService";
+                readonly minLength: 1;
+                readonly maxLength: 50;
+            };
+            readonly SourceID: {
+                readonly type: "string";
+                readonly title: "SourceID";
+                readonly minLength: 1;
+                readonly maxLength: 500;
+            };
+            readonly SourceURL: import("json-schema-typed").JSONSchema.String;
+            readonly DateTime: import("json-schema-typed").JSONSchema.String;
+        };
+    };
+    readonly fieldsMeta: {
+        readonly thread: {
+            readonly type: "document";
+            readonly model: "#0";
+        };
+    };
+};
+export declare const googleMailLabelDefinition: {
+    readonly name: "GoogleMailLabel";
+    readonly behavior: "default";
+    readonly interfaces: [string];
+    readonly schema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly name: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 225;
+            };
+            readonly type: {
+                readonly type: "string";
+                readonly maxLength: 20;
+            };
+            readonly messageListVisibility: {
+                readonly type: "string";
+                readonly maxLength: 20;
+            };
+            readonly labelListVisibility: {
+                readonly type: "string";
+                readonly maxLength: 30;
+            };
+            readonly textColor: {
+                readonly type: "string";
+                readonly maxLength: 20;
+            };
+            readonly backgroundColor: {
+                readonly type: "string";
+                readonly maxLength: 20;
+            };
+            readonly sourceService: {
+                readonly $ref: "#/definitions/SourceService";
+            };
+            readonly sourceID: {
+                readonly $ref: "#/definitions/SourceID";
+            };
+            readonly sourceURL: {
+                readonly $ref: "#/definitions/SourceURL";
+            };
+            readonly lastSyncedAt: {
+                readonly $ref: "#/definitions/DateTime";
+            };
+        };
+        readonly required: ["name", "sourceService", "sourceID", "lastSyncedAt"];
+        readonly additionalProperties: false;
+        readonly definitions: {
+            readonly SourceService: {
+                readonly type: "string";
+                readonly title: "SourceService";
+                readonly minLength: 1;
+                readonly maxLength: 50;
+            };
+            readonly SourceID: {
+                readonly type: "string";
+                readonly title: "SourceID";
+                readonly minLength: 1;
+                readonly maxLength: 500;
+            };
+            readonly SourceURL: import("json-schema-typed").JSONSchema.String;
+            readonly DateTime: import("json-schema-typed").JSONSchema.String;
+        };
+    };
+    readonly fieldsMeta: {};
+};
+export declare const googleMailClusters: import("@kubun/protocol").ClustersRecord;

package/lib/model.js

@@ -0,0 +1,245 @@
+import { connectorClusters, connectorModelIDs } from '@kubun/connector';
+import { modelIDs, modelsClusters } from '@kubun/models';
+import { GraphBuilder } from '@kubun/protocol';
+import { dateTimeSchema, docIDSchema, urlSchema } from '@kubun/scalars';
+const commonDefinitions = {
+    SourceService: {
+        type: 'string',
+        title: 'SourceService',
+        minLength: 1,
+        maxLength: 50
+    },
+    SourceID: {
+        type: 'string',
+        title: 'SourceID',
+        minLength: 1,
+        maxLength: 500
+    },
+    SourceURL: urlSchema,
+    DateTime: dateTimeSchema
+};
+export const googleMailThreadDefinition = {
+    name: 'GoogleMailThread',
+    behavior: 'default',
+    interfaces: [
+        connectorModelIDs.ExternalEntity,
+        modelIDs.ThreadKind
+    ],
+    schema: {
+        type: 'object',
+        properties: {
+            title: {
+                type: 'string',
+                maxLength: 200
+            },
+            sourceService: {
+                $ref: '#/definitions/SourceService'
+            },
+            sourceID: {
+                $ref: '#/definitions/SourceID'
+            },
+            sourceURL: {
+                $ref: '#/definitions/SourceURL'
+            },
+            lastSyncedAt: {
+                $ref: '#/definitions/DateTime'
+            }
+        },
+        required: [
+            'sourceService',
+            'sourceID',
+            'lastSyncedAt'
+        ],
+        additionalProperties: false,
+        definitions: {
+            ...commonDefinitions
+        }
+    },
+    fieldsMeta: {}
+};
+export const googleMailMessageDefinition = {
+    name: 'GoogleMailMessage',
+    behavior: 'default',
+    interfaces: [
+        connectorModelIDs.ExternalEntity,
+        modelIDs.MessageKind
+    ],
+    schema: {
+        type: 'object',
+        properties: {
+            body: {
+                type: 'string'
+            },
+            sender: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 320
+            },
+            subject: {
+                type: 'string'
+            },
+            snippet: {
+                type: 'string'
+            },
+            to: {
+                type: 'array',
+                title: 'To',
+                items: {
+                    type: 'string'
+                }
+            },
+            cc: {
+                type: 'array',
+                title: 'Cc',
+                items: {
+                    type: 'string'
+                }
+            },
+            labels: {
+                type: 'array',
+                title: 'Labels',
+                items: {
+                    type: 'string'
+                }
+            },
+            sentAt: {
+                $ref: '#/definitions/DateTime'
+            },
+            unread: {
+                type: 'boolean'
+            },
+            attachments: {
+                type: 'array',
+                title: 'Attachments',
+                items: {
+                    $ref: '#/definitions/Attachment'
+                }
+            },
+            threadID: {
+                type: 'string'
+            },
+            thread: {
+                $ref: '#/definitions/ThreadDocID'
+            },
+            sourceService: {
+                $ref: '#/definitions/SourceService'
+            },
+            sourceID: {
+                $ref: '#/definitions/SourceID'
+            },
+            sourceURL: {
+                $ref: '#/definitions/SourceURL'
+            },
+            lastSyncedAt: {
+                $ref: '#/definitions/DateTime'
+            }
+        },
+        required: [
+            'body',
+            'sender',
+            'threadID',
+            'thread',
+            'sourceService',
+            'sourceID',
+            'lastSyncedAt'
+        ],
+        additionalProperties: false,
+        definitions: {
+            ...commonDefinitions,
+            ThreadDocID: docIDSchema,
+            Attachment: {
+                type: 'object',
+                title: 'Attachment',
+                properties: {
+                    filename: {
+                        type: 'string'
+                    },
+                    mimeType: {
+                        type: 'string'
+                    }
+                },
+                required: [
+                    'filename',
+                    'mimeType'
+                ],
+                additionalProperties: false
+            }
+        }
+    },
+    fieldsMeta: {
+        thread: {
+            type: 'document',
+            model: '#0'
+        }
+    }
+};
+export const googleMailLabelDefinition = {
+    name: 'GoogleMailLabel',
+    behavior: 'default',
+    interfaces: [
+        connectorModelIDs.ExternalEntity
+    ],
+    schema: {
+        type: 'object',
+        properties: {
+            name: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 225
+            },
+            type: {
+                type: 'string',
+                maxLength: 20
+            },
+            messageListVisibility: {
+                type: 'string',
+                maxLength: 20
+            },
+            labelListVisibility: {
+                type: 'string',
+                maxLength: 30
+            },
+            textColor: {
+                type: 'string',
+                maxLength: 20
+            },
+            backgroundColor: {
+                type: 'string',
+                maxLength: 20
+            },
+            sourceService: {
+                $ref: '#/definitions/SourceService'
+            },
+            sourceID: {
+                $ref: '#/definitions/SourceID'
+            },
+            sourceURL: {
+                $ref: '#/definitions/SourceURL'
+            },
+            lastSyncedAt: {
+                $ref: '#/definitions/DateTime'
+            }
+        },
+        required: [
+            'name',
+            'sourceService',
+            'sourceID',
+            'lastSyncedAt'
+        ],
+        additionalProperties: false,
+        definitions: {
+            ...commonDefinitions
+        }
+    },
+    fieldsMeta: {}
+};
+const builder = new GraphBuilder({
+    externalClusters: {
+        ...connectorClusters,
+        ...modelsClusters
+    }
+});
+builder.add(googleMailThreadDefinition); // #0
+builder.add(googleMailMessageDefinition); // #1
+builder.add(googleMailLabelDefinition); // #2
+export const googleMailClusters = builder.build();

package/lib/provider.d.ts

@@ -0,0 +1,12 @@
+import type { Credential, ServerDataProvider, SyncBoundary } from '@kubun/connector';
+export declare const DEFAULT_QUERY = "in:inbox";
+export type MailCheckpoint = {
+    historyId: string;
+};
+export type GoogleMailProviderConfig = {
+    credential: Credential;
+    boundary?: SyncBoundary;
+    fetch?: typeof globalThis.fetch;
+    query?: string;
+};
+export declare function createGoogleMailProvider(config: GoogleMailProviderConfig): ServerDataProvider;

package/lib/provider.js

@@ -0,0 +1,190 @@
+import { resolveModelID } from '@kubun/connector';
+import { buildHistoryListURL, buildLabelsListURL, buildMessageGetURL, buildMessagesListURL, buildProfileURL, getHeader, mapLabelToEntity, mapMessageToEntity, mapThreadToEntity, parseGoogleError } from './api.js';
+import { googleMailClusters } from './model.js';
+export const DEFAULT_QUERY = 'in:inbox';
+const THREAD_MODEL_ID = resolveModelID(googleMailClusters, 'GoogleMailThread');
+const MESSAGE_MODEL_ID = resolveModelID(googleMailClusters, 'GoogleMailMessage');
+const LABEL_MODEL_ID = resolveModelID(googleMailClusters, 'GoogleMailLabel');
+async function fetchJSON(url, credential, fetchFn, signal) {
+    const response = await fetchFn(url, {
+        headers: {
+            Authorization: `Bearer ${credential.accessToken}`
+        },
+        signal
+    });
+    if (!response.ok) {
+        throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
+    }
+    return await response.json();
+}
+function applyMaxAge(query, boundary) {
+    if (boundary?.maxAge == null) return query;
+    const match = /^P(\d+)D$/i.exec(boundary.maxAge);
+    if (match == null) return query;
+    if (/\b(newer_than:|after:)/i.test(query)) return query;
+    return `${query} newer_than:${match[1]}d`;
+}
+function maxHistoryId(messages) {
+    let max = -1;
+    for (const m of messages){
+        const n = m.historyId != null ? Number.parseInt(m.historyId, 10) : Number.NaN;
+        if (!Number.isNaN(n) && n > max) max = n;
+    }
+    return max < 0 ? undefined : String(max);
+}
+export function createGoogleMailProvider(config) {
+    const fetchFn = config.fetch ?? globalThis.fetch;
+    async function listMessageIDs(query, signal) {
+        const ids = [];
+        let pageToken;
+        do {
+            const data = await fetchJSON(buildMessagesListURL({
+                query,
+                pageToken
+            }), config.credential, fetchFn, signal);
+            for (const m of data.messages ?? [])ids.push(m);
+            pageToken = data.nextPageToken;
+        }while (pageToken != null)
+        return ids;
+    }
+    async function getMessage(id, signal) {
+        return fetchJSON(buildMessageGetURL({
+            messageID: id
+        }), config.credential, fetchFn, signal);
+    }
+    async function profileHistoryId(signal) {
+        const profile = await fetchJSON(buildProfileURL(), config.credential, fetchFn, signal);
+        return profile.historyId ?? '0';
+    }
+    // Labels have no incremental history API, so every sync re-lists them in full.
+    // The list endpoint is a single cheap call; it omits color (captured only on
+    // create/edit) but carries id, name, type, and the visibility fields.
+    async function labelBatch(signal) {
+        const data = await fetchJSON(buildLabelsListURL(), config.credential, fetchFn, signal);
+        return {
+            modelID: LABEL_MODEL_ID,
+            entities: (data.labels ?? []).map(mapLabelToEntity),
+            hasMore: true
+        };
+    }
+    async function* fetchAllEntities(params) {
+        yield await labelBatch(params.signal);
+        const query = applyMaxAge(config.query ?? DEFAULT_QUERY, params.boundary);
+        const ids = await listMessageIDs(query, params.signal);
+        const messages = [];
+        for (const { id } of ids){
+            messages.push(await getMessage(id, params.signal));
+        }
+        // Thread batch: one thread per distinct threadId, titled by its first message's subject.
+        const threadSubjects = new Map();
+        for (const m of messages){
+            if (!threadSubjects.has(m.threadId)) {
+                threadSubjects.set(m.threadId, getHeader(m.payload?.headers, 'Subject'));
+            }
+        }
+        yield {
+            modelID: THREAD_MODEL_ID,
+            entities: [
+                ...threadSubjects
+            ].map(([threadId, subject])=>mapThreadToEntity(threadId, subject)),
+            hasMore: true
+        };
+        const checkpoint = {
+            historyId: maxHistoryId(messages) ?? await profileHistoryId(params.signal)
+        };
+        yield {
+            modelID: MESSAGE_MODEL_ID,
+            entities: messages.map(mapMessageToEntity),
+            hasMore: false,
+            checkpoint
+        };
+    }
+    async function* fetchChangesEntities(params) {
+        const checkpoint = params.checkpoint;
+        if (checkpoint == null) {
+            yield* fetchAllEntities(params);
+            return;
+        }
+        yield await labelBatch(params.signal);
+        const addedIDs = new Map() // id -> threadId
+        ;
+        const deletedIDs = new Set();
+        let latestHistoryId = checkpoint.historyId;
+        let pageToken;
+        do {
+            const response = await fetchFn(buildHistoryListURL({
+                startHistoryId: checkpoint.historyId,
+                pageToken
+            }), {
+                headers: {
+                    Authorization: `Bearer ${config.credential.accessToken}`
+                },
+                signal: params.signal
+            });
+            if (response.status === 404) {
+                yield* fetchAllEntities(params);
+                return;
+            }
+            if (!response.ok) {
+                throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
+            }
+            const data = await response.json();
+            for (const record of data.history ?? []){
+                for (const ref of [
+                    ...record.messagesAdded ?? [],
+                    ...record.labelsAdded ?? [],
+                    ...record.labelsRemoved ?? []
+                ]){
+                    addedIDs.set(ref.message.id, ref.message.threadId);
+                }
+                for (const ref of record.messagesDeleted ?? []){
+                    deletedIDs.add(ref.message.id);
+                    addedIDs.delete(ref.message.id);
+                }
+            }
+            if (data.historyId != null) latestHistoryId = data.historyId;
+            pageToken = data.nextPageToken;
+        }while (pageToken != null)
+        const survivingIDs = [
+            ...addedIDs.keys()
+        ].filter((id)=>!deletedIDs.has(id));
+        const messages = [];
+        for (const id of survivingIDs){
+            messages.push(await getMessage(id, params.signal));
+        }
+        const threadSubjects = new Map();
+        for (const m of messages){
+            if (!threadSubjects.has(m.threadId)) {
+                threadSubjects.set(m.threadId, getHeader(m.payload?.headers, 'Subject'));
+            }
+        }
+        yield {
+            modelID: THREAD_MODEL_ID,
+            entities: [
+                ...threadSubjects
+            ].map(([threadId, subject])=>mapThreadToEntity(threadId, subject)),
+            hasMore: true
+        };
+        yield {
+            modelID: MESSAGE_MODEL_ID,
+            entities: messages.map(mapMessageToEntity),
+            deleted: [
+                ...deletedIDs
+            ].map((id)=>({
+                    sourceService: 'google-mail',
+                    sourceID: id
+                })),
+            hasMore: false,
+            checkpoint: {
+                historyId: latestHistoryId
+            }
+        };
+    }
+    return {
+        supportedStrategies: [
+            'on-demand'
+        ],
+        fetchAll: fetchAllEntities,
+        fetchChanges: fetchChangesEntities
+    };
+}