@kubun/connector-google-mail 0.12.0 → 0.13.0

package/lib/actions.d.ts

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

package/lib/actions.js

@@ -1,4 +1,4 @@
-import { createDraft, createLabel, modifyLabels, sendMessage, updateLabel } from './api.js';
+import { createDraft, createLabel, importMessageAttachment, modifyLabels, sendMessage, updateLabel } from './api.js';
 export function createGoogleMailActionHandler(config) {
     return {
         async create (model, params) {
@@ -22,7 +22,7 @@ export function createGoogleMailActionHandler(config) {
                 fetch: config.fetch
             });
         },
-        async update (model, sourceID, params) {
+        async update (model, sourceID, params, existing) {
             if (model === 'GoogleMailLabel') {
                 return updateLabel({
                     accessToken: config.credential.accessToken,
@@ -31,6 +31,22 @@ export function createGoogleMailActionHandler(config) {
                     fetch: config.fetch
                 });
             }
+            // On GoogleMailMessage, a providerRef selects an attachment to import: its
+            // bytes are downloaded and written to the blob store, filling that entry's
+            // blob field. Without it, the update modifies labels as before.
+            if (typeof params.providerRef === 'string') {
+                if (config.writeAttachment == null) {
+                    throw new Error('Google Mail: cannot import attachment, no blob plugin installed');
+                }
+                return importMessageAttachment({
+                    accessToken: config.credential.accessToken,
+                    messageID: sourceID,
+                    providerRef: params.providerRef,
+                    existing,
+                    writeAttachment: config.writeAttachment,
+                    fetch: config.fetch
+                });
+            }
             return modifyLabels({
                 accessToken: config.credential.accessToken,
                 messageID: sourceID,

package/lib/api.d.ts

@@ -1,7 +1,8 @@
-import type { EntityRecord } from '@kubun/connector';
+import type { EntityRecord, WriteAttachment } 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 decodeBase64UrlBytes(data: string): Uint8Array;
 export declare function encodeBase64Url(text: string): string;
 export declare function buildMessagesListURL(params: {
     query: string;
@@ -10,6 +11,10 @@ export declare function buildMessagesListURL(params: {
 export declare function buildMessageGetURL(params: {
     messageID: string;
 }): string;
+export declare function buildAttachmentGetURL(params: {
+    messageID: string;
+    attachmentID: string;
+}): string;
 export declare function buildHistoryListURL(params: {
     startHistoryId: string;
     pageToken?: string;
@@ -87,6 +92,14 @@ export declare function getHeader(headers: Array<{
 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 importMessageAttachment(config: {
+    accessToken: string;
+    messageID: string;
+    providerRef: string;
+    existing: Record<string, unknown> | undefined;
+    writeAttachment: WriteAttachment;
+    fetch?: typeof globalThis.fetch;
+}): Promise<EntityRecord>;
 export declare function mapThreadToEntity(threadID: string, subject: string | undefined): EntityRecord;
 export declare function buildRawMessage(params: {
     to: string | Array<string>;

package/lib/api.js

@@ -1,3 +1,4 @@
+import { b64uFromUTF, b64uToUTF, fromB64U } from '@sozai/codec';
 export const MAIL_BASE_URL = 'https://gmail.googleapis.com/gmail/v1';
 export async function parseGoogleError(response) {
     try {
@@ -8,10 +9,13 @@ export async function parseGoogleError(response) {
     }
 }
 export function decodeBase64Url(data) {
-    return Buffer.from(data, 'base64url').toString('utf8');
+    return b64uToUTF(data);
+}
+export function decodeBase64UrlBytes(data) {
+    return fromB64U(data);
 }
 export function encodeBase64Url(text) {
-    return Buffer.from(text, 'utf8').toString('base64url');
+    return b64uFromUTF(text);
 }
 export function buildMessagesListURL(params) {
     const url = new URL(`${MAIL_BASE_URL}/users/me/messages`);
@@ -24,6 +28,9 @@ export function buildMessageGetURL(params) {
     url.searchParams.set('format', 'full');
     return url.toString();
 }
+export function buildAttachmentGetURL(params) {
+    return `${MAIL_BASE_URL}/users/me/messages/${encodeURIComponent(params.messageID)}/attachments/${encodeURIComponent(params.attachmentID)}`;
+}
 export function buildHistoryListURL(params) {
     const url = new URL(`${MAIL_BASE_URL}/users/me/history`);
     url.searchParams.set('startHistoryId', params.startHistoryId);
@@ -82,9 +89,13 @@ function extractAttachments(payload) {
     const out = [];
     function walk(part) {
         if (part.filename != null && part.filename !== '' && part.body?.attachmentId != null) {
+            // providerRef is the Gmail part id used later to fetch bytes on demand
+            // (users.messages.attachments.get); the blob field stays absent until import.
             out.push({
                 filename: part.filename,
-                mimeType: part.mimeType ?? 'application/octet-stream'
+                mimeType: part.mimeType ?? 'application/octet-stream',
+                providerRef: part.body.attachmentId,
+                size: part.body.size ?? 0
             });
         }
         for (const child of part.parts ?? [])walk(child);
@@ -117,6 +128,51 @@ export function mapMessageToEntity(message) {
         }
     };
 }
+function streamOfBytes(bytes) {
+    return new ReadableStream({
+        start (controller) {
+            controller.enqueue(bytes);
+            controller.close();
+        }
+    });
+}
+// Download one attachment's bytes from Gmail, write them to the blob store, and
+// return the message entity with that attachment's `blob` set. Other attachments'
+// already-imported blobs are preserved from `existing`. Gmail returns the whole
+// attachment as a single base64url `data` field, so the bytes are buffered here.
+export async function importMessageAttachment(config) {
+    const attachments = config.existing?.attachments ?? [];
+    const target = attachments.find((a)=>a.providerRef === config.providerRef);
+    if (target == null) {
+        throw new Error(`Google Mail: no attachment with providerRef "${config.providerRef}"`);
+    }
+    const fetchFn = config.fetch ?? globalThis.fetch;
+    const response = await fetchFn(buildAttachmentGetURL({
+        messageID: config.messageID,
+        attachmentID: config.providerRef
+    }), {
+        headers: {
+            Authorization: `Bearer ${config.accessToken}`
+        }
+    });
+    if (!response.ok) throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
+    const body = await response.json();
+    if (body.data == null) throw new Error('Google Mail: attachment response has no data');
+    const bytes = decodeBase64UrlBytes(body.data);
+    const attachmentID = await config.writeAttachment(streamOfBytes(bytes), {
+        mimeType: target.mimeType ?? 'application/octet-stream'
+    });
+    const updated = attachments.map((a)=>a.providerRef === config.providerRef ? {
+            ...a,
+            blob: attachmentID
+        } : a);
+    return {
+        ...config.existing ?? {},
+        sourceService: 'google-mail',
+        sourceID: config.messageID,
+        attachments: updated
+    };
+}
 export function mapThreadToEntity(threadID, subject) {
     return {
         sourceService: 'google-mail',

package/lib/connector.js

@@ -66,7 +66,7 @@ export function createGoogleMailConnector(options) {
             },
             {
                 name: 'update',
-                description: 'On GoogleMailMessage: add/remove labels. On GoogleMailLabel: rename or restyle the label.',
+                description: 'On GoogleMailMessage: add/remove labels, or import an attachment when providerRef is set. On GoogleMailLabel: rename or restyle the label.',
                 input: {
                     type: 'object',
                     properties: {
@@ -83,6 +83,10 @@ export function createGoogleMailConnector(options) {
                                 type: 'string'
                             }
                         },
+                        // Import the attachment identified by this Gmail part id into the blob store.
+                        providerRef: {
+                            type: 'string'
+                        },
                         // GoogleMailLabel
                         name: {
                             type: 'string'
@@ -107,7 +111,8 @@ export function createGoogleMailConnector(options) {
         actionHandler: (config)=>{
             return createGoogleMailActionHandler({
                 credential: config.credential,
-                fetch: options?.fetch
+                fetch: options?.fetch,
+                writeAttachment: config.writeAttachment
             });
         },
         auth: {

package/lib/model.d.ts

@@ -37,7 +37,11 @@ export declare const googleMailThreadDefinition: {
                 readonly minLength: 1;
                 readonly maxLength: 500;
             };
-            readonly SourceURL: import("json-schema-typed").JSONSchema.String;
+            readonly SourceURL: {
+                readonly type: "string";
+                readonly format: "uri";
+                readonly title: "URL";
+            };
             readonly DateTime: import("json-schema-typed").JSONSchema.String;
         };
     };
@@ -120,7 +124,11 @@ export declare const googleMailMessageDefinition: {
         readonly required: ["body", "sender", "threadID", "thread", "sourceService", "sourceID", "lastSyncedAt"];
         readonly additionalProperties: false;
         readonly definitions: {
-            readonly ThreadDocID: import("json-schema-typed").JSONSchema.String;
+            readonly ThreadDocID: {
+                readonly type: "string";
+                readonly title: "DocID";
+                readonly pattern: "^k[0-9a-z]{10,120}$";
+            };
             readonly Attachment: {
                 readonly type: "object";
                 readonly title: "Attachment";
@@ -131,8 +139,18 @@ export declare const googleMailMessageDefinition: {
                     readonly mimeType: {
                         readonly type: "string";
                     };
+                    readonly providerRef: {
+                        readonly type: "string";
+                    };
+                    readonly size: {
+                        readonly type: "number";
+                    };
+                    readonly blob: {
+                        readonly type: "string";
+                        readonly title: "attachmentid";
+                    };
                 };
-                readonly required: ["filename", "mimeType"];
+                readonly required: ["filename", "mimeType", "providerRef", "size"];
                 readonly additionalProperties: false;
             };
             readonly SourceService: {
@@ -147,7 +165,11 @@ export declare const googleMailMessageDefinition: {
                 readonly minLength: 1;
                 readonly maxLength: 500;
             };
-            readonly SourceURL: import("json-schema-typed").JSONSchema.String;
+            readonly SourceURL: {
+                readonly type: "string";
+                readonly format: "uri";
+                readonly title: "URL";
+            };
             readonly DateTime: import("json-schema-typed").JSONSchema.String;
         };
     };
@@ -218,7 +240,11 @@ export declare const googleMailLabelDefinition: {
                 readonly minLength: 1;
                 readonly maxLength: 500;
             };
-            readonly SourceURL: import("json-schema-typed").JSONSchema.String;
+            readonly SourceURL: {
+                readonly type: "string";
+                readonly format: "uri";
+                readonly title: "URL";
+            };
             readonly DateTime: import("json-schema-typed").JSONSchema.String;
         };
     };

package/lib/model.js

@@ -156,11 +156,25 @@ export const googleMailMessageDefinition = {
                     },
                     mimeType: {
                         type: 'string'
+                    },
+                    // Gmail part id; the stable selector an import action uses to fetch bytes.
+                    providerRef: {
+                        type: 'string'
+                    },
+                    size: {
+                        type: 'number'
+                    },
+                    // Content-addressed blob id, absent until an explicit import fills it.
+                    blob: {
+                        type: 'string',
+                        title: 'attachmentid'
                     }
                 },
                 required: [
                     'filename',
-                    'mimeType'
+                    'mimeType',
+                    'providerRef',
+                    'size'
                 ],
                 additionalProperties: false
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/connector-google-mail",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,11 +15,12 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/connector": "^0.12.1",
-    "@kubun/models": "^0.12.1",
-    "@kubun/provider-google": "^0.12.0",
+    "@sozai/codec": "^0.4.0",
+    "@kubun/connector": "^0.13.0",
+    "@kubun/models": "^0.13.0",
     "@kubun/protocol": "^0.13.0",
-    "@kubun/scalars": "^0.12.0"
+    "@kubun/scalars": "^0.13.0",
+    "@kubun/provider-google": "^0.13.0"
   },
   "publishConfig": {
     "access": "public"