@kubun/connector-google-contacts 0.17.1 → 0.17.3

package/lib/api.d.ts

@@ -1,4 +1,5 @@
 import { type EntityRecord } from '@kubun/connector';
+import { type GoogleAPIClient } from '@kubun/provider-google';
 export type GooglePersonResource = {
     resourceName: string;
     etag?: string;
@@ -24,17 +25,19 @@ export type GooglePersonResource = {
         deleted?: boolean;
     };
 };
+export declare function peopleAPIClient(accessToken: string, fetch?: typeof globalThis.fetch): GoogleAPIClient;
 export type GoogleConnectionsResponse = {
     connections?: Array<GooglePersonResource>;
     nextPageToken?: string;
     nextSyncToken?: string;
     totalPeople?: number;
 };
-export declare function buildListURL(params: {
+export type BuildListURLParams = {
     pageToken?: string;
     syncToken?: string;
     pageSize?: number;
-}): string;
+};
+export declare function buildListURL(params: BuildListURLParams): string;
 export declare function mapPersonToEntity(person: GooglePersonResource): EntityRecord;
 export declare function buildPersonFromParams(params: Record<string, unknown>): Partial<GooglePersonResource>;
 export declare function getPerson(config: {

package/lib/api.js

@@ -1,4 +1,5 @@
 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';
@@ -12,41 +13,22 @@ function assertValidSourceID(sourceID) {
         throw new Error(`Invalid contact sourceID: ${JSON.stringify(sourceID)}`);
     }
 }
-async function parseGoogleErrorBody(response) {
-    try {
-        const body = await response.json();
-        return {
-            message: body.error?.message ?? `${response.status} ${response.statusText}`,
-            status: body.error?.status
-        };
-    } catch  {
-        return {
-            message: `${response.status} ${response.statusText}`
-        };
-    }
-}
-async function parseGoogleError(response) {
-    return (await parseGoogleErrorBody(response)).message;
-}
-// Build the error thrown by a People API 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: a Google
-// person resource has no `metadata.deleted` flag on a direct get — the 404
-// itself IS the deletion signal.
-function googlePeopleAPIError(status, detail) {
-    return connectorHTTPError(`Google People API error: ${detail}`, status);
+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.
-async function googlePeopleWriteError(response) {
-    const { message, status } = await parseGoogleErrorBody(response);
-    return new GoogleContactsError(`Google People API error: ${message}`, {
-        httpStatus: response.status,
-        kind: status === 'FAILED_PRECONDITION' ? 'unknown' : classifyHTTPStatus(response.status)
+function googlePeopleWriteError(failure) {
+    return new GoogleContactsError(failure.message, {
+        httpStatus: failure.httpStatus,
+        kind: failure.googleStatus === 'FAILED_PRECONDITION' ? 'unknown' : classifyHTTPStatus(failure.httpStatus)
     });
 }
 export function buildListURL(params) {
@@ -117,25 +99,15 @@ export function buildPersonFromParams(params) {
 }
 // Raw people.get, shared by getPerson/getPersonWithETag (fetchEntity/
 // reconcile's targeted read) — a single choke point for sourceID validation
-// and 404 tagging.
+// and 404 classification.
 async function fetchPersonResource(config) {
     assertValidSourceID(config.sourceID);
-    const fetchFn = config.fetch ?? globalThis.fetch;
     const url = `${CONTACTS_BASE_URL}/${config.sourceID}?personFields=${PERSON_FIELDS}`;
-    const response = await fetchFn(url, {
-        headers: {
-            Authorization: `Bearer ${config.accessToken}`
-        }
-    });
-    if (!response.ok) {
-        const errorMessage = await parseGoogleError(response);
-        throw googlePeopleAPIError(response.status, errorMessage);
-    }
-    return await response.json();
+    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 — see
-// googlePeopleAPIError's doc.
+// 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);
@@ -151,21 +123,11 @@ export async function getPersonWithETag(config) {
     };
 }
 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 googlePeopleAPIError(response.status, errorMessage);
-    }
-    const created = await response.json();
     return mapPersonToEntity(created);
 }
 function contactEtagRequired() {
@@ -177,7 +139,6 @@ export async function updateContact(options) {
     // 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 fetchFn = options.fetch ?? globalThis.fetch;
     const person = buildPersonFromParams(options.params);
     person.etag = options.etag;
     const updatePersonFields = [];
@@ -186,15 +147,17 @@ export async function updateContact(options) {
     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) throw await googlePeopleWriteError(response);
+    if (!response.ok) return client.fail(response);
     const updated = await response.json();
     return mapPersonToEntity(updated);
 }

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 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 BuildListURLParams, 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';

package/lib/model.d.ts

@@ -42,6 +42,11 @@ export declare const googleContactDefinition: {
         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";
@@ -59,11 +64,6 @@ 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;
         };
     };

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',
@@ -53,21 +53,8 @@ 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: {},

package/lib/provider.js

@@ -1,32 +1,19 @@
-import { resolveModelID } from '@kubun/connector';
-import { buildListURL, getPerson, getPersonWithETag, 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;
-    // getPerson/getPersonWithETag (api.ts) throw a plain Error tagged with
-    // `.httpStatus` (googlePeopleAPIError) — 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 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;
@@ -94,27 +81,20 @@ export function createGoogleContactsProvider(config) {
     // (see ServerProviderFactory.mintFetchHLC's doc).
     async function fetchEntity(_model, sourceID) {
         const sourceFetchHLC = mintFetchHLC();
-        try {
-            const record = await getPerson({
-                accessToken: config.credential.accessToken,
-                sourceID,
-                fetch: fetchFn
-            });
-            return {
-                present: true,
-                record,
-                sourceFetchHLC
-            };
-        } catch (err) {
-            if (isNotFound(err)) {
-                return {
-                    present: false,
+        return fetchOrAbsent({
+            sourceID,
+            sourceFetchHLC,
+            read: async ()=>{
+                const record = await getPerson({
+                    accessToken: config.credential.accessToken,
                     sourceID,
-                    sourceFetchHLC
+                    fetch: fetchFn
+                });
+                return {
+                    record
                 };
             }
-            throw err;
-        }
+        });
     }
     // Provider-authoritative re-read for write-back recovery. Unlike
     // fetchEntity, the present:true branch also surfaces a providerETag when the
@@ -122,30 +102,21 @@ export function createGoogleContactsProvider(config) {
     // can condition on.
     async function reconcile(_model, sourceID) {
         const sourceFetchHLC = mintFetchHLC();
-        try {
-            const { record, etag } = await getPersonWithETag({
-                accessToken: config.credential.accessToken,
-                sourceID,
-                fetch: fetchFn
-            });
-            return {
-                present: true,
-                record,
-                sourceFetchHLC,
-                ...etag != null ? {
-                    providerETag: etag
-                } : {}
-            };
-        } catch (err) {
-            if (isNotFound(err)) {
-                return {
-                    present: false,
+        return fetchOrAbsent({
+            sourceID,
+            sourceFetchHLC,
+            read: async ()=>{
+                const { record, etag } = await getPersonWithETag({
+                    accessToken: config.credential.accessToken,
                     sourceID,
-                    sourceFetchHLC
+                    fetch: fetchFn
+                });
+                return {
+                    record,
+                    providerETag: etag
                 };
             }
-            throw err;
-        }
+        });
     }
     return {
         supportedStrategies: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/connector-google-contacts",
-  "version": "0.17.1",
+  "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"
   },
   "publishConfig": {