@kubun/connector-google-contacts 0.17.0 → 0.17.2

package/lib/actions.d.ts

@@ -5,5 +5,6 @@ export type GoogleContactsActionHandlerConfig = {
         scopes: Array<string>;
     };
     fetch?: typeof globalThis.fetch;
+    mintFetchHLC: () => string;
 };
 export declare function createGoogleContactsActionHandler(config: GoogleContactsActionHandlerConfig): ActionHandler;

package/lib/actions.js

@@ -1,20 +1,46 @@
 import { createContact, updateContact } from './api.js';
+// The People API writes a contact's organization name and job title as one
+// `organizations` entry, so a write that changes only one of them carries the
+// other from the target document — sending one alone would clear the other.
+function withOrganizationPair(params, existing) {
+    const changesOne = 'organization' in params !== 'jobTitle' in params;
+    if (!changesOne || existing == null) return params;
+    return 'organization' in params ? {
+        ...params,
+        jobTitle: existing.jobTitle
+    } : {
+        ...params,
+        organization: existing.organization
+    };
+}
 export function createGoogleContactsActionHandler(config) {
+    const mintActionFetchHLC = config.mintFetchHLC;
     return {
         async create (_model, params) {
-            return createContact({
+            const record = await createContact({
                 accessToken: config.credential.accessToken,
                 params,
                 fetch: config.fetch
             });
+            return {
+                present: true,
+                record,
+                sourceFetchHLC: mintActionFetchHLC()
+            };
         },
-        async update (_model, sourceID, params) {
-            return updateContact({
+        async update (_model, sourceID, params, existing, context) {
+            const record = await updateContact({
                 accessToken: config.credential.accessToken,
                 sourceID,
-                params,
+                params: withOrganizationPair(params, existing),
+                etag: context?.providerETag,
                 fetch: config.fetch
             });
+            return {
+                present: true,
+                record,
+                sourceFetchHLC: mintActionFetchHLC()
+            };
         }
     };
 }

package/lib/api.d.ts

@@ -1,4 +1,5 @@
-import type { EntityRecord } from '@kubun/connector';
+import { type EntityRecord } from '@kubun/connector';
+import { type GoogleAPIClient } from '@kubun/provider-google';
 export type GooglePersonResource = {
     resourceName: string;
     etag?: string;
@@ -20,7 +21,11 @@ export type GooglePersonResource = {
     photos?: Array<{
         url?: string;
     }>;
+    metadata?: {
+        deleted?: boolean;
+    };
 };
+export declare function peopleAPIClient(accessToken: string, fetch?: typeof globalThis.fetch): GoogleAPIClient;
 export type GoogleConnectionsResponse = {
     connections?: Array<GooglePersonResource>;
     nextPageToken?: string;
@@ -34,6 +39,19 @@ export declare function buildListURL(params: {
 }): string;
 export declare function mapPersonToEntity(person: GooglePersonResource): EntityRecord;
 export declare function buildPersonFromParams(params: Record<string, unknown>): Partial<GooglePersonResource>;
+export declare function getPerson(config: {
+    accessToken: string;
+    sourceID: string;
+    fetch?: typeof globalThis.fetch;
+}): Promise<EntityRecord>;
+export declare function getPersonWithETag(config: {
+    accessToken: string;
+    sourceID: string;
+    fetch?: typeof globalThis.fetch;
+}): Promise<{
+    record: EntityRecord;
+    etag?: string;
+}>;
 export type CreateContactParams = {
     accessToken: string;
     params: Record<string, unknown>;
@@ -44,6 +62,13 @@ export type UpdateContactParams = {
     accessToken: string;
     sourceID: string;
     params: Record<string, unknown>;
+    /**
+     * The contact's etag as last fetched. The People API writes a contact only
+     * against its etag and refuses (FAILED_PRECONDITION) a stale one, so a
+     * contact changed at Google since is never overwritten. It is never re-read
+     * right before the write — that would always match and guard nothing.
+     */
+    etag?: string | null;
     fetch?: typeof globalThis.fetch;
 };
 export declare function updateContact(options: UpdateContactParams): Promise<EntityRecord>;

package/lib/api.js

@@ -1,3 +1,6 @@
+import { classifyHTTPStatus, connectorHTTPError } from '@kubun/connector';
+import { createGoogleAPIClient } from '@kubun/provider-google';
+import { ContactEtagRequired, GoogleContactsError } from './errors.js';
 const PERSON_FIELDS = 'names,emailAddresses,phoneNumbers,organizations,photos';
 const CONTACTS_BASE_URL = 'https://people.googleapis.com/v1';
 // A Google People API resource name is `people/{id}`. A sourceID reaches here
@@ -10,13 +13,23 @@ function assertValidSourceID(sourceID) {
         throw new Error(`Invalid contact sourceID: ${JSON.stringify(sourceID)}`);
     }
 }
-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 peopleAPIClient(accessToken, fetch) {
+    return createGoogleAPIClient({
+        api: 'Google People API',
+        accessToken,
+        fetch,
+        toError: ({ httpStatus, message })=>connectorHTTPError(message, httpStatus)
+    });
+}
+// A write answered with FAILED_PRECONDITION (a 400) was refused because the
+// contact changed at Google since the etag it was conditioned on — the People
+// API's form of a 412. Like a 412 it is outcome-unknown, never a rejection:
+// recovery reconciles against the contact's current state.
+function googlePeopleWriteError(failure) {
+    return new GoogleContactsError(failure.message, {
+        httpStatus: failure.httpStatus,
+        kind: failure.googleStatus === 'FAILED_PRECONDITION' ? 'unknown' : classifyHTTPStatus(failure.httpStatus)
+    });
 }
 export function buildListURL(params) {
     const url = new URL(`${CONTACTS_BASE_URL}/people/me/connections`);
@@ -43,7 +56,8 @@ export function mapPersonToEntity(person) {
         organization: person.organizations?.[0]?.name ?? undefined,
         jobTitle: person.organizations?.[0]?.title ?? undefined,
         photoURL: person.photos?.[0]?.url ?? undefined,
-        sourceURL: `https://contacts.google.com/person/${person.resourceName.replace('people/', '')}`
+        sourceURL: `https://contacts.google.com/person/${person.resourceName.replace('people/', '')}`,
+        etag: person.etag
     };
 }
 export function buildPersonFromParams(params) {
@@ -83,59 +97,67 @@ export function buildPersonFromParams(params) {
     }
     return person;
 }
+// Raw people.get, shared by getPerson/getPersonWithETag (fetchEntity/
+// reconcile's targeted read) — a single choke point for sourceID validation
+// and 404 classification.
+async function fetchPersonResource(config) {
+    assertValidSourceID(config.sourceID);
+    const url = `${CONTACTS_BASE_URL}/${config.sourceID}?personFields=${PERSON_FIELDS}`;
+    return peopleAPIClient(config.accessToken, config.fetch).get(url);
+}
+// Targeted single-contact fetch (anti-entropy repair verification / write-back
+// recovery's fetchEntity). A 404 here is the deletion signal: fetchOrAbsent
+// turns it into a `present: false` result instead of a throw.
+export async function getPerson(config) {
+    const data = await fetchPersonResource(config);
+    return mapPersonToEntity(data);
+}
+// Same as getPerson, but also surfaces the provider's etag — used by
+// write-back recovery's reconcile read, which reports a providerETag
+// alongside the record.
+export async function getPersonWithETag(config) {
+    const data = await fetchPersonResource(config);
+    return {
+        record: mapPersonToEntity(data),
+        etag: data.etag
+    };
+}
 export async function createContact(options) {
-    const fetchFn = options.fetch ?? globalThis.fetch;
     const person = buildPersonFromParams(options.params);
-    const response = await fetchFn(`${CONTACTS_BASE_URL}/people:createContact?personFields=${PERSON_FIELDS}`, {
+    const created = await peopleAPIClient(options.accessToken, options.fetch).send(`${CONTACTS_BASE_URL}/people:createContact?personFields=${PERSON_FIELDS}`, {
         method: 'POST',
-        headers: {
-            Authorization: `Bearer ${options.accessToken}`,
-            'Content-Type': 'application/json'
-        },
-        body: JSON.stringify(person)
+        body: person
     });
-    if (!response.ok) {
-        const errorMessage = await parseGoogleError(response);
-        throw new Error(`Google People API error: ${errorMessage}`);
-    }
-    const created = await response.json();
     return mapPersonToEntity(created);
 }
+function contactEtagRequired() {
+    return new ContactEtagRequired();
+}
 export async function updateContact(options) {
     assertValidSourceID(options.sourceID);
-    const fetchFn = options.fetch ?? globalThis.fetch;
-    // Fetch current person to get etag (required by Google People API for updates)
-    const getURL = `${CONTACTS_BASE_URL}/${options.sourceID}?personFields=${PERSON_FIELDS}`;
-    const getResponse = await fetchFn(getURL, {
-        headers: {
-            Authorization: `Bearer ${options.accessToken}`
-        }
-    });
-    if (!getResponse.ok) {
-        const errorMessage = await parseGoogleError(getResponse);
-        throw new Error(`Google People API error: ${errorMessage}`);
-    }
-    const current = await getResponse.json();
+    // The People API requires an etag on every update. Without the stored one
+    // the only way to get one is a fresh read, which would overwrite a change
+    // made at Google since the edit: refuse before any request instead.
+    if (options.etag == null || options.etag === '') throw contactEtagRequired();
     const person = buildPersonFromParams(options.params);
-    person.etag = current.etag;
+    person.etag = options.etag;
     const updatePersonFields = [];
     if (person.names != null) updatePersonFields.push('names');
     if (person.emailAddresses != null) updatePersonFields.push('emailAddresses');
     if (person.phoneNumbers != null) updatePersonFields.push('phoneNumbers');
     if (person.organizations != null) updatePersonFields.push('organizations');
     const url = `${CONTACTS_BASE_URL}/${options.sourceID}:updateContact?updatePersonFields=${updatePersonFields.join(',')}&personFields=${PERSON_FIELDS}`;
-    const response = await fetchFn(url, {
+    const client = createGoogleAPIClient({
+        api: 'Google People API',
+        accessToken: options.accessToken,
+        fetch: options.fetch,
+        toError: googlePeopleWriteError
+    });
+    const response = await client.request(url, {
         method: 'PATCH',
-        headers: {
-            Authorization: `Bearer ${options.accessToken}`,
-            'Content-Type': 'application/json'
-        },
-        body: JSON.stringify(person)
+        body: person
     });
-    if (!response.ok) {
-        const errorMessage = await parseGoogleError(response);
-        throw new Error(`Google People API error: ${errorMessage}`);
-    }
+    if (!response.ok) return client.fail(response);
     const updated = await response.json();
     return mapPersonToEntity(updated);
 }

package/lib/connector.js

@@ -1,4 +1,5 @@
 import { createGoogleContactsActionHandler } from './actions.js';
+import { canonicalizeContactIntent } from './intent.js';
 import { googleContactsClusters } from './model.js';
 import { createGoogleContactsProvider } from './provider.js';
 export function createGoogleContactsConnector(options) {
@@ -46,7 +47,14 @@ export function createGoogleContactsConnector(options) {
                     required: [
                         'displayName'
                     ]
-                }
+                },
+                // Google assigns the resourceName (people/{id}) — there is no
+                // caller-supplied deterministic id to key a safe reissue on, unlike
+                // the google-calendar connector's create. A blind retry after an
+                // outcome-unknown failure could create a duplicate contact, so
+                // recovery must reconcile rather than reissue; this action is never
+                // re-dispatched on recovery.
+                recoveryClass: 'reconcile-only'
             },
             {
                 name: 'update',
@@ -78,19 +86,37 @@ export function createGoogleContactsConnector(options) {
                     required: [
                         'sourceID'
                     ]
-                }
+                },
+                // Written against the etag the contact was fetched with, pinned on the
+                // operation at claim: a contact changed at Google since is refused
+                // (FAILED_PRECONDITION), never overwritten. A reissue would meet its
+                // own earlier write's new etag, so recovery reconciles (reads current
+                // provider state) rather than reissues.
+                recoveryClass: 'reconcile-only',
+                providerETagField: 'etag',
+                // The People API writes a contact only against its etag.
+                providerETagRequired: true
             }
         ],
+        canonicalizeIntent: canonicalizeContactIntent,
+        // A contact write lands in the account's own contacts: its target is the
+        // account (`people/me`), already pinned by the operation's account key.
+        resolveActionTarget: async ({ input })=>({
+                target: 'people/me',
+                input
+            }),
         actionHandler: (config)=>{
             return createGoogleContactsActionHandler({
                 credential: config.credential,
-                fetch: options?.fetch
+                fetch: options?.fetch,
+                mintFetchHLC: config.mintFetchHLC
             });
         },
         serverProvider: (config)=>{
             return createGoogleContactsProvider({
                 credential: config.credential,
-                fetch: options?.fetch
+                fetch: options?.fetch,
+                mintFetchHLC: config.mintFetchHLC
             });
         }
     };

package/lib/errors.d.ts

@@ -0,0 +1,21 @@
+import { ConnectorError, type ConnectorErrorOptions } from '@kubun/connector';
+/** A machine-readable failure code fixed for a given Google Contacts failure. */
+export type GoogleContactsErrorCode = 'CONTACT_ETAG_REQUIRED';
+export type GoogleContactsErrorOptions = ConnectorErrorOptions & {
+    code?: GoogleContactsErrorCode;
+};
+/** A Google Contacts connector failure, classified the way `ConnectorError` is. */
+export declare class GoogleContactsError extends ConnectorError {
+    constructor(message: string, options?: GoogleContactsErrorOptions);
+    get code(): GoogleContactsErrorCode | undefined;
+}
+/**
+ * An update was attempted against a contact with no stored etag to write
+ * against. The People API requires an etag on every update; the only way to
+ * get one for a contact synced before this field existed is a fresh read,
+ * which would overwrite a change made at Google since the edit — so the
+ * write is refused before any request instead.
+ */
+export declare class ContactEtagRequired extends GoogleContactsError {
+    constructor();
+}

package/lib/errors.js

@@ -0,0 +1,25 @@
+import { ConnectorError } from '@kubun/connector';
+/** A Google Contacts connector failure, classified the way `ConnectorError` is. */ export class GoogleContactsError extends ConnectorError {
+    constructor(message, options = {}){
+        super(message, options);
+        this.name = 'GoogleContactsError';
+    }
+    get code() {
+        return super.code;
+    }
+}
+/**
+ * An update was attempted against a contact with no stored etag to write
+ * against. The People API requires an etag on every update; the only way to
+ * get one for a contact synced before this field existed is a fresh read,
+ * which would overwrite a change made at Google since the edit — so the
+ * write is refused before any request instead.
+ */ export class ContactEtagRequired extends GoogleContactsError {
+    constructor(){
+        super('CONTACT_ETAG_REQUIRED: the contact has no stored etag to write against; sync contacts before editing it', {
+            code: 'CONTACT_ETAG_REQUIRED',
+            kind: 'rejected'
+        });
+        this.name = 'ContactEtagRequired';
+    }
+}

package/lib/index.d.ts

@@ -1,5 +1,7 @@
 export { createGoogleContactsActionHandler, type GoogleContactsActionHandlerConfig, } from './actions.js';
 export { buildListURL, buildPersonFromParams, type CreateContactParams, createContact, type GoogleConnectionsResponse, type GooglePersonResource, mapPersonToEntity, type UpdateContactParams, updateContact, } from './api.js';
 export { type CreateGoogleContactsConnectorOptions, createGoogleContactsConnector, } from './connector.js';
+export { ContactEtagRequired, GoogleContactsError, type GoogleContactsErrorCode, type GoogleContactsErrorOptions, } from './errors.js';
+export { canonicalizeContactIntent } from './intent.js';
 export { googleContactDefinition, googleContactsClusters } from './model.js';
 export { createGoogleContactsProvider, type GoogleContactsProviderConfig } from './provider.js';

package/lib/index.js

@@ -1,5 +1,7 @@
 export { createGoogleContactsActionHandler } from './actions.js';
 export { buildListURL, buildPersonFromParams, createContact, mapPersonToEntity, updateContact } from './api.js';
 export { createGoogleContactsConnector } from './connector.js';
+export { ContactEtagRequired, GoogleContactsError } from './errors.js';
+export { canonicalizeContactIntent } from './intent.js';
 export { googleContactDefinition, googleContactsClusters } from './model.js';
 export { createGoogleContactsProvider } from './provider.js';

package/lib/intent.d.ts

@@ -0,0 +1,8 @@
+import type { IntentCanonicalizer } from '@kubun/connector';
+/**
+ * The Contacts intent canonicalizer (see `IntentCanonicalizer`). The People
+ * API keeps no empty value — a written empty string comes back as an absent
+ * field — so an empty string compares equal to an absent one, on both sides.
+ * Nothing else is folded: a value is never taken for a different one.
+ */
+export declare const canonicalizeContactIntent: IntentCanonicalizer;

package/lib/intent.js

@@ -0,0 +1,20 @@
+import { googleContactDefinition } from './model.js';
+/**
+ * The Contacts intent canonicalizer (see `IntentCanonicalizer`). The People
+ * API keeps no empty value — a written empty string comes back as an absent
+ * field — so an empty string compares equal to an absent one, on both sides.
+ * Nothing else is folded: a value is never taken for a different one.
+ */ export const canonicalizeContactIntent = ({ model, intent, record })=>{
+    if (model !== googleContactDefinition.name) return {
+        intent,
+        record
+    };
+    const withoutEmpty = (values)=>Object.fromEntries(Object.entries(values).map(([field, value])=>[
+                field,
+                value === '' ? undefined : value
+            ]));
+    return {
+        intent: withoutEmpty(intent),
+        record: withoutEmpty(record)
+    };
+};

package/lib/model.d.ts

@@ -35,10 +35,18 @@ export declare const googleContactDefinition: {
             readonly photoURL: {
                 readonly $ref: "#/definitions/PhotoURL";
             };
+            readonly etag: {
+                readonly type: "string";
+            };
         };
         readonly required: ["sourceService", "sourceID", "lastSyncedAt"];
         readonly additionalProperties: false;
         readonly definitions: {
+            readonly PhotoURL: {
+                readonly type: "string";
+                readonly format: "uri";
+                readonly title: "URL";
+            };
             readonly SourceService: {
                 readonly type: "string";
                 readonly title: "SourceService";
@@ -56,14 +64,12 @@ export declare const googleContactDefinition: {
                 readonly format: "uri";
                 readonly title: "URL";
             };
-            readonly PhotoURL: {
-                readonly type: "string";
-                readonly format: "uri";
-                readonly title: "URL";
-            };
             readonly DateTime: import("json-schema-typed").JSONSchema.String;
         };
     };
     readonly fieldsMeta: {};
+    readonly providerMergePolicy: {
+        readonly group: ["displayName", "sourceService", "sourceID", "sourceURL", "email", "phoneNumber", "organization", "jobTitle", "photoURL", "etag"];
+    };
 };
 export declare const googleContactsClusters: import("@kubun/protocol").ClustersRecord;

package/lib/model.js

@@ -1,7 +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, urlSchema } from '@kubun/scalars';
+import { urlSchema } from '@kubun/scalars';
 export const googleContactDefinition = {
     name: 'GoogleContact',
     behavior: 'default',
@@ -41,6 +41,9 @@ export const googleContactDefinition = {
             },
             photoURL: {
                 $ref: '#/definitions/PhotoURL'
+            },
+            etag: {
+                type: 'string'
             }
         },
         required: [
@@ -50,24 +53,29 @@ export const googleContactDefinition = {
         ],
         additionalProperties: false,
         definitions: {
-            SourceService: {
-                type: 'string',
-                title: 'SourceService',
-                minLength: 1,
-                maxLength: 50
-            },
-            SourceID: {
-                type: 'string',
-                title: 'SourceID',
-                minLength: 1,
-                maxLength: 500
-            },
-            SourceURL: urlSchema,
-            PhotoURL: urlSchema,
-            DateTime: dateTimeSchema
+            ...externalEntityDefinition.schema.definitions,
+            PhotoURL: urlSchema
         }
     },
-    fieldsMeta: {}
+    fieldsMeta: {},
+    // lastSyncedAt is a device-local sync-bookkeeping annotation, not fetched
+    // provider content, so it stays outside the group.
+    providerMergePolicy: {
+        group: [
+            'displayName',
+            'sourceService',
+            'sourceID',
+            'sourceURL',
+            'email',
+            'phoneNumber',
+            'organization',
+            'jobTitle',
+            'photoURL',
+            // The provider revision of this state: an update is written against it,
+            // so it must travel with the fields it versions.
+            'etag'
+        ]
+    }
 };
 const builder = new GraphBuilder({
     externalClusters: {

package/lib/provider.d.ts

@@ -3,5 +3,6 @@ import type { Credential } from '@kubun/credential-types';
 export type GoogleContactsProviderConfig = {
     credential: Credential;
     fetch?: typeof globalThis.fetch;
+    mintFetchHLC: () => string;
 };
 export declare function createGoogleContactsProvider(config: GoogleContactsProviderConfig): ServerDataProvider;

package/lib/provider.js

@@ -1,24 +1,19 @@
-import { resolveModelID } from '@kubun/connector';
-import { buildListURL, mapPersonToEntity } from './api.js';
+import { fetchOrAbsent, resolveModelID } from '@kubun/connector';
+import { buildListURL, getPerson, getPersonWithETag, mapPersonToEntity, peopleAPIClient } from './api.js';
 import { googleContactsClusters } from './model.js';
 const GOOGLE_CONTACT_MODEL_ID = resolveModelID(googleContactsClusters, 'GoogleContact');
 export function createGoogleContactsProvider(config) {
     const fetchFn = config.fetch ?? globalThis.fetch;
+    const client = peopleAPIClient(config.credential.accessToken, fetchFn);
+    const mintFetchHLC = config.mintFetchHLC;
     async function fetchPage(params) {
         const url = buildListURL({
             pageToken: params.pageToken,
             syncToken: params.syncToken
         });
-        const response = await fetchFn(url, {
-            headers: {
-                Authorization: `Bearer ${config.credential.accessToken}`
-            },
+        return client.get(url, {
             signal: params.signal
         });
-        if (!response.ok) {
-            throw new Error(`Google People API error: ${response.status} ${response.statusText}`);
-        }
-        return await response.json();
     }
     async function* fetchAllEntities(params) {
         let pageToken;
@@ -28,7 +23,15 @@ export function createGoogleContactsProvider(config) {
                 pageToken,
                 signal: params.signal
             });
-            const entities = (data.connections ?? []).map(mapPersonToEntity);
+            const sourceFetchHLC = mintFetchHLC();
+            // A first sync never carries a syncToken, so Google never returns a
+            // deleted tombstone on this path — deletion detection is
+            // incremental-only (see fetchIncrementalEntities).
+            const entities = (data.connections ?? []).map((person)=>({
+                    present: true,
+                    record: mapPersonToEntity(person),
+                    sourceFetchHLC
+                }));
             pageToken = data.nextPageToken;
             syncToken = data.nextSyncToken;
             yield {
@@ -39,33 +42,96 @@ export function createGoogleContactsProvider(config) {
             };
         }while (pageToken != null)
     }
+    async function* fetchIncrementalEntities(params) {
+        const syncToken = params.checkpoint;
+        let pageToken;
+        do {
+            const data = await fetchPage({
+                pageToken,
+                syncToken: pageToken != null ? undefined : syncToken,
+                signal: params.signal
+            });
+            const sourceFetchHLC = mintFetchHLC();
+            const connections = data.connections ?? [];
+            // A removed contact comes back with only resourceName + metadata.deleted
+            // populated (all content fields absent) — split it into the deletion
+            // batch instead of mapping it as content.
+            const activePersons = connections.filter((p)=>p.metadata?.deleted !== true);
+            const deletedPersons = connections.filter((p)=>p.metadata?.deleted === true);
+            pageToken = data.nextPageToken;
+            yield {
+                modelID: GOOGLE_CONTACT_MODEL_ID,
+                entities: activePersons.map((person)=>({
+                        present: true,
+                        record: mapPersonToEntity(person),
+                        sourceFetchHLC
+                    })),
+                deleted: deletedPersons.map((person)=>({
+                        present: false,
+                        sourceID: person.resourceName,
+                        sourceFetchHLC
+                    })),
+                hasMore: pageToken != null,
+                checkpoint: data.nextSyncToken
+            };
+        }while (pageToken != null)
+    }
+    // Targeted single-entity fetch (anti-entropy repair verification). Mints its
+    // own fetch-order token at request start, independent of any batch token
+    // (see ServerProviderFactory.mintFetchHLC's doc).
+    async function fetchEntity(_model, sourceID) {
+        const sourceFetchHLC = mintFetchHLC();
+        return fetchOrAbsent({
+            sourceID,
+            sourceFetchHLC,
+            read: async ()=>{
+                const record = await getPerson({
+                    accessToken: config.credential.accessToken,
+                    sourceID,
+                    fetch: fetchFn
+                });
+                return {
+                    record
+                };
+            }
+        });
+    }
+    // Provider-authoritative re-read for write-back recovery. Unlike
+    // fetchEntity, the present:true branch also surfaces a providerETag when the
+    // provider reports one — the current revision an update's conditional write
+    // can condition on.
+    async function reconcile(_model, sourceID) {
+        const sourceFetchHLC = mintFetchHLC();
+        return fetchOrAbsent({
+            sourceID,
+            sourceFetchHLC,
+            read: async ()=>{
+                const { record, etag } = await getPersonWithETag({
+                    accessToken: config.credential.accessToken,
+                    sourceID,
+                    fetch: fetchFn
+                });
+                return {
+                    record,
+                    providerETag: etag
+                };
+            }
+        });
+    }
     return {
         supportedStrategies: [
             'on-demand'
         ],
         fetchAll: fetchAllEntities,
+        fetchEntity,
+        reconcile,
         async *fetchChanges (params) {
             const syncToken = params.checkpoint;
             if (syncToken == null) {
                 yield* fetchAllEntities(params);
                 return;
             }
-            let pageToken;
-            do {
-                const data = await fetchPage({
-                    pageToken,
-                    syncToken: pageToken != null ? undefined : syncToken,
-                    signal: params.signal
-                });
-                const entities = (data.connections ?? []).map(mapPersonToEntity);
-                pageToken = data.nextPageToken;
-                yield {
-                    modelID: GOOGLE_CONTACT_MODEL_ID,
-                    entities,
-                    hasMore: pageToken != null,
-                    checkpoint: data.nextSyncToken
-                };
-            }while (pageToken != null)
+            yield* fetchIncrementalEntities(params);
         }
     };
 }

package/package.json

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