@kubun/connector-google-mail 0.17.1 → 0.17.3

package/lib/actions.d.ts

@@ -6,5 +6,6 @@ export type GoogleMailActionHandlerConfig = {
     };
     fetch?: typeof globalThis.fetch;
     writeAttachment?: WriteAttachment;
+    mintFetchHLC: () => string;
 };
 export declare function createGoogleMailActionHandler(config: GoogleMailActionHandlerConfig): ActionHandler;

package/lib/actions.js

@@ -1,44 +1,89 @@
 import { createDraft, createLabel, importMessageAttachment, modifyLabels, sendMessage, updateLabel } from './api.js';
+import { GoogleMailError } from './errors.js';
+// Gmail takes a label color only as the textColor/backgroundColor pair, so a
+// write that changes one of them carries the other from the target document.
+// With no companion to carry (absent or empty), the color cannot be written at all: the write is
+// rejected before any request, rather than sent without the change.
+function withColorPair(params, existing) {
+    const changesOne = 'textColor' in params !== 'backgroundColor' in params;
+    if (!changesOne) return params;
+    const missing = 'textColor' in params ? 'backgroundColor' : 'textColor';
+    const companion = existing?.[missing];
+    if (typeof companion !== 'string' || companion === '') {
+        throw new GoogleMailError(`Google Mail: a label color needs both textColor and backgroundColor, and the label has no ${missing} to keep`, {
+            kind: 'rejected'
+        });
+    }
+    return {
+        ...params,
+        [missing]: companion
+    };
+}
 export function createGoogleMailActionHandler(config) {
+    const mintActionFetchHLC = config.mintFetchHLC;
     return {
         async create (model, params) {
             if (model === 'GoogleMailLabel') {
-                return createLabel({
+                const record = await createLabel({
                     accessToken: config.credential.accessToken,
                     params,
                     fetch: config.fetch
                 });
+                return {
+                    present: true,
+                    record,
+                    sourceFetchHLC: mintActionFetchHLC()
+                };
             }
             if (params.draft === true) {
-                return createDraft({
+                const record = await createDraft({
                     accessToken: config.credential.accessToken,
                     params,
                     fetch: config.fetch
                 });
+                return {
+                    present: true,
+                    record,
+                    sourceFetchHLC: mintActionFetchHLC()
+                };
             }
-            return sendMessage({
+            const record = await sendMessage({
                 accessToken: config.credential.accessToken,
                 params,
                 fetch: config.fetch
             });
+            return {
+                present: true,
+                record,
+                sourceFetchHLC: mintActionFetchHLC()
+            };
         },
         async update (model, sourceID, params, existing) {
             if (model === 'GoogleMailLabel') {
-                return updateLabel({
+                const record = await updateLabel({
                     accessToken: config.credential.accessToken,
                     labelID: sourceID,
-                    params,
+                    params: withColorPair(params, existing),
                     fetch: config.fetch
                 });
+                return {
+                    present: true,
+                    record,
+                    sourceFetchHLC: mintActionFetchHLC()
+                };
             }
             // 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.
+            // blob field. `attachments` is outside GoogleMailMessage's providerMergePolicy
+            // group (model.ts), so this write only ever touches a local-annotation
+            // field — never the provider content group — and says so (`localChange`):
+            // it is projected as an outside-group change, not a fetched SET. 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({
+                const record = await importMessageAttachment({
                     accessToken: config.credential.accessToken,
                     messageID: sourceID,
                     providerRef: params.providerRef,
@@ -46,14 +91,25 @@ export function createGoogleMailActionHandler(config) {
                     writeAttachment: config.writeAttachment,
                     fetch: config.fetch
                 });
+                return {
+                    present: true,
+                    record,
+                    sourceFetchHLC: mintActionFetchHLC(),
+                    localChange: true
+                };
             }
-            return modifyLabels({
+            const record = await modifyLabels({
                 accessToken: config.credential.accessToken,
                 messageID: sourceID,
                 addLabelIds: params.addLabelIds,
                 removeLabelIds: params.removeLabelIds,
                 fetch: config.fetch
             });
+            return {
+                present: true,
+                record,
+                sourceFetchHLC: mintActionFetchHLC()
+            };
         }
     };
 }

package/lib/api.d.ts

@@ -1,6 +1,7 @@
-import type { EntityRecord, WriteAttachment } from '@kubun/connector';
+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;
@@ -11,6 +12,12 @@ export declare function buildMessagesListURL(params: {
 export declare function buildMessageGetURL(params: {
     messageID: string;
 }): string;
+export declare function buildThreadGetURL(params: {
+    threadID: string;
+}): string;
+export declare function buildLabelGetURL(params: {
+    labelID: string;
+}): string;
 export declare function buildAttachmentGetURL(params: {
     messageID: string;
     attachmentID: string;
@@ -85,6 +92,11 @@ export type GmailMessagesListResponse = {
     nextPageToken?: string;
     resultSizeEstimate?: number;
 };
+export type GmailThreadResource = {
+    id: string;
+    historyId?: string;
+    messages?: Array<GmailMessageResource>;
+};
 export declare function getHeader(headers: Array<{
     name: string;
     value: string;
@@ -92,6 +104,24 @@ 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 getMessage(config: {
+    accessToken: string;
+    messageID: string;
+    fetch?: typeof globalThis.fetch;
+    signal?: AbortSignal;
+}): Promise<GmailMessageResource>;
+export declare function getThread(config: {
+    accessToken: string;
+    threadID: string;
+    fetch?: typeof globalThis.fetch;
+    signal?: AbortSignal;
+}): Promise<GmailThreadResource>;
+export declare function getLabel(config: {
+    accessToken: string;
+    labelID: string;
+    fetch?: typeof globalThis.fetch;
+    signal?: AbortSignal;
+}): Promise<GmailLabelResource>;
 export declare function importMessageAttachment(config: {
     accessToken: string;
     messageID: string;

package/lib/api.js

@@ -1,12 +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}`;
-    }
+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);
@@ -28,6 +30,14 @@ export function buildMessageGetURL(params) {
     url.searchParams.set('format', 'full');
     return url.toString();
 }
+export function buildThreadGetURL(params) {
+    const url = new URL(`${MAIL_BASE_URL}/users/me/threads/${encodeURIComponent(params.threadID)}`);
+    url.searchParams.set('format', 'full');
+    return url.toString();
+}
+export function buildLabelGetURL(params) {
+    return `${MAIL_BASE_URL}/users/me/labels/${encodeURIComponent(params.labelID)}`;
+}
 export function buildAttachmentGetURL(params) {
     return `${MAIL_BASE_URL}/users/me/messages/${encodeURIComponent(params.messageID)}/attachments/${encodeURIComponent(params.attachmentID)}`;
 }
@@ -128,6 +138,36 @@ 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:
+// fetchOrAbsent turns it into a `present: false` result instead of a throw.
+export async function getMessage(config) {
+    return mailAPIClient(config.accessToken, config.fetch).get(buildMessageGetURL({
+        messageID: config.messageID
+    }), {
+        signal: config.signal
+    });
+}
+// 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) {
+    return mailAPIClient(config.accessToken, config.fetch).get(buildThreadGetURL({
+        threadID: config.threadID
+    }), {
+        signal: config.signal
+    });
+}
+// 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) {
+    return mailAPIClient(config.accessToken, config.fetch).get(buildLabelGetURL({
+        labelID: config.labelID
+    }), {
+        signal: config.signal
+    });
+}
 function streamOfBytes(bytes) {
     return new ReadableStream({
         start (controller) {
@@ -137,26 +177,22 @@ function streamOfBytes(bytes) {
     });
 }
 // 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.
+// return the message identity with just its `attachments`, that attachment's
+// `blob` set. Other attachments' already-imported blobs are preserved from
+// `existing`, and no other field of `existing` is carried: `attachments` is a
+// local annotation, and the local copy of the provider fields must never be
+// re-issued as if freshly read. 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({
+    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 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), {
@@ -167,7 +203,6 @@ export async function importMessageAttachment(config) {
             blob: attachmentID
         } : a);
     return {
-        ...config.existing ?? {},
         sourceService: 'google-mail',
         sourceID: config.messageID,
         attachments: updated
@@ -228,20 +263,21 @@ function requireString(params, key) {
 // 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());
+// Everything here runs after the write went out, so any failure is marked sent: the
+// write may have landed, whatever the read-back did.
+async function readBackWrittenMessage(config) {
+    try {
+        const messageID = config.messageIDOf(await config.written.json());
+        const message = await mailAPIClient(config.accessToken, config.fetch).get(buildMessageGetURL({
+            messageID
+        }));
+        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,
@@ -249,26 +285,22 @@ 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 new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
-    const sent = await response.json();
-    return fetchAndMapMessage({
+    if (!response.ok) return client.fail(response);
+    return readBackWrittenMessage({
         accessToken: config.accessToken,
-        messageID: sent.id,
+        written: response,
+        messageIDOf: (sent)=>sent.id,
         fetch: config.fetch
     });
 }
 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,
@@ -276,45 +308,37 @@ 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 new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
-    const draft = await response.json();
-    return fetchAndMapMessage({
+    if (!response.ok) return client.fail(response);
+    return readBackWrittenMessage({
         accessToken: config.accessToken,
-        messageID: draft.message.id,
+        written: response,
+        messageIDOf: (draft)=>draft.message.id,
         fetch: config.fetch
     });
 }
 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 new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
-    const modified = await response.json();
-    return fetchAndMapMessage({
+    if (!response.ok) return client.fail(response);
+    return readBackWrittenMessage({
         accessToken: config.accessToken,
-        messageID: modified.id,
+        written: response,
+        messageIDOf: (modified)=>modified.id,
         fetch: config.fetch
     });
 }
@@ -339,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 new Error(`Google Mail API error: ${await parseGoogleError(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 new Error(`Google Mail API error: ${await parseGoogleError(response)}`);
-    return mapLabelToEntity(await response.json());
+    return mapLabelToEntity(label);
 }

package/lib/connector.js

@@ -1,4 +1,5 @@
 import { createGoogleMailActionHandler } from './actions.js';
+import { mergeMailLocalAnnotations } from './local-annotations.js';
 import { googleMailClusters } from './model.js';
 import { createGoogleMailProvider, DEFAULT_QUERY } from './provider.js';
 export function createGoogleMailConnector(options) {
@@ -9,14 +10,19 @@ export function createGoogleMailConnector(options) {
         syncStrategies: [
             'on-demand'
         ],
+        // Two `create`/`update` verbs, each split per entityModel rather than one
+        // action spanning multiple models — schema.ts's dynamic mutation generator
+        // (connectorCreate<Model>/connectorUpdate<Model>) and the write-back
+        // recovery driver (writeback/workflow.ts) both select an action by
+        // (name, entityModel), so each model gets its own recoveryClass.
         actions: [
             {
                 name: 'create',
-                description: 'On GoogleMailMessage: send a message (or create a draft when draft is true). On GoogleMailLabel: create a label.',
+                description: 'Send a message (or create a draft when draft is true).',
+                entityModel: 'GoogleMailMessage',
                 input: {
                     type: 'object',
                     properties: {
-                        // GoogleMailMessage
                         to: {
                             type: 'array',
                             items: {
@@ -43,8 +49,23 @@ export function createGoogleMailConnector(options) {
                         },
                         draft: {
                             type: 'boolean'
-                        },
-                        // GoogleMailLabel
+                        }
+                    }
+                },
+                requiresCredential: true,
+                // Gmail assigns the message id — there is no caller-supplied
+                // deterministic id to key a safe reissue on, and a blind resend after
+                // an outcome-unknown failure could duplicate-send to the recipient.
+                // Recovery must reconcile rather than reissue.
+                recoveryClass: 'reconcile-only'
+            },
+            {
+                name: 'create',
+                description: 'Create a label.',
+                entityModel: 'GoogleMailLabel',
+                input: {
+                    type: 'object',
+                    properties: {
                         name: {
                             type: 'string'
                         },
@@ -62,15 +83,19 @@ export function createGoogleMailConnector(options) {
                         }
                     }
                 },
-                requiresCredential: true
+                requiresCredential: true,
+                // Same reasoning as the google-contacts connector's create: Google
+                // assigns the label id, so a blind retry could create a duplicate
+                // label. Recovery must reconcile rather than reissue.
+                recoveryClass: 'reconcile-only'
             },
             {
                 name: 'update',
-                description: 'On GoogleMailMessage: add/remove labels, or import an attachment when providerRef is set. On GoogleMailLabel: rename or restyle the label.',
+                description: 'Add/remove labels on a message, or import an attachment when providerRef is set.',
+                entityModel: 'GoogleMailMessage',
                 input: {
                     type: 'object',
                     properties: {
-                        // GoogleMailMessage
                         addLabelIds: {
                             type: 'array',
                             items: {
@@ -86,8 +111,23 @@ export function createGoogleMailConnector(options) {
                         // Import the attachment identified by this Gmail part id into the blob store.
                         providerRef: {
                             type: 'string'
-                        },
-                        // GoogleMailLabel
+                        }
+                    }
+                },
+                requiresCredential: true,
+                // Both effects are idempotent under exact-input replay: re-applying the
+                // same add/remove label set is a no-op on the already-applied labels,
+                // and re-downloading + re-writing the same attachment bytes to the
+                // content-addressed blob store is a no-op re-write. Safe to reissue.
+                recoveryClass: 'reissue-safe'
+            },
+            {
+                name: 'update',
+                description: 'Rename or restyle a label.',
+                entityModel: 'GoogleMailLabel',
+                input: {
+                    type: 'object',
+                    properties: {
                         name: {
                             type: 'string'
                         },
@@ -105,14 +145,27 @@ export function createGoogleMailConnector(options) {
                         }
                     }
                 },
-                requiresCredential: true
+                requiresCredential: true,
+                // Same blind-absolute-overwrite reasoning as the google-calendar/
+                // google-contacts connectors' update: a reissue of absolute field
+                // values could silently clobber an intervening edit, so recovery must
+                // reconcile rather than reissue.
+                recoveryClass: 'reconcile-only'
             }
         ],
+        mergeLocalAnnotations: mergeMailLocalAnnotations,
+        // A mail write lands in the account's own mailbox: its target is the
+        // account (`users/me`), already pinned by the operation's account key.
+        resolveActionTarget: async ({ input })=>({
+                target: 'users/me',
+                input
+            }),
         actionHandler: (config)=>{
             return createGoogleMailActionHandler({
                 credential: config.credential,
                 fetch: options?.fetch,
-                writeAttachment: config.writeAttachment
+                writeAttachment: config.writeAttachment,
+                mintFetchHLC: config.mintFetchHLC
             });
         },
         auth: {
@@ -131,7 +184,8 @@ export function createGoogleMailConnector(options) {
                 credential: config.credential,
                 boundary: config.boundary,
                 fetch: options?.fetch,
-                query: options?.query ?? DEFAULT_QUERY
+                query: options?.query ?? DEFAULT_QUERY,
+                mintFetchHLC: config.mintFetchHLC
             });
         }
     };

package/lib/errors.d.ts

@@ -0,0 +1,5 @@
+import { ConnectorError, type ConnectorErrorOptions } from '@kubun/connector';
+/** A Google Mail connector failure, classified the way `ConnectorError` is. */
+export declare class GoogleMailError extends ConnectorError {
+    constructor(message: string, options?: ConnectorErrorOptions);
+}

package/lib/errors.js

@@ -0,0 +1,7 @@
+import { ConnectorError } from '@kubun/connector';
+/** A Google Mail connector failure, classified the way `ConnectorError` is. */ export class GoogleMailError extends ConnectorError {
+    constructor(message, options = {}){
+        super(message, options);
+        this.name = 'GoogleMailError';
+    }
+}

package/lib/index.d.ts

@@ -1,5 +1,7 @@
 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 { buildHistoryListURL, buildLabelGetURL, buildLabelsListURL, buildMessageGetURL, buildMessagesListURL, buildProfileURL, buildRawMessage, buildThreadGetURL, createDraft, createLabel, decodeBase64Url, encodeBase64Url, extractEmail, extractEmails, type GmailHistoryListResponse, type GmailHistoryRecord, type GmailLabelResource, type GmailLabelsListResponse, type GmailMessagePart, type GmailMessageResource, type GmailMessagesListResponse, type GmailThreadResource, getHeader, getLabel, getMessage, getThread, mapLabelToEntity, mapMessageToEntity, mapThreadToEntity, modifyLabels, sendMessage, updateLabel, } from './api.js';
 export { type CreateGoogleMailConnectorOptions, createGoogleMailConnector } from './connector.js';
+export { GoogleMailError } from './errors.js';
+export { mergeMailLocalAnnotations } from './local-annotations.js';
 export { googleMailClusters, googleMailLabelDefinition, googleMailMessageDefinition, googleMailThreadDefinition, } from './model.js';
 export { createGoogleMailProvider, DEFAULT_QUERY, type GoogleMailProviderConfig, type MailCheckpoint, } from './provider.js';

package/lib/index.js

@@ -1,5 +1,7 @@
 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 { buildHistoryListURL, buildLabelGetURL, buildLabelsListURL, buildMessageGetURL, buildMessagesListURL, buildProfileURL, buildRawMessage, buildThreadGetURL, createDraft, createLabel, decodeBase64Url, encodeBase64Url, extractEmail, extractEmails, getHeader, getLabel, getMessage, getThread, mapLabelToEntity, mapMessageToEntity, mapThreadToEntity, modifyLabels, sendMessage, updateLabel } from './api.js';
 export { createGoogleMailConnector } from './connector.js';
+export { GoogleMailError } from './errors.js';
+export { mergeMailLocalAnnotations } from './local-annotations.js';
 export { googleMailClusters, googleMailLabelDefinition, googleMailMessageDefinition, googleMailThreadDefinition } from './model.js';
 export { createGoogleMailProvider, DEFAULT_QUERY } from './provider.js';

package/lib/local-annotations.d.ts

@@ -0,0 +1,8 @@
+import type { LocalAnnotationMerger } from '@kubun/connector';
+/**
+ * The Gmail local-annotation merger (see `LocalAnnotationMerger`). Gmail
+ * authors a message's attachment metadata but never the `blob` an import
+ * adds locally: each incoming attachment without a blob keeps the one its
+ * existing counterpart holds. Nothing else is carried over.
+ */
+export declare const mergeMailLocalAnnotations: LocalAnnotationMerger;

package/lib/local-annotations.js

@@ -0,0 +1,39 @@
+import { googleMailMessageDefinition } from './model.js';
+function sameContent(a, b) {
+    return a.filename === b.filename && a.mimeType === b.mimeType && a.size === b.size;
+}
+// The existing attachment an incoming one is: the one with its attachment id,
+// or — Gmail may re-issue attachment ids — the only one of the message with
+// its filename, type and size when that is unambiguous on both sides. A
+// message's attachments never change, so that pairing is the same content.
+function counterpart(incoming, incomingAll, existingAll) {
+    const byRef = existingAll.find((a)=>a.providerRef === incoming.providerRef);
+    if (byRef != null) return byRef;
+    const matches = existingAll.filter((a)=>sameContent(a, incoming));
+    const twins = incomingAll.filter((a)=>sameContent(a, incoming));
+    return matches.length === 1 && twins.length === 1 ? matches[0] : undefined;
+}
+/**
+ * The Gmail local-annotation merger (see `LocalAnnotationMerger`). Gmail
+ * authors a message's attachment metadata but never the `blob` an import
+ * adds locally: each incoming attachment without a blob keeps the one its
+ * existing counterpart holds. Nothing else is carried over.
+ */ export const mergeMailLocalAnnotations = ({ model, incoming, existing })=>{
+    if (model !== googleMailMessageDefinition.name) return incoming;
+    if (!Array.isArray(incoming.attachments) || !Array.isArray(existing.attachments)) return incoming;
+    const incomingAll = incoming.attachments;
+    const existingAll = existing.attachments;
+    if (!existingAll.some((a)=>typeof a.blob === 'string')) return incoming;
+    const attachments = incomingAll.map((attachment)=>{
+        if (attachment.blob != null) return attachment;
+        const blob = counterpart(attachment, incomingAll, existingAll)?.blob;
+        return typeof blob === 'string' ? {
+            ...attachment,
+            blob
+        } : attachment;
+    });
+    return {
+        ...incoming,
+        attachments
+    };
+};

package/lib/model.d.ts

@@ -46,6 +46,9 @@ export declare const googleMailThreadDefinition: {
         };
     };
     readonly fieldsMeta: {};
+    readonly providerMergePolicy: {
+        readonly group: ["title", "sourceService", "sourceID", "sourceURL"];
+    };
 };
 export declare const googleMailMessageDefinition: {
     readonly name: "GoogleMailMessage";
@@ -179,6 +182,9 @@ export declare const googleMailMessageDefinition: {
             readonly model: "#0";
         };
     };
+    readonly providerMergePolicy: {
+        readonly group: ["body", "sender", "subject", "snippet", "to", "cc", "labels", "sentAt", "unread", "threadID", "thread", "sourceService", "sourceID", "sourceURL"];
+    };
 };
 export declare const googleMailLabelDefinition: {
     readonly name: "GoogleMailLabel";
@@ -249,5 +255,8 @@ export declare const googleMailLabelDefinition: {
         };
     };
     readonly fieldsMeta: {};
+    readonly providerMergePolicy: {
+        readonly group: ["name", "type", "messageListVisibility", "labelListVisibility", "textColor", "backgroundColor", "sourceService", "sourceID", "sourceURL"];
+    };
 };
 export declare const googleMailClusters: import("@kubun/protocol").ClustersRecord;

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,10 +36,20 @@ export const googleMailThreadDefinition = {
         ],
         additionalProperties: false,
         definitions: {
-            ...commonDefinitions
+            ...externalEntityDefinition.schema.definitions
         }
     },
-    fieldsMeta: {}
+    fieldsMeta: {},
+    // lastSyncedAt is a device-local sync-bookkeeping annotation, not fetched
+    // provider content, so it stays outside the group.
+    providerMergePolicy: {
+        group: [
+            'title',
+            'sourceService',
+            'sourceID',
+            'sourceURL'
+        ]
+    }
 };
 export const googleMailMessageDefinition = {
     name: 'GoogleMailMessage',
@@ -145,7 +139,7 @@ export const googleMailMessageDefinition = {
         ],
         additionalProperties: false,
         definitions: {
-            ...commonDefinitions,
+            ...externalEntityDefinition.schema.definitions,
             ThreadDocID: docIDSchema,
             Attachment: {
                 type: 'object',
@@ -185,6 +179,28 @@ export const googleMailMessageDefinition = {
             type: 'document',
             model: '#0'
         }
+    },
+    // lastSyncedAt is device-local sync bookkeeping; attachments carries the
+    // locally-materialized `blob` annotation (absent until an explicit import
+    // fills it), so the whole field stays outside the group rather than
+    // splitting a single top-level field between provider and device content.
+    providerMergePolicy: {
+        group: [
+            'body',
+            'sender',
+            'subject',
+            'snippet',
+            'to',
+            'cc',
+            'labels',
+            'sentAt',
+            'unread',
+            'threadID',
+            'thread',
+            'sourceService',
+            'sourceID',
+            'sourceURL'
+        ]
     }
 };
 export const googleMailLabelDefinition = {
@@ -242,10 +258,25 @@ export const googleMailLabelDefinition = {
         ],
         additionalProperties: false,
         definitions: {
-            ...commonDefinitions
+            ...externalEntityDefinition.schema.definitions
         }
     },
-    fieldsMeta: {}
+    fieldsMeta: {},
+    // lastSyncedAt is a device-local sync-bookkeeping annotation, not fetched
+    // provider content, so it stays outside the group.
+    providerMergePolicy: {
+        group: [
+            'name',
+            'type',
+            'messageListVisibility',
+            'labelListVisibility',
+            'textColor',
+            'backgroundColor',
+            'sourceService',
+            'sourceID',
+            'sourceURL'
+        ]
+    }
 };
 const builder = new GraphBuilder({
     externalClusters: {

package/lib/provider.d.ts

@@ -10,5 +10,6 @@ export type GoogleMailProviderConfig = {
     boundary?: SyncBoundary;
     fetch?: typeof globalThis.fetch;
     query?: string;
+    mintFetchHLC: () => string;
 };
 export declare function createGoogleMailProvider(config: GoogleMailProviderConfig): ServerDataProvider;

package/lib/provider.js

@@ -1,32 +1,18 @@
-import { resolveModelID } from '@kubun/connector';
-import { buildHistoryListURL, buildLabelsListURL, buildMessageGetURL, buildMessagesListURL, buildProfileURL, getHeader, 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,36 +30,55 @@ function maxHistoryId(messages) {
 }
 export function createGoogleMailProvider(config) {
     const fetchFn = config.fetch ?? globalThis.fetch;
+    const client = mailAPIClient(config.credential.accessToken, fetchFn);
+    const mintFetchHLC = config.mintFetchHLC;
     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)
         return ids;
     }
-    async function getMessage(id, signal) {
-        return fetchJSON(buildMessageGetURL({
-            messageID: id
-        }), config.credential, fetchFn, signal);
+    // Bulk-listing message fetch (fetchAll/fetchChanges) — delegates to the
+    // shared api.ts getMessage so both the bulk and targeted (fetchEntity)
+    // paths share one 404-tagging choke point.
+    async function getMessageResource(id, signal) {
+        return getMessage({
+            accessToken: config.credential.accessToken,
+            messageID: id,
+            fetch: fetchFn,
+            signal
+        });
     }
     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,
-            entities: (data.labels ?? []).map(mapLabelToEntity),
+            entities: (data.labels ?? []).map((label)=>({
+                    present: true,
+                    record: mapLabelToEntity(label),
+                    sourceFetchHLC
+                })),
             hasMore: true
         };
     }
@@ -87,7 +92,7 @@ export function createGoogleMailProvider(config) {
         const ids = await listMessageIDs(query, params.signal);
         const messages = [];
         for (const { id } of ids){
-            messages.push(await getMessage(id, params.signal));
+            messages.push(await getMessageResource(id, params.signal));
         }
         // Thread batch: one thread per distinct threadId, titled by its first message's subject.
         const threadSubjects = new Map();
@@ -96,11 +101,16 @@ export function createGoogleMailProvider(config) {
                 threadSubjects.set(m.threadId, getHeader(m.payload?.headers, 'Subject'));
             }
         }
+        const threadToken = mintFetchHLC();
         yield {
             modelID: THREAD_MODEL_ID,
             entities: [
                 ...threadSubjects
-            ].map(([threadId, subject])=>mapThreadToEntity(threadId, subject)),
+            ].map(([threadId, subject])=>({
+                    present: true,
+                    record: mapThreadToEntity(threadId, subject),
+                    sourceFetchHLC: threadToken
+                })),
             hasMore: true
         };
         const checkpoint = {
@@ -109,9 +119,14 @@ export function createGoogleMailProvider(config) {
                 windowStart
             } : {}
         };
+        const messageToken = mintFetchHLC();
         yield {
             modelID: MESSAGE_MODEL_ID,
-            entities: messages.map(mapMessageToEntity),
+            entities: messages.map((message)=>({
+                    present: true,
+                    record: mapMessageToEntity(message),
+                    sourceFetchHLC: messageToken
+                })),
             hasMore: false,
             checkpoint
         };
@@ -129,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 [
@@ -167,7 +178,7 @@ export function createGoogleMailProvider(config) {
         ].filter((id)=>!deletedIDs.has(id));
         const messages = [];
         for (const id of survivingIDs){
-            messages.push(await getMessage(id, params.signal));
+            messages.push(await getMessageResource(id, params.signal));
         }
         const threadSubjects = new Map();
         for (const m of messages){
@@ -175,21 +186,32 @@ export function createGoogleMailProvider(config) {
                 threadSubjects.set(m.threadId, getHeader(m.payload?.headers, 'Subject'));
             }
         }
+        const threadToken = mintFetchHLC();
         yield {
             modelID: THREAD_MODEL_ID,
             entities: [
                 ...threadSubjects
-            ].map(([threadId, subject])=>mapThreadToEntity(threadId, subject)),
+            ].map(([threadId, subject])=>({
+                    present: true,
+                    record: mapThreadToEntity(threadId, subject),
+                    sourceFetchHLC: threadToken
+                })),
             hasMore: true
         };
+        const messageToken = mintFetchHLC();
         yield {
             modelID: MESSAGE_MODEL_ID,
-            entities: messages.map(mapMessageToEntity),
+            entities: messages.map((message)=>({
+                    present: true,
+                    record: mapMessageToEntity(message),
+                    sourceFetchHLC: messageToken
+                })),
             deleted: [
                 ...deletedIDs
             ].map((id)=>({
-                    sourceService: 'google-mail',
-                    sourceID: id
+                    present: false,
+                    sourceID: id,
+                    sourceFetchHLC: messageToken
                 })),
             hasMore: false,
             checkpoint: {
@@ -200,11 +222,65 @@ export function createGoogleMailProvider(config) {
             }
         };
     }
+    // Targeted single-entity fetch (anti-entropy repair verification / write-back
+    // recovery). Mints its own fetch-order token at request start, independent of
+    // any batch token. `model` distinguishes the three GoogleMail* resources —
+    // Thread uses a real threads.get (not the bulk-listing subject synthesis
+    // fetchAll/fetchChanges use); Label uses labels.get (carries color, unlike
+    // the list endpoint labelBatch uses).
+    async function fetchEntity(model, sourceID) {
+        const sourceFetchHLC = mintFetchHLC();
+        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,
+                    messageID: sourceID,
+                    fetch: fetchFn
+                });
+                return {
+                    record: mapMessageToEntity(message)
+                };
+            }
+        });
+    }
+    // Provider-authoritative re-read for write-back recovery. Gmail's
+    // resources carry no dependable ETag on a direct get, so this mirrors
+    // fetchEntity without a providerETag — present for contract parity with the
+    // other connectors' reconcile.
+    async function reconcile(model, sourceID) {
+        return fetchEntity(model, sourceID);
+    }
     return {
         supportedStrategies: [
             'on-demand'
         ],
         fetchAll: fetchAllEntities,
-        fetchChanges: fetchChangesEntities
+        fetchChanges: fetchChangesEntities,
+        fetchEntity,
+        reconcile
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/connector-google-mail",
-  "version": "0.17.1",
+  "version": "0.17.3",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,11 +15,12 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/connector": "^0.17.1",
-    "@kubun/credential-types": "^0.17.0",
+    "@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.0",
-    "@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"
   },