@kubun/connector-google-calendar 0.17.0 → 0.17.2

package/lib/account-key.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Non-reversible, deterministic account key projected to the graph in place of
+ * the raw provider identity. A pure function of (iss, sub) — no salt — so it
+ * survives credential deletion/re-auth so it stays stable across reconcile.
+ * This is a consistency label, not provenance.
+ */
+export declare function deriveAccountKey(account: {
+    iss: string;
+    sub: string;
+}): string;

package/lib/account-key.js

@@ -0,0 +1,19 @@
+import { digestJSON } from '@kubun/id';
+import { toB64U } from '@sozai/codec';
+/**
+ * Non-reversible, deterministic account key projected to the graph in place of
+ * the raw provider identity. A pure function of (iss, sub) — no salt — so it
+ * survives credential deletion/re-auth so it stays stable across reconcile.
+ * This is a consistency label, not provenance.
+ */ export function deriveAccountKey(account) {
+    // The extractor (plugin-connector's extractProviderAccount) accepts both
+    // 'https://accounts.google.com' and bare 'accounts.google.com' as valid
+    // Google iss claims. The key must be stable across whichever spelling a
+    // given token carries, so canonicalize before hashing.
+    const canonicalIss = account.iss === 'accounts.google.com' ? 'https://accounts.google.com' : account.iss;
+    return toB64U(digestJSON({
+        v: 'gcal-account',
+        iss: canonicalIss,
+        sub: account.sub
+    }));
+}

package/lib/actions.d.ts

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

package/lib/actions.js

@@ -1,59 +1,111 @@
-import { createEvent, getCalendar, updateEvent } from './api.js';
+import { createEvent, updateEvent } from './api.js';
+import { GoogleCalendarError } from './errors.js';
+import { deriveEventID } from './event-id.js';
+/**
+ * The params of a sparse PATCH: only what the write changes, never the rest
+ * of the (possibly stale) local document. The one exception is how a changed
+ * start/end is written: it keeps the event's all-day form and time zone from
+ * the target document, and a changed time zone or all-day flag rewrites the
+ * start and end it applies to.
+ */ function sparsePatchParams(params, existing) {
+    const patch = {
+        ...params
+    };
+    // An all-day flip carries the event's current start/end over in the new
+    // form. Turning a timed event whose end falls on its start day all-day
+    // gives start.date == end.date, which Google rejects (400, an exclusive end
+    // must be later): the write dead-letters rather than guessing an end.
+    const reshapesTimes = 'timeZone' in params || 'allDay' in params;
+    for (const field of [
+        'startAt',
+        'endAt'
+    ]){
+        if (patch[field] == null && reshapesTimes && existing?.[field] != null) {
+            patch[field] = existing[field];
+        }
+    }
+    const writesTimes = patch.startAt != null || patch.endAt != null;
+    if (writesTimes) {
+        if (!('allDay' in patch) && existing?.allDay != null) patch.allDay = existing.allDay;
+        if (!('timeZone' in patch) && existing?.timeZone != null) patch.timeZone = existing.timeZone;
+    }
+    return patch;
+}
 export function createGoogleCalendarActionHandler(config) {
+    const mintActionFetchHLC = config.mintFetchHLC;
     return {
-        async create (_model, params) {
+        async create (_model, params, context) {
             const calendarID = params.calendarID;
             if (calendarID == null) {
                 throw new Error('calendarID is required for creating calendar events');
             }
-            // 'primary' is a per-account alias; sync sees the real id. Resolve it once
-            // on create so the composite sourceID matches the synced event's identity.
-            const resolvedCalendarID = calendarID === 'primary' ? (await getCalendar({
-                accessToken: config.credential.accessToken,
-                calendarID: 'primary',
-                fetch: config.fetch
-            })).id : calendarID;
-            return createEvent({
+            // The action layer resolves the 'primary' alias from synced data before
+            // the operation is claimed (resolveCalendarTarget); the handler writes
+            // only to a resolved calendar and never resolves the alias itself.
+            if (calendarID === 'primary') {
+                throw new GoogleCalendarError("the 'primary' calendar alias must be resolved before the write; name the calendar id", {
+                    kind: 'rejected'
+                });
+            }
+            const resolvedCalendarID = calendarID;
+            // The provider id is derived from the operation's deterministic event
+            // id, so every attempt of the operation inserts under the same id and a
+            // re-issue after a lost response hits a 409 instead of a duplicate.
+            const record = await createEvent({
                 accessToken: config.credential.accessToken,
                 calendarID: resolvedCalendarID,
                 params,
+                ...context != null ? {
+                    eventID: deriveEventID(context.deterministicEventID)
+                } : {},
                 fetch: config.fetch
             });
+            return {
+                present: true,
+                record,
+                sourceFetchHLC: mintActionFetchHLC()
+            };
         },
-        async update (_model, sourceID, params) {
-            // sourceID is the composite calendarID/eventID. On a lookup hit the merged
-            // document supplies eventID + calendarID directly; on a miss recover both
-            // from the composite. An eventID never contains '/', a calendarID may, so
-            // split on the last '/'.
-            const mergedEventID = params.eventID;
-            const mergedCalendarID = params.calendarID;
+        async update (_model, sourceID, params, existing, context) {
+            // sourceID is the composite calendarID/eventID. The target document
+            // (`existing`) names the event; without it, recover both ids from the
+            // composite — an eventID never contains '/', a calendarID may, so split
+            // on the last '/'.
+            const knownEventID = existing?.eventID ?? params.eventID;
+            const knownCalendarID = existing?.calendarID ?? params.calendarID;
             let eventID;
             let calendarID;
-            if (mergedEventID != null) {
-                if (mergedCalendarID == null) {
+            if (knownEventID != null) {
+                if (knownCalendarID == null) {
                     throw new Error('calendarID is required for updating calendar events');
                 }
-                eventID = mergedEventID;
-                calendarID = mergedCalendarID;
+                eventID = knownEventID;
+                calendarID = knownCalendarID;
             } else {
                 const slash = sourceID.lastIndexOf('/');
                 if (slash <= 0 || slash === sourceID.length - 1) {
                     throw new Error(`Cannot recover eventID from sourceID "${sourceID}"`);
                 }
                 const recoveredCalendarID = sourceID.slice(0, slash);
-                if (mergedCalendarID != null && mergedCalendarID !== recoveredCalendarID) {
+                if (knownCalendarID != null && knownCalendarID !== recoveredCalendarID) {
                     throw new Error('calendarID does not match the event sourceID');
                 }
                 eventID = sourceID.slice(slash + 1);
                 calendarID = recoveredCalendarID;
             }
-            return updateEvent({
+            const record = await updateEvent({
                 accessToken: config.credential.accessToken,
                 calendarID,
                 eventID,
-                params,
+                params: sparsePatchParams(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';
+export { type ConnectorErrorKind, classifyHTTPStatus } from '@kubun/connector';
 export declare function parseGoogleError(response: Response): Promise<string>;
 export type GoogleCalendarResource = {
     id: string;
@@ -23,6 +24,7 @@ export type GoogleEventDateTime = {
 };
 export type GoogleEventResource = {
     id: string;
+    etag?: string;
     summary?: string;
     description?: string;
     location?: string;
@@ -47,26 +49,42 @@ export declare function buildEventsListURL(params: {
     pageToken?: string;
     timeMin?: string;
 }): string;
-export declare function mapCalendarToEntity(calendar: GoogleCalendarResource): EntityRecord;
+export declare function mapCalendarToEntity(calendar: GoogleCalendarResource, accountKey?: string): EntityRecord;
 export declare function mapEventToEntity(event: GoogleEventResource, calendarID: string): EntityRecord;
 export declare function buildEventFromParams(params: Record<string, unknown>, options?: {
     create?: boolean;
+    eventID?: string;
 }): Record<string, unknown>;
-export declare function getCalendar(config: {
+export declare function getCalendarListEntry(config: {
     accessToken: string;
     calendarID: string;
     fetch?: typeof globalThis.fetch;
 }): Promise<GoogleCalendarResource>;
+export declare function splitEventSourceID(sourceID: string): {
+    calendarID: string;
+    eventID: string;
+};
 export declare function getEvent(config: {
     accessToken: string;
     calendarID: string;
     eventID: string;
     fetch?: typeof globalThis.fetch;
 }): Promise<EntityRecord>;
+export declare function getEventWithETag(config: {
+    accessToken: string;
+    calendarID: string;
+    eventID: string;
+    fetch?: typeof globalThis.fetch;
+}): Promise<{
+    record: EntityRecord;
+    etag?: string;
+}>;
 export declare function createEvent(config: {
     accessToken: string;
     calendarID: string;
     params: Record<string, unknown>;
+    /** The provider event id to insert under (see `deriveEventID`); takes precedence over `params.id`. */
+    eventID?: string;
     fetch?: typeof globalThis.fetch;
 }): Promise<EntityRecord>;
 export declare function updateEvent(config: {
@@ -74,5 +92,13 @@ export declare function updateEvent(config: {
     calendarID: string;
     eventID: string;
     params: Record<string, unknown>;
+    /**
+     * The event's etag as last fetched, sent as If-Match: a change at Google
+     * since then fails the PATCH with a 412 (outcome `unknown`, resolved by
+     * recovery's reconcile read) instead of being overwritten. It is never
+     * re-read right before the write — that would guard nothing. Absent, the
+     * PATCH is unconditional.
+     */
+    etag?: string | null;
     fetch?: typeof globalThis.fetch;
 }): Promise<EntityRecord>;

package/lib/api.js

@@ -1,3 +1,7 @@
+import { connectorHTTPError } from '@kubun/connector';
+import { GoogleCalendarEventConflict } from './errors.js';
+import { eventHoldsIntent } from './intent.js';
+export { classifyHTTPStatus } from '@kubun/connector';
 const CALENDAR_BASE_URL = 'https://www.googleapis.com/calendar/v3';
 export async function parseGoogleError(response) {
     try {
@@ -7,6 +11,23 @@ export async function parseGoogleError(response) {
         return `${response.status} ${response.statusText}`;
     }
 }
+/**
+ * Build the error thrown by an action's provider call, tagged with the HTTP
+ * status and its outcome classification so the caller can distinguish a
+ * definite rejection from an indeterminate failure.
+ */ function googleAPIError(status, detail) {
+    return connectorHTTPError(`Google Calendar API error: ${detail}`, status);
+}
+/**
+ * A create that collided with an existing event it could not confirm as its
+ * own. Outcome-unknown, not a rejection: the event may be this create's own
+ * earlier effect, edited since. `code: 'CONFLICT'` and `sourceID` let
+ * write-back recovery reconcile against the event.
+ */ function eventConflict(sourceID, cause) {
+    return new GoogleCalendarEventConflict(sourceID, cause != null ? {
+        cause
+    } : undefined);
+}
 export function buildCalendarListURL(params) {
     const url = new URL(`${CALENDAR_BASE_URL}/users/me/calendarList`);
     // Google rejects `showHidden=false` (and `showDeleted=false`) alongside a
@@ -37,7 +58,7 @@ export function buildEventsListURL(params) {
     }
     return url.toString();
 }
-export function mapCalendarToEntity(calendar) {
+export function mapCalendarToEntity(calendar, accountKey) {
     return {
         sourceService: 'google-calendar',
         sourceID: calendar.id,
@@ -46,7 +67,10 @@ export function mapCalendarToEntity(calendar) {
         description: calendar.description,
         timeZone: calendar.timeZone,
         primary: calendar.primary ?? false,
-        backgroundColor: calendar.backgroundColor
+        backgroundColor: calendar.backgroundColor,
+        ...accountKey != null ? {
+            accountKey
+        } : {}
     };
 }
 // Google gives all-day events a bare calendar date (`YYYY-MM-DD`); the model's
@@ -81,17 +105,19 @@ export function mapEventToEntity(event, calendarID) {
         calendar: {
             sourceService: 'google-calendar',
             sourceID: calendarID
-        }
+        },
+        etag: event.etag
     };
 }
 export function buildEventFromParams(params, options) {
     const event = {};
     const allDay = params.allDay === true;
-    // A caller-supplied id makes a create idempotent (Google rejects a duplicate
+    // A caller-chosen id makes a create idempotent (Google rejects a duplicate
     // with 409). Only insert accepts an id; PATCH must never carry one, so gate it
     // to the create path — the builder is shared with updateEvent.
-    if (options?.create === true && params.id != null) {
-        event.id = params.id;
+    const eventID = options?.eventID ?? params.id;
+    if (options?.create === true && eventID != null) {
+        event.id = eventID;
     }
     if (params.title != null) {
         event.summary = params.title;
@@ -127,9 +153,13 @@ export function buildEventFromParams(params, options) {
     }
     return event;
 }
-export async function getCalendar(config) {
+// One calendar as the account's calendar list holds it (calendarList.get) —
+// the same resource sync maps, with the per-account `primary` flag and
+// colour. calendars.get carries neither, so a re-pull from it would clear
+// `primary` and break resolving the 'primary' alias.
+export async function getCalendarListEntry(config) {
     const fetchFn = config.fetch ?? globalThis.fetch;
-    const url = `${CALENDAR_BASE_URL}/calendars/${encodeURIComponent(config.calendarID)}`;
+    const url = `${CALENDAR_BASE_URL}/users/me/calendarList/${encodeURIComponent(config.calendarID)}`;
     const response = await fetchFn(url, {
         headers: {
             Authorization: `Bearer ${config.accessToken}`
@@ -137,11 +167,23 @@ export async function getCalendar(config) {
     });
     if (!response.ok) {
         const errorMessage = await parseGoogleError(response);
-        throw new Error(`Google Calendar API error: ${errorMessage}`);
+        throw googleAPIError(response.status, errorMessage);
     }
     return await response.json();
 }
-export async function getEvent(config) {
+// A composite calendarID/eventID sourceID splits on the LAST '/': an eventID
+// never contains one, but a calendarID (email-like) may.
+export function splitEventSourceID(sourceID) {
+    const slash = sourceID.lastIndexOf('/');
+    if (slash <= 0 || slash === sourceID.length - 1) {
+        throw new Error(`Cannot recover eventID from sourceID "${sourceID}"`);
+    }
+    return {
+        calendarID: sourceID.slice(0, slash),
+        eventID: sourceID.slice(slash + 1)
+    };
+}
+async function fetchEventResource(config) {
     const fetchFn = config.fetch ?? globalThis.fetch;
     const url = `${CALENDAR_BASE_URL}/calendars/${encodeURIComponent(config.calendarID)}/events/${encodeURIComponent(config.eventID)}`;
     const response = await fetchFn(url, {
@@ -151,16 +193,31 @@ export async function getEvent(config) {
     });
     if (!response.ok) {
         const errorMessage = await parseGoogleError(response);
-        throw new Error(`Google Calendar API error: ${errorMessage}`);
+        throw googleAPIError(response.status, errorMessage);
     }
-    const data = await response.json();
+    return await response.json();
+}
+export async function getEvent(config) {
+    const data = await fetchEventResource(config);
     return mapEventToEntity(data, config.calendarID);
 }
+// Same as getEvent, but also surfaces the provider's etag/revision — used by
+// write-back recovery's reconcile read, which reports a providerETag
+// alongside the record.
+export async function getEventWithETag(config) {
+    const data = await fetchEventResource(config);
+    return {
+        record: mapEventToEntity(data, config.calendarID),
+        etag: data.etag
+    };
+}
 export async function createEvent(config) {
     const fetchFn = config.fetch ?? globalThis.fetch;
     const event = buildEventFromParams(config.params, {
-        create: true
+        create: true,
+        eventID: config.eventID
     });
+    const eventID = event.id;
     const url = `${CALENDAR_BASE_URL}/calendars/${encodeURIComponent(config.calendarID)}/events`;
     const response = await fetchFn(url, {
         method: 'POST',
@@ -171,19 +228,34 @@ export async function createEvent(config) {
         body: JSON.stringify(event)
     });
     if (!response.ok) {
-        // A 409 on a caller-supplied id means the event already exists — the create
-        // is already committed, so a retry after a lost response is idempotent: fetch
-        // and return the existing event instead of failing.
-        if (response.status === 409 && config.params.id != null) {
-            return getEvent({
-                accessToken: config.accessToken,
-                calendarID: config.calendarID,
-                eventID: config.params.id,
-                fetch: config.fetch
-            });
+        // A 409 on a caller-chosen id means an event already exists under it. It
+        // is this create's own earlier effect (a retry after a lost response) only
+        // if it holds what this create writes; anything else is a conflict naming
+        // the existing event, for recovery to reconcile — never a success.
+        if (response.status === 409 && eventID != null) {
+            const sourceID = `${config.calendarID}/${eventID}`;
+            let existing;
+            try {
+                existing = await getEvent({
+                    accessToken: config.accessToken,
+                    calendarID: config.calendarID,
+                    eventID,
+                    fetch: config.fetch
+                });
+            } catch (err) {
+                throw eventConflict(sourceID, err);
+            }
+            if (!eventHoldsIntent({
+                op: 'create',
+                intent: config.params,
+                record: existing
+            })) {
+                throw eventConflict(sourceID);
+            }
+            return existing;
         }
         const errorMessage = await parseGoogleError(response);
-        throw new Error(`Google Calendar API error: ${errorMessage}`);
+        throw googleAPIError(response.status, errorMessage);
     }
     const data = await response.json();
     return mapEventToEntity(data, config.calendarID);
@@ -196,13 +268,16 @@ export async function updateEvent(config) {
         method: 'PATCH',
         headers: {
             Authorization: `Bearer ${config.accessToken}`,
-            'Content-Type': 'application/json'
+            'Content-Type': 'application/json',
+            ...config.etag != null ? {
+                'If-Match': config.etag
+            } : {}
         },
         body: JSON.stringify(event)
     });
     if (!response.ok) {
         const errorMessage = await parseGoogleError(response);
-        throw new Error(`Google Calendar API error: ${errorMessage}`);
+        throw googleAPIError(response.status, errorMessage);
     }
     const data = await response.json();
     return mapEventToEntity(data, config.calendarID);

package/lib/connector.js

@@ -1,6 +1,9 @@
 import { createGoogleCalendarActionHandler } from './actions.js';
+import { canonicalizeEventIntent } from './intent.js';
 import { googleCalendarClusters } from './model.js';
+import { predictCreatedEventSourceID } from './predict.js';
 import { createGoogleCalendarProvider } from './provider.js';
+import { resolveCalendarTarget } from './target.js';
 export function createGoogleCalendarConnector(options) {
     return {
         name: 'google-calendar',
@@ -42,7 +45,12 @@ export function createGoogleCalendarConnector(options) {
                         }
                     }
                 },
-                requiresCredential: true
+                requiresCredential: true,
+                // The provider event id is derived from the operation's deterministic
+                // event id (see deriveEventID), so a reissue inserts under the same id
+                // as the original attempt: a create that already landed answers 409
+                // instead of inserting a duplicate — safe to reissue.
+                recoveryClass: 'reissue-safe'
             },
             {
                 name: 'update',
@@ -76,13 +84,29 @@ export function createGoogleCalendarConnector(options) {
                         }
                     }
                 },
-                requiresCredential: true
+                requiresCredential: true,
+                // A sparse PATCH conditioned (If-Match) on the etag of the document
+                // the edit was made against, pinned on the operation at claim. A
+                // reissue after an unknown outcome would meet its own earlier write's
+                // new etag as a 412, and an unconditional one could clobber an
+                // intervening edit, so recovery reconciles (reads current provider
+                // state) rather than reissues.
+                recoveryClass: 'reconcile-only',
+                providerETagField: 'etag',
+                // An edit is only ever written against the version it was made on: an
+                // event with no stored etag (not synced yet) is refused before the
+                // claim rather than written unconditionally over a provider edit.
+                providerETagRequired: true
             }
         ],
+        canonicalizeIntent: canonicalizeEventIntent,
+        resolveActionTarget: resolveCalendarTarget,
+        predictCreatedSourceID: predictCreatedEventSourceID,
         actionHandler: (config)=>{
             return createGoogleCalendarActionHandler({
                 credential: config.credential,
-                fetch: options?.fetch
+                fetch: options?.fetch,
+                mintFetchHLC: config.mintFetchHLC
             });
         },
         auth: {
@@ -98,7 +122,8 @@ export function createGoogleCalendarConnector(options) {
             return createGoogleCalendarProvider({
                 credential: config.credential,
                 boundary: config.boundary,
-                fetch: options?.fetch
+                fetch: options?.fetch,
+                mintFetchHLC: config.mintFetchHLC
             });
         }
     };

package/lib/errors.d.ts

@@ -0,0 +1,32 @@
+import { ConnectorError, type ConnectorErrorOptions } from '@kubun/connector';
+/** A machine-readable failure code fixed for a given Google Calendar failure. */
+export type GoogleCalendarErrorCode = 'GOOGLE_CALENDARS_NOT_SYNCED' | 'GOOGLE_CALENDAR_ID_REQUIRED' | 'GOOGLE_CALENDAR_ID_MISMATCH' | 'CONFLICT';
+export type GoogleCalendarErrorOptions = ConnectorErrorOptions & {
+    code?: GoogleCalendarErrorCode;
+};
+/** A Google Calendar connector failure, classified the way `ConnectorError` is. */
+export declare class GoogleCalendarError extends ConnectorError {
+    constructor(message: string, options?: GoogleCalendarErrorOptions);
+    get code(): GoogleCalendarErrorCode | undefined;
+}
+/**
+ * A create that collided with an existing event it could not confirm as its
+ * own. Outcome-unknown, not a rejection: the event may be this create's own
+ * earlier effect, edited since. `sourceID` lets write-back recovery
+ * reconcile against the event.
+ */
+export declare class GoogleCalendarEventConflict extends GoogleCalendarError {
+    #private;
+    constructor(sourceID: string, options?: ErrorOptions);
+    get sourceID(): string;
+}
+/**
+ * A raw provider HTTP failure from a batch/list round trip (`fetchJSON` in
+ * `provider.ts`), carrying the response status so `fetchChanges` can detect
+ * an expired sync token (410) and fall back to a full resync.
+ */
+export declare class GoogleCalendarAPIError extends Error {
+    #private;
+    constructor(status: number, detail: string);
+    get status(): number;
+}

package/lib/errors.js

@@ -0,0 +1,46 @@
+import { ConnectorError } from '@kubun/connector';
+/** A Google Calendar connector failure, classified the way `ConnectorError` is. */ export class GoogleCalendarError extends ConnectorError {
+    constructor(message, options = {}){
+        super(message, options);
+        this.name = 'GoogleCalendarError';
+    }
+    get code() {
+        return super.code;
+    }
+}
+/**
+ * A create that collided with an existing event it could not confirm as its
+ * own. Outcome-unknown, not a rejection: the event may be this create's own
+ * earlier effect, edited since. `sourceID` lets write-back recovery
+ * reconcile against the event.
+ */ export class GoogleCalendarEventConflict extends GoogleCalendarError {
+    #sourceID;
+    constructor(sourceID, options){
+        super(`Google Calendar API error: an event already exists as "${sourceID}" and does not hold this create`, {
+            ...options,
+            code: 'CONFLICT',
+            httpStatus: 409,
+            kind: 'unknown'
+        });
+        this.name = 'GoogleCalendarEventConflict';
+        this.#sourceID = sourceID;
+    }
+    get sourceID() {
+        return this.#sourceID;
+    }
+}
+/**
+ * A raw provider HTTP failure from a batch/list round trip (`fetchJSON` in
+ * `provider.ts`), carrying the response status so `fetchChanges` can detect
+ * an expired sync token (410) and fall back to a full resync.
+ */ export class GoogleCalendarAPIError extends Error {
+    #status;
+    constructor(status, detail){
+        super(`Google Calendar API error: ${detail}`);
+        this.name = 'GoogleCalendarAPIError';
+        this.#status = status;
+    }
+    get status() {
+        return this.#status;
+    }
+}

package/lib/event-id.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The Google Calendar event id a create inserts under, derived from the
+ * operation's deterministic event id: the lowercase base32hex encoding (no
+ * padding) of a 32-byte digest of it, 52 characters — inside Google's allowed
+ * alphabet (`a-v`, `0-9`) and length (5 to 1024).
+ *
+ * Every attempt of the same operation derives the same id, so a create that is
+ * re-issued after its response was lost collides with its own earlier effect
+ * (a 409) instead of inserting a duplicate event. The mapping is one-way and
+ * versioned: changing it would re-key every create not yet confirmed.
+ */
+export declare function deriveEventID(deterministicEventID: string): string;

package/lib/event-id.js

@@ -0,0 +1,35 @@
+import { digestJSON } from '@kubun/id';
+// Google Calendar event ids use the base32hex alphabet (RFC 4648 §7), lowercase.
+const BASE32HEX = '0123456789abcdefghijklmnopqrstuv';
+function toBase32Hex(bytes) {
+    let out = '';
+    let buffer = 0;
+    let bits = 0;
+    for (const byte of bytes){
+        buffer = buffer << 8 | byte;
+        bits += 8;
+        while(bits >= 5){
+            bits -= 5;
+            out += BASE32HEX[buffer >> bits & 31];
+        }
+        buffer &= (1 << bits) - 1;
+    }
+    if (bits > 0) out += BASE32HEX[buffer << 5 - bits & 31];
+    return out;
+}
+/**
+ * The Google Calendar event id a create inserts under, derived from the
+ * operation's deterministic event id: the lowercase base32hex encoding (no
+ * padding) of a 32-byte digest of it, 52 characters — inside Google's allowed
+ * alphabet (`a-v`, `0-9`) and length (5 to 1024).
+ *
+ * Every attempt of the same operation derives the same id, so a create that is
+ * re-issued after its response was lost collides with its own earlier effect
+ * (a 409) instead of inserting a duplicate event. The mapping is one-way and
+ * versioned: changing it would re-key every create not yet confirmed.
+ */ export function deriveEventID(deterministicEventID) {
+    return toBase32Hex(digestJSON({
+        v: 'gcal-event-id',
+        deterministicEventID
+    }));
+}