@kubun/connector-google-contacts 0.17.2 → 0.18.0

package/lib/actions.d.ts

@@ -1,4 +1,4 @@
-import type { ActionHandler } from '@kubun/connector';
+import { type ActionHandler } from '@kubun/connector';
 export type GoogleContactsActionHandlerConfig = {
     credential: {
         accessToken: string;

package/lib/actions.js

@@ -1,16 +1,18 @@
+import { carryField, refuseCutLists } from '@kubun/connector';
 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) {
+// A carried value trimmed at sync is refused (`carryField`), never sent.
+function withOrganizationPair(params, existing, context) {
     const changesOne = 'organization' in params !== 'jobTitle' in params;
     if (!changesOne || existing == null) return params;
     return 'organization' in params ? {
         ...params,
-        jobTitle: existing.jobTitle
+        jobTitle: carryField(existing, 'jobTitle', context)
     } : {
         ...params,
-        organization: existing.organization
+        organization: carryField(existing, 'organization', context)
     };
 }
 export function createGoogleContactsActionHandler(config) {
@@ -29,10 +31,11 @@ export function createGoogleContactsActionHandler(config) {
             };
         },
         async update (_model, sourceID, params, existing, context) {
+            refuseCutLists(params, context);
             const record = await updateContact({
                 accessToken: config.credential.accessToken,
                 sourceID,
-                params: withOrganizationPair(params, existing),
+                params: withOrganizationPair(params, existing, context),
                 etag: context?.providerETag,
                 fetch: config.fetch
             });

package/lib/api.d.ts

@@ -1,26 +1,60 @@
 import { type EntityRecord } from '@kubun/connector';
 import { type GoogleAPIClient } from '@kubun/provider-google';
+export type GooglePersonName = {
+    displayName?: string;
+    givenName?: string;
+    familyName?: string;
+    unstructuredName?: string;
+};
+export type GooglePersonLabeledValue = {
+    value?: string;
+    type?: string;
+    metadata?: {
+        primary?: boolean;
+    };
+};
+export type GooglePersonAddress = {
+    streetAddress?: string;
+    city?: string;
+    region?: string;
+    postalCode?: string;
+    country?: string;
+    type?: string;
+    metadata?: {
+        primary?: boolean;
+    };
+};
+export type GooglePersonOrganization = {
+    name?: string;
+    title?: string;
+};
+export type GooglePersonBirthday = {
+    date?: {
+        year?: number;
+        month?: number;
+        day?: number;
+    };
+};
+export type GooglePersonPhoto = {
+    url?: string;
+    default?: boolean;
+};
 export type GooglePersonResource = {
     resourceName: string;
     etag?: string;
-    names?: Array<{
-        displayName?: string;
-        givenName?: string;
-        familyName?: string;
-    }>;
-    emailAddresses?: Array<{
+    names?: Array<GooglePersonName>;
+    nicknames?: Array<{
         value?: string;
     }>;
-    phoneNumbers?: Array<{
+    emailAddresses?: Array<GooglePersonLabeledValue>;
+    phoneNumbers?: Array<GooglePersonLabeledValue>;
+    addresses?: Array<GooglePersonAddress>;
+    organizations?: Array<GooglePersonOrganization>;
+    birthdays?: Array<GooglePersonBirthday>;
+    biographies?: Array<{
         value?: string;
     }>;
-    organizations?: Array<{
-        name?: string;
-        title?: string;
-    }>;
-    photos?: Array<{
-        url?: string;
-    }>;
+    photos?: Array<GooglePersonPhoto>;
     metadata?: {
         deleted?: boolean;
     };
@@ -32,11 +66,12 @@ export type GoogleConnectionsResponse = {
     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,7 +1,7 @@
 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 PERSON_FIELDS = 'names,nicknames,emailAddresses,phoneNumbers,addresses,organizations,birthdays,biographies,photos';
 const CONTACTS_BASE_URL = 'https://people.googleapis.com/v1';
 // A Google People API resource name is `people/{id}`. A sourceID reaches here
 // from caller-controlled GraphQL input and is interpolated straight into the
@@ -46,43 +46,164 @@ export function buildListURL(params) {
     }
     return url.toString();
 }
+// An empty provider string is no value: the model's text fields hold at
+// least one character.
+function text(value) {
+    return value == null || value === '' ? undefined : value;
+}
+function nonEmpty(items) {
+    return items == null || items.length === 0 ? undefined : items;
+}
+// Emails and phone numbers share the same labeled-value shape at Google
+// (value, a free-text type, and a primary bit) and in the model (LabeledValue).
+function mapLabeledValue(entry) {
+    const mapped = {
+        value: entry.value
+    };
+    const label = text(entry.type);
+    if (label != null) mapped.label = label;
+    if (entry.metadata?.primary === true) mapped.primary = true;
+    return mapped;
+}
+function mapAddress(entry) {
+    const mapped = {};
+    const street = text(entry.streetAddress);
+    if (street != null) mapped.street = street;
+    const locality = text(entry.city);
+    if (locality != null) mapped.locality = locality;
+    const region = text(entry.region);
+    if (region != null) mapped.region = region;
+    const postalCode = text(entry.postalCode);
+    if (postalCode != null) mapped.postalCode = postalCode;
+    const country = text(entry.country);
+    if (country != null) mapped.country = country;
+    const label = text(entry.type);
+    if (label != null) mapped.label = label;
+    if (entry.metadata?.primary === true) mapped.primary = true;
+    return mapped;
+}
+function pad2(value) {
+    return String(value).padStart(2, '0');
+}
+// Google keeps a birthday with no year as `{ month, day }` alone. The
+// model's birthday is a single LocalDate, which cannot name a year-less day
+// without inventing one, so a year-less birthday is left unmapped rather
+// than guessing a year.
+function mapBirthday(person) {
+    const date = person.birthdays?.[0]?.date;
+    if (date?.year == null || date.month == null || date.day == null) return undefined;
+    return `${date.year}-${pad2(date.month)}-${pad2(date.day)}`;
+}
+function mapPrimaryPhotoURL(person) {
+    const photos = person.photos ?? [];
+    return (photos.find((photo)=>photo.default === true) ?? photos[0])?.url;
+}
 export function mapPersonToEntity(person) {
     return {
         sourceService: 'google-contacts',
         sourceID: person.resourceName,
         displayName: person.names?.[0]?.displayName ?? '',
-        email: person.emailAddresses?.[0]?.value ?? undefined,
-        phoneNumber: person.phoneNumbers?.[0]?.value ?? undefined,
+        givenName: text(person.names?.[0]?.givenName),
+        familyName: text(person.names?.[0]?.familyName),
+        nickname: text(person.nicknames?.[0]?.value),
+        emails: nonEmpty(person.emailAddresses)?.map(mapLabeledValue),
+        phones: nonEmpty(person.phoneNumbers)?.map(mapLabeledValue),
+        addresses: nonEmpty(person.addresses)?.map(mapAddress),
         organization: person.organizations?.[0]?.name ?? undefined,
         jobTitle: person.organizations?.[0]?.title ?? undefined,
-        photoURL: person.photos?.[0]?.url ?? undefined,
+        birthday: mapBirthday(person),
+        // Photos are read-only on write (the People API has no way to set a
+        // photo via updateContact), and the model keeps only the one the
+        // provider marks default (or else the first) — never the whole list.
+        photoURL: mapPrimaryPhotoURL(person),
+        note: text(person.biographies?.[0]?.value),
         sourceURL: `https://contacts.google.com/person/${person.resourceName.replace('people/', '')}`,
         etag: person.etag
     };
 }
+function buildLabeledValues(values) {
+    return values.map((value)=>{
+        const entry = value ?? {};
+        const built = {
+            value: entry.value
+        };
+        if (typeof entry.label === 'string') built.type = entry.label;
+        if (entry.primary === true) built.metadata = {
+            primary: true
+        };
+        return built;
+    });
+}
+function buildAddresses(values) {
+    return values.map((value)=>{
+        const entry = value ?? {};
+        const built = {};
+        if (typeof entry.street === 'string') built.streetAddress = entry.street;
+        if (typeof entry.locality === 'string') built.city = entry.locality;
+        if (typeof entry.region === 'string') built.region = entry.region;
+        if (typeof entry.postalCode === 'string') built.postalCode = entry.postalCode;
+        if (typeof entry.country === 'string') built.country = entry.country;
+        if (typeof entry.label === 'string') built.type = entry.label;
+        if (entry.primary === true) built.metadata = {
+            primary: true
+        };
+        return built;
+    });
+}
+const LOCAL_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+function buildBirthday(value) {
+    const match = LOCAL_DATE.exec(value);
+    if (match == null) {
+        throw new GoogleContactsError(`a Google Contacts birthday must be a YYYY-MM-DD date, got ${JSON.stringify(value)}`, {
+            kind: 'rejected'
+        });
+    }
+    return {
+        date: {
+            year: Number(match[1] ?? ''),
+            month: Number(match[2] ?? ''),
+            day: Number(match[3] ?? '')
+        }
+    };
+}
 export function buildPersonFromParams(params) {
     const person = {};
-    if (params.displayName != null) {
+    if (params.givenName != null || params.familyName != null) {
         person.names = [
             {
-                givenName: params.displayName
+                ...params.givenName != null ? {
+                    givenName: params.givenName
+                } : {},
+                ...params.familyName != null ? {
+                    familyName: params.familyName
+                } : {}
             }
         ];
-    }
-    if (params.email != null) {
-        person.emailAddresses = [
+    } else if (params.displayName != null) {
+        // With no structured given/family name, take the caller's display name
+        // as an unstructured name rather than guessing a given/family split.
+        person.names = [
             {
-                value: params.email
+                unstructuredName: params.displayName
             }
         ];
     }
-    if (params.phoneNumber != null) {
-        person.phoneNumbers = [
+    if (params.nickname != null) {
+        person.nicknames = [
             {
-                value: params.phoneNumber
+                value: params.nickname
             }
         ];
     }
+    if (Array.isArray(params.emails)) {
+        person.emailAddresses = buildLabeledValues(params.emails);
+    }
+    if (Array.isArray(params.phones)) {
+        person.phoneNumbers = buildLabeledValues(params.phones);
+    }
+    if (Array.isArray(params.addresses)) {
+        person.addresses = buildAddresses(params.addresses);
+    }
     if (params.organization != null || params.jobTitle != null) {
         person.organizations = [
             {
@@ -95,6 +216,18 @@ export function buildPersonFromParams(params) {
             }
         ];
     }
+    if (params.birthday != null) {
+        person.birthdays = [
+            buildBirthday(params.birthday)
+        ];
+    }
+    if (params.note != null) {
+        person.biographies = [
+            {
+                value: params.note
+            }
+        ];
+    }
     return person;
 }
 // Raw people.get, shared by getPerson/getPersonWithETag (fetchEntity/
@@ -143,9 +276,13 @@ export async function updateContact(options) {
     person.etag = options.etag;
     const updatePersonFields = [];
     if (person.names != null) updatePersonFields.push('names');
+    if (person.nicknames != null) updatePersonFields.push('nicknames');
     if (person.emailAddresses != null) updatePersonFields.push('emailAddresses');
     if (person.phoneNumbers != null) updatePersonFields.push('phoneNumbers');
+    if (person.addresses != null) updatePersonFields.push('addresses');
     if (person.organizations != null) updatePersonFields.push('organizations');
+    if (person.birthdays != null) updatePersonFields.push('birthdays');
+    if (person.biographies != null) updatePersonFields.push('biographies');
     const url = `${CONTACTS_BASE_URL}/${options.sourceID}:updateContact?updatePersonFields=${updatePersonFields.join(',')}&personFields=${PERSON_FIELDS}`;
     const client = createGoogleAPIClient({
         api: 'Google People API',

package/lib/connector.js

@@ -1,7 +1,30 @@
+import { contactsModelDefinitions } from '@kubun/models-contacts';
 import { createGoogleContactsActionHandler } from './actions.js';
 import { canonicalizeContactIntent } from './intent.js';
 import { googleContactsClusters } from './model.js';
 import { createGoogleContactsProvider } from './provider.js';
+const contactKindProperties = contactsModelDefinitions.find((definition)=>definition.name === 'ContactKind')?.schema?.properties ?? {};
+function contactKindProperty(name) {
+    const property = contactKindProperties[name];
+    if (property == null) throw new Error(`ContactKind declares no "${name}" field`);
+    return property;
+}
+// Every ContactKind field a write can set, in the ContactKind shape.
+// `photoURL` is read-only (the People API has no way to set a photo via
+// updateContact), so it is left out.
+const contactInputProperties = {
+    displayName: contactKindProperty('displayName'),
+    givenName: contactKindProperty('givenName'),
+    familyName: contactKindProperty('familyName'),
+    nickname: contactKindProperty('nickname'),
+    emails: contactKindProperty('emails'),
+    phones: contactKindProperty('phones'),
+    addresses: contactKindProperty('addresses'),
+    organization: contactKindProperty('organization'),
+    jobTitle: contactKindProperty('jobTitle'),
+    birthday: contactKindProperty('birthday'),
+    note: contactKindProperty('note')
+};
 export function createGoogleContactsConnector(options) {
     return {
         name: 'google-contacts',
@@ -27,23 +50,7 @@ export function createGoogleContactsConnector(options) {
                 requiresCredential: true,
                 input: {
                     type: 'object',
-                    properties: {
-                        displayName: {
-                            type: 'string'
-                        },
-                        email: {
-                            type: 'string'
-                        },
-                        phoneNumber: {
-                            type: 'string'
-                        },
-                        organization: {
-                            type: 'string'
-                        },
-                        jobTitle: {
-                            type: 'string'
-                        }
-                    },
+                    properties: contactInputProperties,
                     required: [
                         'displayName'
                     ]
@@ -67,21 +74,7 @@ export function createGoogleContactsConnector(options) {
                         sourceID: {
                             type: 'string'
                         },
-                        displayName: {
-                            type: 'string'
-                        },
-                        email: {
-                            type: 'string'
-                        },
-                        phoneNumber: {
-                            type: 'string'
-                        },
-                        organization: {
-                            type: 'string'
-                        },
-                        jobTitle: {
-                            type: 'string'
-                        }
+                        ...contactInputProperties
                     },
                     required: [
                         'sourceID'

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

@@ -1,39 +1,21 @@
 export declare const googleContactDefinition: {
     readonly name: "GoogleContact";
     readonly behavior: "default";
-    readonly interfaces: [string, string];
+    readonly interfaces: [string, string, string];
     readonly schema: {
         readonly type: "object";
         readonly properties: {
-            readonly displayName: {
-                readonly type: "string";
-            };
             readonly sourceService: {
                 readonly $ref: "#/definitions/SourceService";
             };
             readonly sourceID: {
                 readonly $ref: "#/definitions/SourceID";
             };
-            readonly lastSyncedAt: {
-                readonly $ref: "#/definitions/DateTime";
-            };
             readonly sourceURL: {
                 readonly $ref: "#/definitions/SourceURL";
             };
-            readonly email: {
-                readonly type: "string";
-            };
-            readonly phoneNumber: {
-                readonly type: "string";
-            };
-            readonly organization: {
-                readonly type: "string";
-            };
-            readonly jobTitle: {
-                readonly type: "string";
-            };
-            readonly photoURL: {
-                readonly $ref: "#/definitions/PhotoURL";
+            readonly lastSyncedAt: {
+                readonly $ref: "#/definitions/DateTime";
             };
             readonly etag: {
                 readonly type: "string";
@@ -42,11 +24,6 @@ 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";
@@ -69,7 +46,7 @@ export declare const googleContactDefinition: {
     };
     readonly fieldsMeta: {};
     readonly providerMergePolicy: {
-        readonly group: ["displayName", "sourceService", "sourceID", "sourceURL", "email", "phoneNumber", "organization", "jobTitle", "photoURL", "etag"];
+        readonly group: [...string[], "sourceService", "sourceID", "sourceURL", "etag"];
     };
 };
 export declare const googleContactsClusters: import("@kubun/protocol").ClustersRecord;

package/lib/model.js

@@ -1,46 +1,35 @@
 import { connectorClusters, connectorModelIDs, externalEntityDefinition } from '@kubun/connector';
-import { modelIDs, modelsClusters } from '@kubun/models';
+import { contactsClusters, contactsModelDefinitions, contactsModelIDs } from '@kubun/models-contacts';
+import { coreClusters, coreModelIDs } from '@kubun/models-core';
 import { GraphBuilder } from '@kubun/protocol';
-import { urlSchema } from '@kubun/scalars';
+// The shared contact fields (displayName, givenName/familyName, nickname,
+// emails, phones, addresses, organization, jobTitle, birthday, photoURL,
+// note) come from ContactKind, and local tags from Taggable; only what is
+// Google's own is declared here.
+const contactKindProviderFields = contactsModelDefinitions.find((definition)=>definition.name === 'ContactKind')?.providerMergePolicy?.group;
+if (contactKindProviderFields == null) throw new Error('ContactKind provider fields are missing');
 export const googleContactDefinition = {
     name: 'GoogleContact',
     behavior: 'default',
     interfaces: [
         connectorModelIDs.ExternalEntity,
-        modelIDs.ContactKind
+        contactsModelIDs.ContactKind,
+        coreModelIDs.Taggable
     ],
     schema: {
         type: 'object',
         properties: {
-            displayName: {
-                type: 'string'
-            },
             sourceService: {
                 $ref: '#/definitions/SourceService'
             },
             sourceID: {
                 $ref: '#/definitions/SourceID'
             },
-            lastSyncedAt: {
-                $ref: '#/definitions/DateTime'
-            },
             sourceURL: {
                 $ref: '#/definitions/SourceURL'
             },
-            email: {
-                type: 'string'
-            },
-            phoneNumber: {
-                type: 'string'
-            },
-            organization: {
-                type: 'string'
-            },
-            jobTitle: {
-                type: 'string'
-            },
-            photoURL: {
-                $ref: '#/definitions/PhotoURL'
+            lastSyncedAt: {
+                $ref: '#/definitions/DateTime'
             },
             etag: {
                 type: 'string'
@@ -53,24 +42,19 @@ export const googleContactDefinition = {
         ],
         additionalProperties: false,
         definitions: {
-            ...externalEntityDefinition.schema.definitions,
-            PhotoURL: urlSchema
+            ...externalEntityDefinition.schema.definitions
         }
     },
     fieldsMeta: {},
-    // lastSyncedAt is a device-local sync-bookkeeping annotation, not fetched
-    // provider content, so it stays outside the group.
+    // lastSyncedAt is a device-local sync-bookkeeping annotation and tags a
+    // local user annotation, neither fetched provider content, so both stay
+    // outside the group.
     providerMergePolicy: {
         group: [
-            'displayName',
+            ...contactKindProviderFields,
             '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'
@@ -80,7 +64,8 @@ export const googleContactDefinition = {
 const builder = new GraphBuilder({
     externalClusters: {
         ...connectorClusters,
-        ...modelsClusters
+        ...coreClusters,
+        ...contactsClusters
     }
 });
 builder.add(googleContactDefinition);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/connector-google-contacts",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,13 +15,13 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@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.2",
-    "@kubun/provider-google": "^0.17.1",
-    "@kubun/scalars": "^0.17.0"
+    "@kubun/connector": "^0.18.0",
+    "@kubun/credential-types": "^0.18.0",
+    "@kubun/hlc": "^0.18.0",
+    "@kubun/models-contacts": "^0.18.0",
+    "@kubun/models-core": "^0.18.0",
+    "@kubun/protocol": "^0.18.0",
+    "@kubun/provider-google": "^0.18.0"
   },
   "publishConfig": {
     "access": "public"