@kubun/connector-google-mail 0.17.2 → 0.17.3

package/lib/api.d.ts

@@ -1,6 +1,7 @@
 import { type EntityRecord, type WriteAttachment } from '@kubun/connector';
+import { type GoogleAPIClient } from '@kubun/provider-google';
 export declare const MAIL_BASE_URL = "https://gmail.googleapis.com/gmail/v1";
-export declare function parseGoogleError(response: Response): Promise<string>;
+export declare function mailAPIClient(accessToken: string, fetch?: typeof globalThis.fetch): GoogleAPIClient;
 export declare function decodeBase64Url(data: string): string;
 export declare function decodeBase64UrlBytes(data: string): Uint8Array;
 export declare function encodeBase64Url(text: string): string;

package/lib/api.js

@@ -1,22 +1,14 @@
 import { connectorHTTPError, markWriteSent } from '@kubun/connector';
+import { createGoogleAPIClient } from '@kubun/provider-google';
 import { b64uFromUTF, b64uToUTF, fromB64U } from '@sozai/codec';
 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}`;
-    }
-}
-// Build the error thrown by a Gmail call, tagged with the HTTP status and its
-// outcome classification (`kind`, see `classifyHTTPStatus`) — a definite
-// rejection dead-letters a write instead of re-driving it. The status is also
-// the seam fetchEntity/reconcile (provider.ts) use to turn a 404 into a
-// `present: false` result (deletion detected) instead of a throw.
-async function googleMailAPIError(response) {
-    const detail = await parseGoogleError(response);
-    return connectorHTTPError(`Google Mail API error: ${detail}`, response.status);
+export function mailAPIClient(accessToken, fetch) {
+    return createGoogleAPIClient({
+        api: 'Google Mail API',
+        accessToken,
+        fetch,
+        toError: ({ httpStatus, message })=>connectorHTTPError(message, httpStatus)
+    });
 }
 export function decodeBase64Url(data) {
     return b64uToUTF(data);
@@ -147,52 +139,34 @@ export function mapMessageToEntity(message) {
     };
 }
 // Targeted single-message fetch (anti-entropy repair verification / write-back
-// recovery's fetchEntity+reconcile). A 404 here is the deletion signal — see
-// googleMailAPIError's doc.
+// recovery's fetchEntity+reconcile). A 404 here is the deletion signal:
+// fetchOrAbsent turns it into a `present: false` result instead of a throw.
 export async function getMessage(config) {
-    const fetchFn = config.fetch ?? globalThis.fetch;
-    const response = await fetchFn(buildMessageGetURL({
+    return mailAPIClient(config.accessToken, config.fetch).get(buildMessageGetURL({
         messageID: config.messageID
     }), {
-        headers: {
-            Authorization: `Bearer ${config.accessToken}`
-        },
         signal: config.signal
     });
-    if (!response.ok) throw await googleMailAPIError(response);
-    return await response.json();
 }
 // Targeted single-thread fetch — a real threads.get(format=full) read, mapped
 // from its own resource (id + constituent messages), never synthesized from a
 // bulk message listing's locally-scanned subject.
 export async function getThread(config) {
-    const fetchFn = config.fetch ?? globalThis.fetch;
-    const response = await fetchFn(buildThreadGetURL({
+    return mailAPIClient(config.accessToken, config.fetch).get(buildThreadGetURL({
         threadID: config.threadID
     }), {
-        headers: {
-            Authorization: `Bearer ${config.accessToken}`
-        },
         signal: config.signal
     });
-    if (!response.ok) throw await googleMailAPIError(response);
-    return await response.json();
 }
 // Targeted single-label fetch. Unlike labels.list (buildLabelsListURL, used by
 // the bulk labelBatch), a direct labels.get returns the full resource
 // including `color` — the list endpoint omits it.
 export async function getLabel(config) {
-    const fetchFn = config.fetch ?? globalThis.fetch;
-    const response = await fetchFn(buildLabelGetURL({
+    return mailAPIClient(config.accessToken, config.fetch).get(buildLabelGetURL({
         labelID: config.labelID
     }), {
-        headers: {
-            Authorization: `Bearer ${config.accessToken}`
-        },
         signal: config.signal
     });
-    if (!response.ok) throw await googleMailAPIError(response);
-    return await response.json();
 }
 function streamOfBytes(bytes) {
     return new ReadableStream({
@@ -215,17 +189,10 @@ export async function importMessageAttachment(config) {
     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({
+    const body = await mailAPIClient(config.accessToken, config.fetch).get(buildAttachmentGetURL({
         messageID: config.messageID,
         attachmentID: config.providerRef
-    }), {
-        headers: {
-            Authorization: `Bearer ${config.accessToken}`
-        }
-    });
-    if (!response.ok) throw await googleMailAPIError(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), {
@@ -301,22 +268,16 @@ function requireString(params, key) {
 async function readBackWrittenMessage(config) {
     try {
         const messageID = config.messageIDOf(await config.written.json());
-        const fetchFn = config.fetch ?? globalThis.fetch;
-        const response = await fetchFn(buildMessageGetURL({
+        const message = await mailAPIClient(config.accessToken, config.fetch).get(buildMessageGetURL({
             messageID
-        }), {
-            headers: {
-                Authorization: `Bearer ${config.accessToken}`
-            }
-        });
-        if (!response.ok) throw await googleMailAPIError(response);
-        return mapMessageToEntity(await response.json());
+        }));
+        return mapMessageToEntity(message);
     } catch (err) {
         throw markWriteSent(err);
     }
 }
 export async function sendMessage(config) {
-    const fetchFn = config.fetch ?? globalThis.fetch;
+    const client = mailAPIClient(config.accessToken, config.fetch);
     const raw = buildRawMessage({
         to: config.params.to,
         cc: config.params.cc,
@@ -324,17 +285,13 @@ export async function sendMessage(config) {
         subject: requireString(config.params, 'subject'),
         body: requireString(config.params, 'body')
     });
-    const response = await fetchFn(`${MAIL_BASE_URL}/users/me/messages/send`, {
+    const response = await client.request(`${MAIL_BASE_URL}/users/me/messages/send`, {
         method: 'POST',
-        headers: {
-            Authorization: `Bearer ${config.accessToken}`,
-            'Content-Type': 'application/json'
-        },
-        body: JSON.stringify({
+        body: {
             raw
-        })
+        }
     });
-    if (!response.ok) throw await googleMailAPIError(response);
+    if (!response.ok) return client.fail(response);
     return readBackWrittenMessage({
         accessToken: config.accessToken,
         written: response,
@@ -343,7 +300,7 @@ export async function sendMessage(config) {
     });
 }
 export async function createDraft(config) {
-    const fetchFn = config.fetch ?? globalThis.fetch;
+    const client = mailAPIClient(config.accessToken, config.fetch);
     const raw = buildRawMessage({
         to: config.params.to,
         cc: config.params.cc,
@@ -351,19 +308,15 @@ export async function createDraft(config) {
         subject: requireString(config.params, 'subject'),
         body: requireString(config.params, 'body')
     });
-    const response = await fetchFn(`${MAIL_BASE_URL}/users/me/drafts`, {
+    const response = await client.request(`${MAIL_BASE_URL}/users/me/drafts`, {
         method: 'POST',
-        headers: {
-            Authorization: `Bearer ${config.accessToken}`,
-            'Content-Type': 'application/json'
-        },
-        body: JSON.stringify({
+        body: {
             message: {
                 raw
             }
-        })
+        }
     });
-    if (!response.ok) throw await googleMailAPIError(response);
+    if (!response.ok) return client.fail(response);
     return readBackWrittenMessage({
         accessToken: config.accessToken,
         written: response,
@@ -372,20 +325,16 @@ export async function createDraft(config) {
     });
 }
 export async function modifyLabels(config) {
-    const fetchFn = config.fetch ?? globalThis.fetch;
+    const client = mailAPIClient(config.accessToken, config.fetch);
     const url = `${MAIL_BASE_URL}/users/me/messages/${encodeURIComponent(config.messageID)}/modify`;
-    const response = await fetchFn(url, {
+    const response = await client.request(url, {
         method: 'POST',
-        headers: {
-            Authorization: `Bearer ${config.accessToken}`,
-            'Content-Type': 'application/json'
-        },
-        body: JSON.stringify({
+        body: {
             addLabelIds: config.addLabelIds ?? [],
             removeLabelIds: config.removeLabelIds ?? []
-        })
+        }
     });
-    if (!response.ok) throw await googleMailAPIError(response);
+    if (!response.ok) return client.fail(response);
     return readBackWrittenMessage({
         accessToken: config.accessToken,
         written: response,
@@ -414,31 +363,19 @@ function buildLabelBody(params) {
     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(), {
+    const label = await mailAPIClient(config.accessToken, config.fetch).send(buildLabelsListURL(), {
         method: 'POST',
-        headers: {
-            Authorization: `Bearer ${config.accessToken}`,
-            'Content-Type': 'application/json'
-        },
-        body: JSON.stringify(body)
+        body
     });
-    if (!response.ok) throw await googleMailAPIError(response);
-    return mapLabelToEntity(await response.json());
+    return mapLabelToEntity(label);
 }
 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, {
+    const label = await mailAPIClient(config.accessToken, config.fetch).send(url, {
         method: 'PATCH',
-        headers: {
-            Authorization: `Bearer ${config.accessToken}`,
-            'Content-Type': 'application/json'
-        },
-        body: JSON.stringify(buildLabelBody(config.params))
+        body: buildLabelBody(config.params)
     });
-    if (!response.ok) throw await googleMailAPIError(response);
-    return mapLabelToEntity(await response.json());
+    return mapLabelToEntity(label);
 }

package/lib/model.js

@@ -1,23 +1,7 @@
-import { connectorClusters, connectorModelIDs } from '@kubun/connector';
+import { connectorClusters, connectorModelIDs, externalEntityDefinition } 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
-};
+import { docIDSchema } from '@kubun/scalars';
 export const googleMailThreadDefinition = {
     name: 'GoogleMailThread',
     behavior: 'default',
@@ -52,7 +36,7 @@ export const googleMailThreadDefinition = {
         ],
         additionalProperties: false,
         definitions: {
-            ...commonDefinitions
+            ...externalEntityDefinition.schema.definitions
         }
     },
     fieldsMeta: {},
@@ -155,7 +139,7 @@ export const googleMailMessageDefinition = {
         ],
         additionalProperties: false,
         definitions: {
-            ...commonDefinitions,
+            ...externalEntityDefinition.schema.definitions,
             ThreadDocID: docIDSchema,
             Attachment: {
                 type: 'object',
@@ -274,7 +258,7 @@ export const googleMailLabelDefinition = {
         ],
         additionalProperties: false,
         definitions: {
-            ...commonDefinitions
+            ...externalEntityDefinition.schema.definitions
         }
     },
     fieldsMeta: {},

package/lib/provider.js

@@ -1,32 +1,18 @@
-import { resolveModelID } from '@kubun/connector';
-import { buildHistoryListURL, buildLabelsListURL, buildMessagesListURL, buildProfileURL, getHeader, getLabel, getMessage, getThread, mapLabelToEntity, mapMessageToEntity, mapThreadToEntity, parseGoogleError } from './api.js';
+import { fetchOrAbsent, parseMaxAgeDays, resolveModelID } from '@kubun/connector';
+import { buildHistoryListURL, buildLabelsListURL, buildMessagesListURL, buildProfileURL, getHeader, getLabel, getMessage, getThread, mailAPIClient, mapLabelToEntity, mapMessageToEntity, mapThreadToEntity } 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();
-}
 /**
  * The absolute lower bound (epoch seconds) for a full message listing: a window
  * already frozen in the checkpoint, else `now − maxAge` computed once. Null when
  * the boundary carries no `maxAge` (no floor).
  */ function windowStartSeconds(boundary, frozen) {
     if (frozen != null) return frozen;
-    if (boundary?.maxAge == null) return null;
-    const match = /^P(\d+)D$/i.exec(boundary.maxAge);
-    if (match?.[1] == null) return null;
-    const days = Number.parseInt(match[1], 10);
+    const days = parseMaxAgeDays(boundary);
+    if (days == null) return null;
     return Math.floor((Date.now() - days * 86_400_000) / 1000);
 }
 /** Appends an absolute `after:<epoch seconds>` floor to a Gmail search query. */ function applyAfter(query, windowStart) {
@@ -44,21 +30,18 @@ function maxHistoryId(messages) {
 }
 export function createGoogleMailProvider(config) {
     const fetchFn = config.fetch ?? globalThis.fetch;
+    const client = mailAPIClient(config.credential.accessToken, fetchFn);
     const mintFetchHLC = config.mintFetchHLC;
-    // getMessage/getThread/getLabel (api.ts) throw a plain Error tagged with
-    // `.httpStatus` — this is the seam fetchEntity/reconcile use to turn a 404
-    // into a `present: false` result instead of a throw.
-    function isNotFound(err) {
-        return err?.httpStatus === 404;
-    }
     async function listMessageIDs(query, signal) {
         const ids = [];
         let pageToken;
         do {
-            const data = await fetchJSON(buildMessagesListURL({
+            const data = await client.get(buildMessagesListURL({
                 query,
                 pageToken
-            }), config.credential, fetchFn, signal);
+            }), {
+                signal
+            });
             for (const m of data.messages ?? [])ids.push(m);
             pageToken = data.nextPageToken;
         }while (pageToken != null)
@@ -76,14 +59,18 @@ export function createGoogleMailProvider(config) {
         });
     }
     async function profileHistoryId(signal) {
-        const profile = await fetchJSON(buildProfileURL(), config.credential, fetchFn, signal);
+        const profile = await client.get(buildProfileURL(), {
+            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);
+        const data = await client.get(buildLabelsListURL(), {
+            signal
+        });
         const sourceFetchHLC = mintFetchHLC();
         return {
             modelID: LABEL_MODEL_ID,
@@ -157,22 +144,18 @@ export function createGoogleMailProvider(config) {
         let latestHistoryId = checkpoint.historyId;
         let pageToken;
         do {
-            const response = await fetchFn(buildHistoryListURL({
+            const response = await client.request(buildHistoryListURL({
                 startHistoryId: checkpoint.historyId,
                 pageToken
             }), {
-                headers: {
-                    Authorization: `Bearer ${config.credential.accessToken}`
-                },
+                method: 'GET',
                 signal: params.signal
             });
             if (response.status === 404) {
                 yield* fetchAllEntities(params);
                 return;
             }
-            if (!response.ok) {
-                throw new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
-            }
+            if (!response.ok) await client.fail(response);
             const data = await response.json();
             for (const record of data.history ?? []){
                 for (const ref of [
@@ -247,53 +230,42 @@ export function createGoogleMailProvider(config) {
     // the list endpoint labelBatch uses).
     async function fetchEntity(model, sourceID) {
         const sourceFetchHLC = mintFetchHLC();
-        try {
-            if (model === THREAD_MODEL_ID) {
-                const thread = await getThread({
-                    accessToken: config.credential.accessToken,
-                    threadID: sourceID,
-                    fetch: fetchFn
-                });
-                const first = thread.messages?.[0];
-                const subject = first != null ? getHeader(first.payload?.headers, 'Subject') : undefined;
-                return {
-                    present: true,
-                    record: mapThreadToEntity(thread.id, subject),
-                    sourceFetchHLC
-                };
-            }
-            if (model === LABEL_MODEL_ID) {
-                const label = await getLabel({
+        return fetchOrAbsent({
+            sourceID,
+            sourceFetchHLC,
+            read: async ()=>{
+                if (model === THREAD_MODEL_ID) {
+                    const thread = await getThread({
+                        accessToken: config.credential.accessToken,
+                        threadID: sourceID,
+                        fetch: fetchFn
+                    });
+                    const first = thread.messages?.[0];
+                    const subject = first != null ? getHeader(first.payload?.headers, 'Subject') : undefined;
+                    return {
+                        record: mapThreadToEntity(thread.id, subject)
+                    };
+                }
+                if (model === LABEL_MODEL_ID) {
+                    const label = await getLabel({
+                        accessToken: config.credential.accessToken,
+                        labelID: sourceID,
+                        fetch: fetchFn
+                    });
+                    return {
+                        record: mapLabelToEntity(label)
+                    };
+                }
+                const message = await getMessage({
                     accessToken: config.credential.accessToken,
-                    labelID: sourceID,
+                    messageID: sourceID,
                     fetch: fetchFn
                 });
                 return {
-                    present: true,
-                    record: mapLabelToEntity(label),
-                    sourceFetchHLC
+                    record: mapMessageToEntity(message)
                 };
             }
-            const message = await getMessage({
-                accessToken: config.credential.accessToken,
-                messageID: sourceID,
-                fetch: fetchFn
-            });
-            return {
-                present: true,
-                record: mapMessageToEntity(message),
-                sourceFetchHLC
-            };
-        } catch (err) {
-            if (isNotFound(err)) {
-                return {
-                    present: false,
-                    sourceID,
-                    sourceFetchHLC
-                };
-            }
-            throw err;
-        }
+        });
     }
     // Provider-authoritative re-read for write-back recovery. Gmail's
     // resources carry no dependable ETag on a direct get, so this mirrors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/connector-google-mail",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,12 +15,12 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/connector": "^0.17.2",
+    "@kubun/connector": "^0.17.3",
     "@kubun/credential-types": "^0.17.2",
     "@kubun/hlc": "^0.17.0",
     "@kubun/models": "^0.17.0",
-    "@kubun/protocol": "^0.17.1",
-    "@kubun/provider-google": "^0.17.0",
+    "@kubun/protocol": "^0.17.2",
+    "@kubun/provider-google": "^0.17.1",
     "@kubun/scalars": "^0.17.0",
     "@sozai/codec": "^0.4.0"
   },