@zapier/google-contacts-connector 0.0.0 → 0.1.1

package/index.ts

@@ -0,0 +1,64 @@
+import { defineConnector, toFunctions } from "@zapier/connectors-sdk";
+
+import { connectionResolvers } from "./connections.ts";
+import copyOtherContactDefinition from "./scripts/copyOtherContact.ts";
+import createContactDefinition from "./scripts/createContact.ts";
+import createContactGroupDefinition from "./scripts/createContactGroup.ts";
+import deleteContactDefinition from "./scripts/deleteContact.ts";
+import deleteContactGroupDefinition from "./scripts/deleteContactGroup.ts";
+import deleteContactPhotoDefinition from "./scripts/deleteContactPhoto.ts";
+import getContactDefinition from "./scripts/getContact.ts";
+import getContactGroupDefinition from "./scripts/getContactGroup.ts";
+import listContactGroupsDefinition from "./scripts/listContactGroups.ts";
+import listContactsDefinition from "./scripts/listContacts.ts";
+import listOtherContactsDefinition from "./scripts/listOtherContacts.ts";
+import modifyContactGroupMembersDefinition from "./scripts/modifyContactGroupMembers.ts";
+import searchContactsDefinition from "./scripts/searchContacts.ts";
+import searchOtherContactsDefinition from "./scripts/searchOtherContacts.ts";
+import updateContactDefinition from "./scripts/updateContact.ts";
+import updateContactGroupDefinition from "./scripts/updateContactGroup.ts";
+import updateContactPhotoDefinition from "./scripts/updateContactPhoto.ts";
+
+const connector = defineConnector({
+  scripts: {
+    copyOtherContact: copyOtherContactDefinition,
+    createContact: createContactDefinition,
+    createContactGroup: createContactGroupDefinition,
+    deleteContact: deleteContactDefinition,
+    deleteContactGroup: deleteContactGroupDefinition,
+    deleteContactPhoto: deleteContactPhotoDefinition,
+    getContact: getContactDefinition,
+    getContactGroup: getContactGroupDefinition,
+    listContactGroups: listContactGroupsDefinition,
+    listContacts: listContactsDefinition,
+    listOtherContacts: listOtherContactsDefinition,
+    modifyContactGroupMembers: modifyContactGroupMembersDefinition,
+    searchContacts: searchContactsDefinition,
+    searchOtherContacts: searchOtherContactsDefinition,
+    updateContact: updateContactDefinition,
+    updateContactGroup: updateContactGroupDefinition,
+    updateContactPhoto: updateContactPhotoDefinition,
+  },
+  connectionResolvers,
+});
+
+export default connector;
+export const {
+  copyOtherContact,
+  createContact,
+  createContactGroup,
+  deleteContact,
+  deleteContactGroup,
+  deleteContactPhoto,
+  getContact,
+  getContactGroup,
+  listContactGroups,
+  listContacts,
+  listOtherContacts,
+  modifyContactGroupMembers,
+  searchContacts,
+  searchOtherContacts,
+  updateContact,
+  updateContactGroup,
+  updateContactPhoto,
+} = toFunctions(connector);

package/package.json

@@ -1,7 +1,62 @@
 {
   "name": "@zapier/google-contacts-connector",
-  "version": "0.0.0",
-  "description": "Placeholder published to enable OIDC Trusted Publisher setup. The real package is published via GitLab CI.",
+  "description": "Agent-callable Google Contacts tools — create, find, update, and delete contacts, manage contact groups (labels) and membership, and read auto-saved other contacts. Use when the user mentions Google Contacts or wants to look up, save, or organize people — including requests that don't name Google Contacts explicitly, e.g. add Jane to my contacts, find Bob's email.",
   "license": "Elastic-2.0",
-  "private": false
-}
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./index.ts"
+    }
+  },
+  "bin": {
+    "@zapier/google-contacts-connector": "./cli.js"
+  },
+  "files": [
+    "dist/",
+    "cli.js",
+    "*.ts",
+    "scripts/",
+    "preflight.sh",
+    "SKILL.md",
+    "README.md",
+    "LICENSE",
+    "references/",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@zapier/connectors-sdk": "^0.2.0",
+    "zod": "^4.0.0",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@zapier/zapier-sdk": ">=0.59.0 <1.0.0"
+  },
+  "keywords": [
+    "google-contacts",
+    "zapier",
+    "connector",
+    "tools",
+    "skills",
+    "mcp",
+    "agent",
+    "ai",
+    "automation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zapier/connectors.git",
+    "directory": "apps/google-contacts"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "version": "0.1.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}

package/preflight.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env sh
+# Connector pre-flight readiness check.
+#
+# Managed by @zapier/connectors-dev — do not edit; synced byte-for-byte
+# across every connector.
+#
+# Runs inside whatever agent harness installed the connector (Cursor, Claude
+# Code, Codex, Gemini CLI, Goose, ...) — often a minimal container — and answers
+# ONE question: how do I run the TypeScript scripts here? It picks a runtime —
+# Node 22.18+ when it can already resolve the connector's deps, else an explicit
+# install step (`npm install`, or `bun install` when only Bun is present) — and
+# tells the agent the exact command to run (see EXIT CODES). When deps are
+# missing it disambiguates the two sandbox failures that block an install: a
+# read-only connector dir (must run unsandboxed / be granted write) vs. a
+# blocked home dir (point the package cache inside this dir). Both surface as a
+# misleading `EPERM`, so the recommendation names the actual fix.
+#
+# NEEDS_ACTION is a single self-verifying step (install a runtime / deps), not a
+# loop: do it, then run a script. The action confirms its own success and the
+# first `--help` run is the authoritative check, so re-running this pre-flight to
+# reconfirm is optional, not required.
+#
+# THE AGENT CONTRACT IS THE STDOUT, NOT THIS HEADER. Agents don't read this file;
+# they run it and parse the `PREFLIGHT_*` lines — each value starts with a stable
+# token (parse as `KEY: (\w+)`), with an optional human gloss in parens, and
+# `PREFLIGHT_RECOMMENDATION` is the one-line next step. SKILL.md "Step 0" is the
+# agent-facing spec; this header is for maintainers of the canonical script.
+#
+# WHY POSIX sh (not bash)
+#   Minimal sandboxes often ship only BusyBox `sh` with no bash. This script runs
+#   unchanged under BusyBox sh, dash, and bash, and never hard-requires
+#   node/bun/npm — a missing runtime degrades to a NEEDS_ACTION instruction.
+#
+# EXIT CODES (the verdict; also emitted on PREFLIGHT_STATUS)
+#   0  READY         a runtime + deps are in place; run the scripts
+#   1  NEEDS_ACTION  perform the printed action (install runtime / deps), then
+#                    run a script — re-running this check is optional
+
+set -u
+
+EXIT_READY=0
+EXIT_NEEDS_ACTION=1
+
+# Directory this script lives in — deps + scripts are resolved relative to it,
+# not the caller's cwd, so `./preflight.sh` works from anywhere.
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+
+has() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+# Node >= 22.18 is the connector baseline (native .ts stripping). Anything older
+# is treated as "no Node" so we fall back to Bun.
+node_ge_2218() {
+  has node || return 1
+  v=$(node -v 2>/dev/null) || return 1
+  v=${v#v}
+  major=${v%%.*}
+  rest=${v#*.}
+  minor=${rest%%.*}
+  case "$major" in '' | *[!0-9]*) return 1 ;; esac
+  case "$minor" in '' | *[!0-9]*) minor=0 ;; esac
+  [ "$major" -gt 22 ] && return 0
+  [ "$major" -eq 22 ] && [ "$minor" -ge 18 ] && return 0
+  return 1
+}
+
+# Are the connector's declared deps installed where Node would find them? Node
+# won't fetch — they must be on disk (this dir's node_modules or an ancestor's).
+# Reads the connector's own package.json, so this stays connector-agnostic. A
+# bare `[ -d node_modules ]` is the wrong test: under pnpm/monorepo layouts the
+# deps can live in an ancestor (or be hoisted), and a local node_modules can
+# exist without the package being present. We check each dep's package.json
+# exists in one of Node's resolution paths rather than `require.resolve(name)`,
+# because resolving the package ENTRY can fail for ESM-only / `exports`-map
+# packages even when they're fully installed and importable.
+node_resolves() {
+  ( CDPATH= cd -- "$SCRIPT_DIR" && node -e 'const fs=require("fs"),path=require("path");const d=require("./package.json").dependencies||{};for(const k of Object.keys(d)){const ps=require.resolve.paths(k)||[];if(!ps.some(b=>fs.existsSync(path.join(b,k,"package.json"))))process.exit(1);}' ) >/dev/null 2>&1
+}
+
+# Can we actually WRITE into this directory right now? Any dep install must land
+# `node_modules/` here, so if the harness mounts the connector read-only (common
+# when skills live under ~/.<agent>/skills, outside the agent's writable
+# workspace) no install can succeed in place — the only fixes are to run it
+# unsandboxed or grant write access. Two deliberate choices:
+#   - Probe with a real create+remove, not `[ -w ]`: a sandbox denies the write
+#     at the syscall while the permission bits still look writable.
+#   - Probe by creating a DIRECTORY (`mkdir`), not a file: that's the install's
+#     very first on-disk action (node_modules/ and the cache dirs), and at least
+#     one sandbox (Claude Code) permits creating a file here while denying
+#     `mkdir` — a file-based probe reports writable and the install then EPERMs.
+dir_writable() {
+  _t="$SCRIPT_DIR/.preflight-write-test.$$"
+  mkdir "$_t" 2>/dev/null || return 1
+  rmdir "$_t" 2>/dev/null
+  return 0
+}
+
+# ---- 1) Pick a runtime -----------------------------------------------------
+# Node 22.18+ (native TS strip) is the baseline and the preferred runner whenever
+# it's present — it runs the .ts scripts directly. Bun is the fallback runner
+# only when there's no usable Node. We DON'T lean on Bun's implicit auto-install:
+# it's silently suppressed by any ancestor node_modules (monorepo layouts) and
+# fails the same way Node's `npm install` does under a sandbox that blocks Bun's
+# home cache — so missing deps are always an explicit, cache-local install step.
+nresolves=false
+node_ge_2218 && node_resolves && nresolves=true
+
+if [ "$nresolves" = true ]; then
+  runner=node
+  ready=true
+elif node_ge_2218; then
+  runner=node # present but deps unresolved — install step below
+  ready=false
+elif has bun; then
+  runner=bun # no usable Node — Bun runs the scripts; install step below
+  ready=false
+else
+  echo "PREFLIGHT_STATUS: NEEDS_ACTION"
+  echo "PREFLIGHT_RECOMMENDATION: no Node 22.18+ or Bun found — install Node 22.18+ (ships npm) or Bun, then run \`<runner> ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials."
+  exit "$EXIT_NEEDS_ACTION"
+fi
+
+# ---- 2) Install deps if the chosen runtime can't run as-is -----------------
+# Two distinct sandbox failures to disambiguate, because their fixes differ:
+#   a) This directory is READ-ONLY (skills installed outside the agent's
+#      writable workspace). No install can place node_modules here — the agent
+#      must run it unsandboxed or be granted write access. A cache flag can't
+#      help.
+#   b) The directory is writable but the HOME dir is sandboxed, so the default
+#      ~/.npm / ~/.bun cache write is what EPERMs mid-install. Pointing the cache
+#      INSIDE this directory sidesteps that without disabling the sandbox (and is
+#      harmless otherwise — just an unused cache dir).
+# So probe writability first and recommend accordingly.
+if [ "$ready" != true ]; then
+  echo "PREFLIGHT_STATUS: NEEDS_ACTION"
+  [ "$runner" = bun ] && install_cmd="bun install" || install_cmd="npm install"
+  if ! dir_writable; then
+    echo "PREFLIGHT_RECOMMENDATION: dependencies are not installed and ${SCRIPT_DIR} is read-only in the current sandbox (a test write there failed) — \`${install_cmd}\` can't place node_modules here. Run the install with the sandbox disabled, or grant the agent write access to ${SCRIPT_DIR} (a cache flag won't help — node_modules must land in this directory); then run \`${runner} ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials."
+  elif [ "$runner" = bun ]; then
+    echo "PREFLIGHT_RECOMMENDATION: dependencies are not installed — run \`BUN_INSTALL_CACHE_DIR=\"${SCRIPT_DIR}/.bun-cache\" bun install\` in ${SCRIPT_DIR} (the workspace-local cache survives a sandbox that blocks ~/.bun; plain \`bun install\` works otherwise), then run \`${runner} ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials."
+  elif has npm; then
+    echo "PREFLIGHT_RECOMMENDATION: dependencies are not installed — run \`npm install --cache \"${SCRIPT_DIR}/.npm-cache\"\` in ${SCRIPT_DIR} (the workspace-local --cache survives a sandbox that blocks ~/.npm; plain \`npm install\` works otherwise), then run \`${runner} ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials."
+  else
+    # node >= 22.18 ships npm, so a missing npm means it was removed from the
+    # Node install. Restore it, then install with a workspace-local cache.
+    echo "PREFLIGHT_RECOMMENDATION: npm is missing (it ships with Node 22.18+) — reinstall/repair Node 22.18+, run \`npm install --cache \"${SCRIPT_DIR}/.npm-cache\"\` in ${SCRIPT_DIR}, then run \`${runner} ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials."
+  fi
+  exit "$EXIT_NEEDS_ACTION"
+fi
+
+# ---- 3) Ready --------------------------------------------------------------
+# Runtime + deps are in place — the scripts run.
+echo "PREFLIGHT_STATUS: READY"
+echo "PREFLIGHT_RUNNER: ${runner}"
+echo "PREFLIGHT_RECOMMENDATION: run \`${runner} ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials, then run the script with the required env vars set."
+exit "$EXIT_READY"

package/references/google-contacts-api-gotchas.md

@@ -0,0 +1,181 @@
+# Google Contacts (People API) — API gotchas
+
+Agent-facing reference for non-obvious Google People API behaviors.
+Every claim below is sourced from public Google documentation.
+
+## Error envelope
+
+The People API returns errors as `{ error: { code, message, status } }` where
+`status` is a [canonical Google status string](https://developers.google.com/people/api/rest/v1/people/updateContact).
+Key mappings an agent should recognize:
+
+| HTTP | status string         | Meaning / recovery                                                                                                                                                                                                                                                                                                                                   |
+| ---- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 401  | `UNAUTHENTICATED`     | Credentials expired or revoked — reconnect.                                                                                                                                                                                                                                                                                                          |
+| 429  | `RESOURCE_EXHAUSTED`  | Quota or rate limit hit. The People API tracks per-operation quota costs: a single create or update costs 1 critical read + 1 critical write + 1 daily contact write; batch operations cost more ([quota table](https://developers.google.com/people/v1/contacts)). Back off with exponential jitter.                                                |
+| 403  | `PERMISSION_DENIED`   | OAuth scope too narrow — reconnect. Writes require the `contacts` scope; other-contacts reads require `contacts.other.readonly` ([otherContacts.list](https://developers.google.com/people/api/rest/v1/otherContacts/list)).                                                                                                                         |
+| 400  | `FAILED_PRECONDITION` | Stale etag — "The server returns a 400 error with reason `failedPrecondition` if `person.metadata.sources.etag` is different than the contact's etag, which indicates the contact has changed since its data was read" ([updateContact](https://developers.google.com/people/api/rest/v1/people/updateContact)). Re-fetch with getContact and retry. |
+| 400  | `INVALID_ARGUMENT`    | Malformed request. Common cause: sending more than one value on a singleton field — "The server returns a 400 error if more than one field is specified on a field that is a singleton for contact sources: biographies, birthdays, genders, names" ([updateContact](https://developers.google.com/people/api/rest/v1/people/updateContact)).        |
+| 404  | `NOT_FOUND`           | Resource does not exist. Verify the `resourceName`.                                                                                                                                                                                                                                                                                                  |
+| 409  | `ALREADY_EXISTS`      | Duplicate contact group name — "Attempting to create a group with a duplicate name will return a HTTP 409 error" ([contactGroups.create](https://developers.google.com/people/api/rest/v1/contactGroups/create)).                                                                                                                                    |
+
+## Update replacement semantics (updateContact)
+
+"All fields specified in the `updateMask` will be replaced"
+([updateContact](https://developers.google.com/people/api/rest/v1/people/updateContact)).
+Each array you name (e.g. `emailAddresses`, `phoneNumbers`) is **replaced wholesale** —
+to add an entry without losing the others, read the contact first, append, then send
+the complete array. Fields you omit from the mask are left untouched.
+"Any non-contact data will not be modified. Any non-contact data in the person to
+update will be ignored"
+([updateContact](https://developers.google.com/people/api/rest/v1/people/updateContact)).
+
+## Etag-based optimistic concurrency
+
+The People API requires `person.metadata.sources.etag` for updates:
+"you must include the `person.metadata.sources.etag` field in the person for the
+contact to be updated"
+([Read and Manage Contacts](https://developers.google.com/people/v1/contacts)).
+A stale etag produces a 400 / `FAILED_PRECONDITION` — re-fetch and retry.
+
+## Singleton fields
+
+Some Person fields accept only a single value per contact source:
+biographies, birthdays, genders, names. Sending an array with more than one entry
+on these fields returns a 400
+([updateContact](https://developers.google.com/people/api/rest/v1/people/updateContact)).
+
+## Search: prefix matching and warmup
+
+`searchContacts` and `searchOtherContacts` use **prefix phrase matching**:
+"a person with name 'foo name' matches queries such as 'f', 'fo', 'foo', 'foo n',
+'nam', etc., but not 'oo n'"
+([searchContacts](https://developers.google.com/people/api/rest/v1/people/searchContacts)).
+
+**Warmup required:** "Before searching, clients should send a warmup request with an
+empty query to update the cache"
+([searchContacts](https://developers.google.com/people/api/rest/v1/people/searchContacts)).
+Without the warmup the cache may not reflect recent changes.
+
+**Page size capped at 30:** "Values greater than 30 will be capped to 30"
+([searchContacts](https://developers.google.com/people/api/rest/v1/people/searchContacts)).
+Default is 10.
+
+## Write propagation delay
+
+"Writes may have a propagation delay of several minutes for sync requests.
+Incremental syncs are not intended for read-after-write use cases"
+([people.connections.list](https://developers.google.com/people/api/rest/v1/people.connections/list)).
+Use `listContacts` (people.connections.list) when freshness matters — it is not
+subject to the search-index propagation delay.
+
+## Mutate request serialization
+
+"Mutate requests for the same user should be sent sequentially to avoid increased
+latency and failures"
+([Read and Manage Contacts](https://developers.google.com/people/v1/contacts)).
+Do not fire concurrent writes for the same account.
+
+## Resource name formats
+
+- Contacts: `people/{person_id}` — "An ASCII string in the form of `people/{person_id}`"
+  ([people resource](https://developers.google.com/people/api/rest/v1/people)).
+- Contact groups: `contactGroups/{contactGroupId}` — "An ASCII string, in the form
+  of `contactGroups/{contactGroupId}`"
+  ([contactGroups resource](https://developers.google.com/people/api/rest/v1/contactGroups)).
+- Other contacts: `otherContacts/{person_id}` — the endpoint is
+  `GET https://people.googleapis.com/v1/otherContacts`
+  ([otherContacts.list](https://developers.google.com/people/api/rest/v1/otherContacts/list)).
+- The resource name may change: "The resource name may change when adding or removing
+  fields that link a contact and profile"
+  ([people resource](https://developers.google.com/people/api/rest/v1/people)).
+
+## Contact groups: user vs system
+
+`groupType` distinguishes `USER_CONTACT_GROUP` (user-defined) from
+`SYSTEM_CONTACT_GROUP` (system-defined, e.g. `myContacts`, `starred`)
+([contactGroups resource](https://developers.google.com/people/api/rest/v1/contactGroups)).
+System group names are "a system provided name" that is "translated and formatted in
+the viewer's account locale"
+([contactGroups resource](https://developers.google.com/people/api/rest/v1/contactGroups)).
+The `contactGroups.create`, `update`, and `delete` methods operate on groups "owned
+by the authenticated user"
+([contactGroups.delete](https://developers.google.com/people/api/rest/v1/contactGroups/delete)).
+System groups have system-provided names and localized `formattedName` values; the
+`name` field description distinguishes "the group owner" from "a system provided name
+for system groups"
+([contactGroups](https://developers.google.com/people/api/rest/v1/contactGroups)).
+
+Group names must be unique: "Created contact group names must be unique to the users
+contact groups" ([contactGroups.create](https://developers.google.com/people/api/rest/v1/contactGroups/create)).
+
+## Contact group membership
+
+`modifyContactGroupMembers` enforces a combined limit: "The total number of resource
+names in `resourceNamesToAdd` and `resourceNamesToRemove` must be less than or equal
+to 1000"
+([contactGroups.members.modify](https://developers.google.com/people/api/rest/v1/contactGroups.members/modify)).
+
+The response reports partial failures without erroring:
+
+- `notFoundResourceNames` — "The contact people resource names that were not found."
+- `canNotRemoveLastContactGroupResourceNames` — "The contact people resource names
+  that cannot be removed from their last contact group"
+  ([contactGroups.members.modify](https://developers.google.com/people/api/rest/v1/contactGroups.members/modify)).
+
+## Other contacts
+
+"Other contacts" are "typically auto created contacts from interactions" that are
+"not in a contact group"
+([otherContacts.list](https://developers.google.com/people/api/rest/v1/otherContacts/list)).
+They require the `contacts.other.readonly` OAuth scope
+([otherContacts.list](https://developers.google.com/people/api/rest/v1/otherContacts/list))
+and the connector exposes them only through read/copy tools: `listOtherContacts`, `searchOtherContacts`, and `copyOtherContact`.
+
+**Limited field set:** other contacts support only a subset of person fields for
+`READ_SOURCE_TYPE_CONTACT`: emailAddresses, metadata, names, phoneNumbers, photos
+([otherContacts.list](https://developers.google.com/people/api/rest/v1/otherContacts/list)).
+
+The `copyOtherContact` tool promotes an other contact to a saved contact (wrapping
+Google's `otherContacts.copyOtherContactToMyContactsGroup` method). The `copyMask`
+is limited to: emailAddresses, names, phoneNumbers
+([docs](https://developers.google.com/people/api/rest/v1/otherContacts/copyOtherContactToMyContactsGroup)).
+
+## Pagination
+
+`listContacts` (people.connections.list): pageSize 1–1000, default 100.
+`listContactGroups`: pageSize 1–1000, default 30.
+`otherContacts.list`: pageSize 1–1000, default 100.
+Search endpoints: pageSize capped at 30, default 10.
+([people.connections.list](https://developers.google.com/people/api/rest/v1/people.connections/list),
+[contactGroups.list](https://developers.google.com/people/api/rest/v1/contactGroups/list),
+[otherContacts.list](https://developers.google.com/people/api/rest/v1/otherContacts/list),
+[searchContacts](https://developers.google.com/people/api/rest/v1/people/searchContacts))
+
+## Email address cap on list endpoints
+
+"For `people.connections.list` and `otherContacts.list` the number of email addresses
+is limited to 100. If a Person has more email addresses the entire set can be obtained
+by calling `people.getBatchGet`"
+([people resource](https://developers.google.com/people/api/rest/v1/people)).
+
+## personFields is required on reads
+
+"The request returns a 400 error if 'personFields' is not specified"
+([people.get](https://developers.google.com/people/api/rest/v1/people/get)).
+Every read operation requires an explicit field mask.
+
+## Delete responses are empty
+
+Both `deleteContact` and `deleteContactGroup` return an empty body on success
+([deleteContact](https://developers.google.com/people/api/rest/v1/people/deleteContact),
+[contactGroups.delete](https://developers.google.com/people/api/rest/v1/contactGroups/delete)).
+
+## Sync token expiry
+
+"Sync tokens expire 7 days after the full sync"
+([people.connections.list](https://developers.google.com/people/api/rest/v1/people.connections/list)).
+"A request with an expired sync token will get an error with an google.rpc.ErrorInfo
+with reason `EXPIRED_SYNC_TOKEN`"
+([people.connections.list](https://developers.google.com/people/api/rest/v1/people.connections/list)) —
+perform a full sync without a `syncToken` to recover.

package/scripts/copyOtherContact.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  PersonSchema,
+  throwForGoogleContacts,
+} from "../lib/google-contacts.ts";
+
+const inputSchema = z
+  .object({
+    resourceName: z
+      .string()
+      .describe(
+        "Other-contact resource name, e.g. otherContacts/c12345 (from listOtherContacts or searchOtherContacts).",
+      ),
+    copyMask: z
+      .string()
+      .describe(
+        "Which fields to copy onto the new contact. Only emailAddresses, names, and phoneNumbers are supported. Defaults to all three.",
+      )
+      .default("names,emailAddresses,phoneNumbers"),
+  })
+  .strict();
+
+const definition = defineTool({
+  name: "copyOtherContact",
+  title: "Copy Other Contact",
+  description:
+    'Promote an "other contact" into the user\'s saved contacts (myContacts), returning an editable contact with a people/c… resourceName.',
+  inputSchema,
+  outputSchema: PersonSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "google-contacts",
+  run: async (input, ctx) => {
+    // resourceName (otherContacts/…) is a Google resource path — the slash is
+    // significant and must NOT be percent-encoded.
+    const url = `https://people.googleapis.com/v1/${input.resourceName}:copyOtherContactToMyContactsGroup`;
+    const res = await ctx.fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ copyMask: input.copyMask }),
+    });
+    await throwForGoogleContacts(res, "copyOtherContact");
+    return res.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });