@chronicle.app/google 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Louis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# @chronicle.app/google
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Google sign-in for Chronicle's Google sources: Gmail (`chronicle extract gmail`) and Google Calendar (`chronicle extract google-calendar`). Chronicle ships no Google OAuth client. You make one in your own Google Cloud project, once, and `chronicle auth login google` walks you through it.
+
+## Signing in
+
+```sh
+chronicle auth login google
+```
+
+The first time, this sets up your client in three steps:
+
+1. **A Google Cloud project, with the Gmail and Calendar APIs on.** With [gcloud](https://cloud.google.com/sdk/docs/install) installed, Chronicle creates it for you. Without it, you create it in the browser and paste its ID.
+2. **A consent screen**, made External and published. Published, your sign-in lasts; left in testing, Google signs you out after 7 days. Google doesn't review an app only you use, so it stays unverified, and the sign-in page says so. Click Continue (or Advanced, then Go to Chronicle).
+3. **A Desktop app OAuth client.** The window Google shows after you create it has the client ID and secret. Copy each one into the terminal when it asks. (A path to the client's downloaded JSON file works in place of the ID.)
+
+Then you sign in in the browser. The consent page lists each kind of access with its own box, so tick them all.
+
+Each step is saved as it finishes, so you can stop and run the command again later. After that, `chronicle auth login google` goes straight to the sign-in.
+
+### Several accounts
+
+Run `chronicle auth login google` again and sign in with another account. One client works for all your accounts, personal or Workspace. Pick one for a run with `--account`:
+
+```sh
+chronicle extract google-calendar --account you@work.example
+```
+
+Without `--account`, a run uses the account that signed in last. `chronicle auth status google` lists them.
+
+A Workspace admin can block apps their organization hasn't approved from Gmail and Drive. If sign-in says access is blocked, ask them to trust your client ID (Admin console, Security, API controls).
+
+### More access
+
+The first sign-in asks for Gmail and Calendar. `--add` asks for more, keeping what you have, and turns the API on in your project:
+
+```sh
+chronicle auth login google --add drive
+```
+
+### Without the walkthrough
+
+- `--client-file <path>` signs in with a client you downloaded.
+- `--client-id <id> --client-secret <secret>` signs in with a client you already have.
+- `--setup` starts the walkthrough over, with a new project and client.
+
+## What it keeps
+
+- **The client and the setup's progress**: `google/setup.json` in Chronicle's config directory (`~/.config/chronicle`), readable only by you.
+- **Tokens**, one entry per account: Chronicle's `credentials.json`, beside it.
+- **gcloud's sign-in, only while setup runs**: `google/gcloud`, a gcloud configuration of Chronicle's own (`CLOUDSDK_CONFIG`), so your usual gcloud accounts, project, and application default credentials stay as they were. Its sign-in can do far more than Chronicle needs, so when setup is done Chronicle signs out (`gcloud auth revoke`) and removes it. `--add` signs in again just to turn the new API on, then signs out. A setup that stops partway keeps it, so the next run picks up without another sign-in.
+
+### Contacts link people; they aren't extracted
+
+Contacts isn't a source of its own, and it's off unless you ask for it. With `--link-contacts`, Gmail and Calendar read your contacts once a run and look up each address they see: a person on one of your contacts is `sameAs` the contact (`contactIdentities`): an Agent in the `google-contacts` namespace, keyed by the contact's ID within your Google account (`inAccount`), named as you saved it (not the name on the person's own Google profile), and `sameAs` its other addresses (in the `email` namespace) and phone numbers (in the `phone` namespace, E.164), the identities iMessage and call history key people by. Add the access with `chronicle auth login google --add contacts`; without it, a run with `--link-contacts` goes on unlinked and says how to add it.
+
+## For sources
+
+A Google source imports this package, which registers the `google` provider. It reads through `GoogleApi`, with `googleAccountOptions` in its schema:
+
+```ts
+const api = new GoogleApi({ service: 'calendar', baseURL, account, accessToken });
+await api.initialize();
+for await (const item of api.pages('/users/me/calendarList')) …
+```
+
+`GoogleApi` turns Google's refusals into errors that say what to run. A missing scope says to run `chronicle auth login google --add <service>`, an API that's off in the project says the same (which turns it on), and a rejected token says to sign in again. Services, their scopes, and their APIs are listed in `GOOGLE_SERVICES`. `ContactDirectory.load()` reads your contacts for a run when `linkContacts` (from `contactOptions`) is set, `linksFor(addresses)` gives the links for the addresses on a record, and `contactIdentities(address, links)` turns them into `sameAs` identities.
+
+## Tests
+
+The tests run setup against a fake gcloud and a temporary config directory, and Google's API against a server on 127.0.0.1. They never run gcloud or read the host's accounts or files.

package/dist/GoogleApi.d.ts

@@ -0,0 +1,44 @@
+import { type AxiosRequestConfig } from 'axios';
+import { ApiProxy } from '@chronicle.app/etl';
+import { z } from 'zod';
+import { type GoogleService } from './services.js';
+/** The options every Google extractor takes: which account, or a token outright. */
+export declare const googleAccountOptions: {
+    account: z.ZodOptional<z.ZodString>;
+    accessToken: z.ZodOptional<z.ZodString>;
+};
+export interface GoogleApiOptions {
+    /** Which service this client reads, for the scope and API in its errors. */
+    service: GoogleService;
+    baseURL: string;
+    account?: string;
+    accessToken?: string;
+    pageDelayMs?: number;
+    /** Waits before each retry of a rate-limited request, in ms. */
+    retryDelaysMs?: number[];
+}
+/**
+ * A Google REST API, signed in as one account. Google's refusals become
+ * typed errors that say what to run: a missing scope adds access, an API
+ * that's off gets turned on, an expired sign-in signs in again.
+ */
+export declare class GoogleApi extends ApiProxy {
+    private readonly service;
+    private readonly account?;
+    private readonly retryDelaysMs;
+    constructor(options: GoogleApiOptions);
+    /** The token came from a stored sign-in, so it can be refreshed. */
+    private readonly stored;
+    initialize(): Promise<void>;
+    get<T>(path: string, params?: Record<string, unknown>): Promise<T>;
+    /** Every item of a list endpoint, page by page, following `nextPageToken`. */
+    pages<T>(path: string, params?: Record<string, unknown>, itemsKey?: string): AsyncGenerator<T>;
+    /**
+     * A request, retried with backoff while Google says it's rate limited, and
+     * once with a refreshed token when Google refuses one that expired during
+     * a long run.
+     */
+    protected request<T>(config: AxiosRequestConfig): Promise<T>;
+    protected mapError(error: unknown): unknown;
+}
+//# sourceMappingURL=GoogleApi.d.ts.map

package/dist/GoogleApi.js

@@ -0,0 +1,171 @@
+import { isAxiosError } from 'axios';
+import { ApiAuthError, ApiProxy } from '@chronicle.app/etl';
+import { TokenHelper } from '@chronicle.app/auth';
+import { AuthRequired, EXIT_CODES, ExtractorError, RateLimited } from '@chronicle.app/logging';
+import { z } from 'zod';
+import { GOOGLE_SERVICES } from './services.js';
+/** The options every Google extractor takes: which account, or a token outright. */
+export const googleAccountOptions = {
+    account: z
+        .string()
+        .optional()
+        .describe('The Google account to use, by email. The default is the last one signed in.'),
+    accessToken: z
+        .string()
+        .optional()
+        .describe('A Google access token to use instead of a stored sign-in'),
+};
+/**
+ * Google's per-minute quotas refill within a minute: back off for about that
+ * long, doubling, before giving up.
+ */
+const RETRY_DELAYS_MS = [2000, 4000, 8000, 16_000, 32_000];
+/** Google's reasons for a rate limit, as a 403 or a 429. */
+const RATE_LIMITED = new Set([
+    'rateLimitExceeded',
+    'userRateLimitExceeded',
+    'RATE_LIMIT_EXCEEDED',
+    'quotaExceeded',
+]);
+/**
+ * A Google REST API, signed in as one account. Google's refusals become
+ * typed errors that say what to run: a missing scope adds access, an API
+ * that's off gets turned on, an expired sign-in signs in again.
+ */
+export class GoogleApi extends ApiProxy {
+    service;
+    account;
+    retryDelaysMs;
+    constructor(options) {
+        super({ baseURL: options.baseURL, pageDelayMs: options.pageDelayMs ?? 0 });
+        this.service = options.service;
+        this.account = options.account;
+        this.retryDelaysMs = options.retryDelaysMs ?? RETRY_DELAYS_MS;
+        if (options.accessToken)
+            this.setAccessToken(options.accessToken);
+        this.stored = !options.accessToken;
+    }
+    /** The token came from a stored sign-in, so it can be refreshed. */
+    stored;
+    async initialize() {
+        if (this.accessToken)
+            return;
+        this.setAccessToken(await TokenHelper.getValidToken('google', { account: this.account }));
+    }
+    get(path, params) {
+        // Google wants a list as the same name repeated (`labelIds=A&labelIds=B`).
+        return this.request({
+            method: 'GET',
+            url: path,
+            params,
+            paramsSerializer: { indexes: null },
+        });
+    }
+    /** Every item of a list endpoint, page by page, following `nextPageToken`. */
+    async *pages(path, params = {}, itemsKey = 'items') {
+        let pageToken;
+        do {
+            const page = await this.get(path, { ...params, pageToken });
+            yield* (page[itemsKey] ?? []);
+            pageToken = page.nextPageToken;
+            if (pageToken)
+                await this.delay();
+        } while (pageToken);
+    }
+    /**
+     * A request, retried with backoff while Google says it's rate limited, and
+     * once with a refreshed token when Google refuses one that expired during
+     * a long run.
+     */
+    async request(config) {
+        let refreshed = false;
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await super.request(config);
+            }
+            catch (error) {
+                if (error instanceof ApiAuthError && this.stored && !refreshed) {
+                    refreshed = true;
+                    this.setAccessToken(await TokenHelper.getValidToken('google', { account: this.account, refresh: true }));
+                    continue;
+                }
+                if (!(error instanceof RateLimited) || attempt >= this.retryDelaysMs.length)
+                    throw error;
+                await this.delay(this.retryDelaysMs[attempt]);
+            }
+        }
+    }
+    mapError(error) {
+        const { label } = GOOGLE_SERVICES[this.service];
+        const reasons = isAxiosError(error) ? googleReasons(error.response?.data) : new Set();
+        if ([...reasons].some(reason => RATE_LIMITED.has(reason))) {
+            return new RateLimited(`Google’s ${label} quota is used up for now`, {
+                hint: 'Try again in a minute.',
+            });
+        }
+        if (isAxiosError(error) && error.response?.status === 403) {
+            if (reasons.has('ACCESS_TOKEN_SCOPE_INSUFFICIENT') ||
+                reasons.has('insufficientPermissions')) {
+                return new AuthRequired(`No access to ${label}`, {
+                    hint: `Run \`chronicle auth login google --add ${this.service}\` to add it.`,
+                });
+            }
+            if (reasons.has('SERVICE_DISABLED') || reasons.has('accessNotConfigured')) {
+                // Google says where to turn it on; that page is the quickest way.
+                const page = activationUrl(error.response.data);
+                return new ExtractorError(`The ${label} API is off in your Google Cloud project`, {
+                    code: 'api-disabled',
+                    exitCode: EXIT_CODES.auth,
+                    hint: page
+                        ? `Turn it on here, then run this again: ${page}\nOr run \`chronicle auth login google --add ${this.service}\` to turn it on.`
+                        : `Run \`chronicle auth login google --add ${this.service}\` to turn it on.`,
+                });
+            }
+        }
+        if (isAxiosError(error) && error.response?.status === 404) {
+            return new ExtractorError(`${label}: not found`, {
+                code: 'not-found',
+                exitCode: EXIT_CODES.input,
+                cause: error,
+            });
+        }
+        const mapped = super.mapError(error);
+        if (mapped instanceof ApiAuthError) {
+            return new ApiAuthError('Google rejected the stored sign-in', {
+                hint: 'Run `chronicle auth login google` to sign in again.',
+            });
+        }
+        // Anything else: Google's own words, not just the status code.
+        const said = isAxiosError(error) && googleMessage(error.response?.data);
+        if (said && mapped === error) {
+            return new ExtractorError(`${label}: ${said}`, {
+                code: 'api-error',
+                exitCode: EXIT_CODES.internal,
+                cause: error,
+            });
+        }
+        return mapped;
+    }
+}
+/** The reasons in a Google error body, from either of its two shapes. */
+function googleReasons(body) {
+    const error = body?.error ?? {};
+    return new Set([
+        ...(error.errors ?? []).map((e) => e?.reason),
+        ...(error.details ?? []).map((d) => d?.reason),
+    ].filter((reason) => typeof reason === 'string'));
+}
+/** The message in a Google error body, if it has one. */
+function googleMessage(body) {
+    const message = body?.error?.message;
+    return typeof message === 'string' && message ? message : undefined;
+}
+/** The page that turns an API on, from a Google "service disabled" error. */
+function activationUrl(body) {
+    for (const detail of body?.error?.details ?? []) {
+        const url = detail?.metadata?.activationUrl;
+        if (typeof url === 'string')
+            return url;
+    }
+    return body?.error?.message?.match(/https:\/\/console\.developers\.google\.com\/\S+?(?=\s|$)/)?.[0];
+}

package/dist/GoogleOAuthProvider.d.ts

@@ -0,0 +1,26 @@
+import { OAuthProvider, type ProviderSetupContext } from '@chronicle.app/auth';
+/**
+ * One Google sign-in for every Google source, with an OAuth client the person
+ * registers in their own Google Cloud project: Chronicle ships no client.
+ * Each account signed in is kept apart by its email.
+ */
+export declare class GoogleOAuthProvider extends OAuthProvider {
+    static providerId: string;
+    static authorizationUrl: string;
+    static tokenUrl: string;
+    static scopes: string[];
+    static scopeSets: Record<string, string[]>;
+    static defaultScopeSets: string[];
+    static requiresClientSecret: boolean;
+    static pkce: boolean;
+    static extraAuthParams: {
+        access_type: string;
+        prompt: string;
+        include_granted_scopes: string;
+    };
+    static signedInHint: string;
+    static setup(context: ProviderSetupContext): Promise<import("@chronicle.app/auth").ClientCredentials>;
+    /** The email in the id_token, which came straight from Google's token endpoint. */
+    protected accountFrom(response: any): string | undefined;
+}
+//# sourceMappingURL=GoogleOAuthProvider.d.ts.map

package/dist/GoogleOAuthProvider.js

@@ -0,0 +1,47 @@
+import { OAuthProvider } from '@chronicle.app/auth';
+import { GOOGLE_SERVICES } from './services.js';
+import { setupGoogleClient } from './setup.js';
+/**
+ * One Google sign-in for every Google source, with an OAuth client the person
+ * registers in their own Google Cloud project: Chronicle ships no client.
+ * Each account signed in is kept apart by its email.
+ */
+export class GoogleOAuthProvider extends OAuthProvider {
+    static providerId = 'google';
+    static authorizationUrl = 'https://accounts.google.com/o/oauth2/v2/auth';
+    static tokenUrl = 'https://oauth2.googleapis.com/token';
+    // `openid email` brings back an id_token naming the account.
+    static scopes = ['openid', 'email'];
+    static scopeSets = Object.fromEntries(Object.entries(GOOGLE_SERVICES).map(([name, service]) => [name, [...service.scopes]]));
+    static defaultScopeSets = ['gmail', 'calendar'];
+    static requiresClientSecret = true;
+    static pkce = true;
+    // Without offline access + forced consent Google issues no refresh token,
+    // leaving the stored credential unable to outlive the first hour.
+    // include_granted_scopes keeps what was granted before when access is added.
+    static extraAuthParams = {
+        access_type: 'offline',
+        prompt: 'consent',
+        include_granted_scopes: 'true',
+    };
+    static signedInHint = [
+        'Run `chronicle extract google-calendar` to extract your calendar.',
+        'Run `chronicle extract gmail` to extract your mail.',
+    ].join('\n');
+    static setup(context) {
+        return setupGoogleClient(context);
+    }
+    /** The email in the id_token, which came straight from Google's token endpoint. */
+    accountFrom(response) {
+        const payload = response?.id_token?.split('.')[1];
+        if (!payload)
+            return undefined;
+        try {
+            const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf-8'));
+            return typeof claims.email === 'string' ? claims.email : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}

package/dist/account.d.ts

@@ -0,0 +1,9 @@
+import type { Agent } from '@chronicle.app/schema';
+/**
+ * A Google account by its address, in the `google-account` namespace, so
+ * Gmail, Google Calendar, and Chrome name the same account the same way. An
+ * address is the one identifier every way in has: an API, a Takeout, or a
+ * browser profile. The source's node for you is `sameAs` it.
+ */
+export declare function googleAccount(address: string): Agent;
+//# sourceMappingURL=account.d.ts.map

package/dist/account.js

@@ -0,0 +1,14 @@
+/**
+ * A Google account by its address, in the `google-account` namespace, so
+ * Gmail, Google Calendar, and Chrome name the same account the same way. An
+ * address is the one identifier every way in has: an API, a Takeout, or a
+ * browser profile. The source's node for you is `sameAs` it.
+ */
+export function googleAccount(address) {
+    return {
+        '@type': 'Agent',
+        '@key': ['@type', 'source', 'handle'],
+        source: 'google-account',
+        handle: address.toLowerCase(),
+    };
+}

package/dist/contacts.d.ts

@@ -0,0 +1,59 @@
+import type { Agent } from '@chronicle.app/schema';
+import { z } from 'zod';
+/**
+ * What your contacts say about an email address: the contact's other
+ * addresses, lowercased, and its phone numbers, in E.164. Plain data, so it
+ * rides a raw record.
+ */
+export interface ContactLinks {
+    /** The contact's ID in the account's contacts, from its `people/<id>` name. */
+    id: string;
+    /** The name you saved for the contact, not the person's own profile name. */
+    name?: string;
+    emails: string[];
+    phones: string[];
+}
+/** The option a Google source takes to link people to your contacts. Off unless asked for. */
+export declare const contactOptions: {
+    linkContacts: z.ZodOptional<z.ZodBoolean>;
+};
+/**
+ * Your Google Contacts as a lookup, not a source: Gmail and Calendar ask it
+ * about each address they see, and link the person to the contact's other
+ * addresses and numbers. Nothing from it is extracted on its own.
+ */
+export declare class ContactDirectory {
+    private readonly byAddress;
+    /** Swapped for a fake server in tests. */
+    static apiBaseURL: string;
+    private constructor();
+    /** A directory with no contacts in it, for a run without Contacts access. */
+    static readonly empty: ContactDirectory;
+    /**
+     * Your contacts, read once for a run with `linkContacts`. Without Contacts
+     * access, or with the People API off, it's empty and says why: linking is
+     * a bonus, so the run goes on.
+     */
+    static load(options: {
+        account?: string;
+        accessToken?: string;
+        linkContacts?: boolean;
+    }): Promise<{
+        directory: ContactDirectory;
+        missing?: unknown;
+    }>;
+    /** The links for each of these addresses that's on a contact. */
+    linksFor(addresses: string[]): {
+        [address: string]: ContactLinks;
+    };
+}
+/**
+ * Your contact for an address, as the identity it links the address to: the
+ * entry in the Google account's contacts, keyed by its ID within the account,
+ * named as you saved it, and `sameAs` its other addresses in the `email`
+ * namespace and its numbers in the `phone` namespace, keyed as mail,
+ * messages, and calls key people. None without the account whose contacts
+ * they are.
+ */
+export declare function contactIdentities(address: string, links: ContactLinks | undefined, account: string | null | undefined): Agent[];
+//# sourceMappingURL=contacts.d.ts.map

package/dist/contacts.js

@@ -0,0 +1,119 @@
+import { normalizePhoneNumber } from '@chronicle.app/etl';
+import { z } from 'zod';
+import { googleAccount } from './account.js';
+import { GoogleApi } from './GoogleApi.js';
+/** The option a Google source takes to link people to your contacts. Off unless asked for. */
+export const contactOptions = {
+    linkContacts: z
+        .boolean()
+        .optional()
+        .describe('Link people to the other addresses and phone numbers your Google Contacts have for them'),
+};
+/**
+ * Your Google Contacts as a lookup, not a source: Gmail and Calendar ask it
+ * about each address they see, and link the person to the contact's other
+ * addresses and numbers. Nothing from it is extracted on its own.
+ */
+export class ContactDirectory {
+    byAddress;
+    /** Swapped for a fake server in tests. */
+    static apiBaseURL = 'https://people.googleapis.com/v1';
+    constructor(byAddress) {
+        this.byAddress = byAddress;
+    }
+    /** A directory with no contacts in it, for a run without Contacts access. */
+    static empty = new ContactDirectory(new Map());
+    /**
+     * Your contacts, read once for a run with `linkContacts`. Without Contacts
+     * access, or with the People API off, it's empty and says why: linking is
+     * a bonus, so the run goes on.
+     */
+    static async load(options) {
+        // Not asked for: your address book isn't read at all.
+        if (!options.linkContacts)
+            return { directory: ContactDirectory.empty };
+        const api = new GoogleApi({
+            service: 'contacts',
+            baseURL: ContactDirectory.apiBaseURL,
+            account: options.account,
+            accessToken: options.accessToken,
+        });
+        const byAddress = new Map();
+        try {
+            await api.initialize();
+            const people = api.pages('/people/me/connections', { personFields: 'names,emailAddresses,phoneNumbers', pageSize: 1000 }, 'connections');
+            for await (const person of people) {
+                const emails = unique((person.emailAddresses ?? []).map(email => email.value?.trim().toLowerCase()));
+                const phones = unique((person.phoneNumbers ?? []).map(phone => phone.canonicalForm ?? (phone.value ? normalizePhoneNumber(phone.value) : null)));
+                const id = person.resourceName?.replace(/^people\//, '');
+                // A contact is found by its addresses, so one without any can't be.
+                if (!id || emails.length === 0)
+                    continue;
+                // The name you saved (a CONTACT source), not the one the person gave
+                // their own Google profile (a PROFILE source).
+                const name = person.names
+                    ?.find(entry => entry.metadata?.source?.type === 'CONTACT')
+                    ?.displayName?.trim();
+                for (const email of emails) {
+                    byAddress.set(email, { id, ...(name && { name }), emails, phones });
+                }
+            }
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code === 'auth-required' || code === 'api-disabled') {
+                return { directory: ContactDirectory.empty, missing: error };
+            }
+            throw error;
+        }
+        return { directory: new ContactDirectory(byAddress) };
+    }
+    /** The links for each of these addresses that's on a contact. */
+    linksFor(addresses) {
+        const found = {};
+        for (const address of addresses) {
+            const key = address.toLowerCase();
+            const links = this.byAddress.get(key);
+            if (links)
+                found[key] = links;
+        }
+        return found;
+    }
+}
+/**
+ * Your contact for an address, as the identity it links the address to: the
+ * entry in the Google account's contacts, keyed by its ID within the account,
+ * named as you saved it, and `sameAs` its other addresses in the `email`
+ * namespace and its numbers in the `phone` namespace, keyed as mail,
+ * messages, and calls key people. None without the account whose contacts
+ * they are.
+ */
+export function contactIdentities(address, links, account) {
+    if (!links || !account)
+        return [];
+    const self = address.toLowerCase();
+    const identity = (source, handle) => ({
+        '@type': 'Agent',
+        '@key': ['@type', 'source', 'handle'],
+        source,
+        handle,
+    });
+    const sameAs = [
+        ...links.emails.filter(email => email !== self).map(email => identity('email', email)),
+        ...links.phones.map(phone => identity('phone', phone)),
+    ];
+    return [
+        {
+            '@type': 'Agent',
+            '@key': ['@type', 'source', 'inAccount[*].handle', 'sourceId'],
+            source: 'google-contacts',
+            sourceId: links.id,
+            inAccount: [googleAccount(account)],
+            ...(links.name && { name: links.name }),
+            ...(sameAs.length > 0 && { sameAs }),
+        },
+    ];
+}
+const unique = (values) => [
+    ...new Set(values.flatMap(value => (value ? [value] : []))),
+];

package/dist/gcloud.d.ts

@@ -0,0 +1,49 @@
+/** What setup needs from Google Cloud's command line. */
+export interface Gcloud {
+    /** Whether `gcloud` is installed. */
+    available(): Promise<boolean>;
+    /** The signed-in account, if any. */
+    account(): Promise<string | undefined>;
+    /** Sign in; gcloud opens the browser and talks to the terminal itself. */
+    login(): Promise<void>;
+    createProject(projectId: string, name: string): Promise<void>;
+    /** IDs of the projects the signed-in account can see. */
+    listProjects(): Promise<string[]>;
+    enableApis(projectId: string, apis: string[]): Promise<void>;
+    /** Sign out and remove gcloud's state: its sign-in can do far more than setup needs. */
+    signOut(): Promise<void>;
+}
+/** A gcloud command that failed, with what it said. */
+export declare class GcloudError extends Error {
+    readonly args: string[];
+    readonly stderr: string;
+    /** gcloud's error, unwrapped into one line, without its `ERROR: (gcloud.…)` prefix. */
+    readonly said: string;
+    constructor(args: string[], stderr: string);
+}
+/**
+ * The error in gcloud's output: from its `ERROR:` line to the next blank
+ * line, which gcloud wraps at 80 columns, as one line. Anything else it
+ * printed (update notices) is left out.
+ */
+export declare function gcloudSaid(stderr: string): string;
+/**
+ * gcloud with its own config directory (`CLOUDSDK_CONFIG`), so the account
+ * and project Chronicle sets up never touch a person's everyday gcloud: its
+ * accounts, active project, and application default credentials stay as
+ * they were. Commands run with argument arrays, never through a shell.
+ */
+export declare class CommandLineGcloud implements Gcloud {
+    private readonly configDir;
+    private readonly bin;
+    constructor(configDir: string, bin?: string);
+    available(): Promise<boolean>;
+    account(): Promise<string | undefined>;
+    login(): Promise<void>;
+    createProject(projectId: string, name: string): Promise<void>;
+    listProjects(): Promise<string[]>;
+    enableApis(projectId: string, apis: string[]): Promise<void>;
+    signOut(): Promise<void>;
+    private run;
+}
+//# sourceMappingURL=gcloud.d.ts.map