@zapier/google-contacts-connector 0.0.0 → 0.1.0

package/scripts/listOtherContacts.ts

@@ -0,0 +1,80 @@
+#!/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({
+    readMask: z
+      .string()
+      .describe(
+        "Comma-separated fields to return. Other contacts support only emailAddresses, metadata, names, phoneNumbers, and photos.",
+      )
+      .default("names,emailAddresses,phoneNumbers,metadata"),
+    pageSize: z
+      .number()
+      .int()
+      .gte(1)
+      .lte(1000)
+      .describe(
+        "Max other-contacts to return per page. Defaults to 20 when omitted; pass a value when you need a specific number of results.",
+      )
+      .optional(),
+    pageToken: z
+      .string()
+      .describe(
+        "Page cursor from a previous response's next_page_token. Omit for the first page.",
+      )
+      .optional(),
+  })
+  .strict();
+
+const definition = defineTool({
+  name: "listOtherContacts",
+  title: "List Other Contacts",
+  description:
+    'List the user\'s auto-saved "other contacts" — people interacted with (e.g. emailed) but never explicitly saved. Read-only; use copyOtherContact to make one editable.',
+  inputSchema,
+  outputSchema: z.object({
+    otherContacts: z
+      .array(PersonSchema)
+      .optional()
+      .describe("The page of other contacts."),
+    next_page_token: z
+      .string()
+      .optional()
+      .describe("Cursor for the next page; absent when there are no more."),
+  }),
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "google-contacts",
+  run: async (input, ctx) => {
+    const url = new URL("https://people.googleapis.com/v1/otherContacts");
+    url.searchParams.set("readMask", input.readMask);
+    url.searchParams.set("pageSize", String(input.pageSize ?? 20));
+    if (input.pageToken !== undefined) {
+      url.searchParams.set("pageToken", input.pageToken);
+    }
+    const res = await ctx.fetch(url.toString(), { method: "GET" });
+    await throwForGoogleContacts(res, "listOtherContacts");
+    const payload = (await res.json()) as Record<string, unknown>;
+    if (payload && typeof payload === "object" && "nextPageToken" in payload) {
+      payload.next_page_token = payload.nextPageToken;
+      delete payload.nextPageToken;
+    }
+    return payload;
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/modifyContactGroupMembers.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { throwForGoogleContacts } from "../lib/google-contacts.ts";
+
+const inputSchema = z
+  .object({
+    resourceName: z
+      .string()
+      .describe(
+        "Contact group resource name, e.g. contactGroups/1a2b3c (from listContactGroups).",
+      ),
+    resourceNamesToAdd: z
+      .array(z.string())
+      .describe("Contact resource names (people/c…) to add to the group.")
+      .optional(),
+    resourceNamesToRemove: z
+      .array(z.string())
+      .describe("Contact resource names (people/c…) to remove from the group.")
+      .optional(),
+  })
+  .strict()
+  .refine(
+    (i) =>
+      (i.resourceNamesToAdd?.length ?? 0) > 0 ||
+      (i.resourceNamesToRemove?.length ?? 0) > 0,
+    {
+      message:
+        "Provide at least one of resourceNamesToAdd or resourceNamesToRemove — both cannot be empty.",
+    },
+  );
+
+const definition = defineTool({
+  name: "modifyContactGroupMembers",
+  title: "Modify Contact Group Members",
+  description:
+    "Add and/or remove contacts in a contact group without disturbing other memberships. Combined add+remove must be 1000 or fewer.",
+  inputSchema,
+  outputSchema: z.object({
+    notFoundResourceNames: z
+      .array(z.string())
+      .optional()
+      .describe("Resource names that could not be found and were skipped."),
+    canNotRemoveLastContactGroupResourceNames: z
+      .array(z.string())
+      .optional()
+      .describe(
+        "Contacts that could not be removed because it was their only group (every contact stays in myContacts).",
+      ),
+  }),
+  annotations: {
+    readOnlyHint: false,
+    // resourceNamesToRemove removes group memberships — a non-additive update.
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "google-contacts",
+  run: async (input, ctx) => {
+    // resourceName (contactGroups/…) is a Google resource path — the slash is
+    // significant and must NOT be percent-encoded.
+    const url = `https://people.googleapis.com/v1/${input.resourceName}/members:modify`;
+    const body: Record<string, unknown> = {};
+    if (input.resourceNamesToAdd !== undefined)
+      body.resourceNamesToAdd = input.resourceNamesToAdd;
+    if (input.resourceNamesToRemove !== undefined)
+      body.resourceNamesToRemove = input.resourceNamesToRemove;
+    const res = await ctx.fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    await throwForGoogleContacts(res, "modifyContactGroupMembers");
+    return res.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/searchContacts.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  DEFAULT_PERSON_FIELDS,
+  PersonSchema,
+  throwForGoogleContacts,
+} from "../lib/google-contacts.ts";
+
+const inputSchema = z
+  .object({
+    query: z
+      .string()
+      .describe(
+        'Prefix phrase matched against names, nicknames, emails, phones, and organizations. "foo n" matches "foo name"; "oo n" does not.',
+      ),
+    readMask: z
+      .string()
+      .describe(
+        "Comma-separated list of contact fields to return on each match. Defaults to a comprehensive set.",
+      )
+      .default(DEFAULT_PERSON_FIELDS),
+    pageSize: z
+      .number()
+      .int()
+      .gte(1)
+      .lte(30)
+      .describe(
+        "Max results per page. Caps at 30. Defaults to 10 when omitted; pass a value when you need a specific number of results.",
+      )
+      .optional(),
+  })
+  .strict();
+
+const definition = defineTool({
+  name: "searchContacts",
+  title: "Search Contacts",
+  description:
+    "Search the user's contacts by name, nickname, email, phone, or organization (prefix matching). Newly created/updated contacts may lag a few minutes behind — use listContacts when freshness matters.",
+  inputSchema,
+  outputSchema: z.object({
+    results: z
+      .array(z.object({ person: PersonSchema.optional() }))
+      .optional()
+      .describe("Matching contacts."),
+  }),
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "google-contacts",
+  run: async (input, ctx) => {
+    const url = new URL(
+      "https://people.googleapis.com/v1/people:searchContacts",
+    );
+    url.searchParams.set("query", input.query);
+    url.searchParams.set("readMask", input.readMask);
+    url.searchParams.set("pageSize", String(input.pageSize ?? 10));
+    const res = await ctx.fetch(url.toString(), { method: "GET" });
+    await throwForGoogleContacts(res, "searchContacts");
+    // searchContacts does not paginate (no pageToken in, no cursor out).
+    return res.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/searchOtherContacts.ts

@@ -0,0 +1,71 @@
+#!/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({
+    query: z
+      .string()
+      .describe(
+        "Prefix phrase matched against names, emails, and phones of other contacts.",
+      ),
+    readMask: z
+      .string()
+      .describe(
+        "Comma-separated fields to return. Other contacts support only emailAddresses, metadata, names, phoneNumbers, and photos.",
+      )
+      .default("names,emailAddresses,phoneNumbers,metadata"),
+    pageSize: z
+      .number()
+      .int()
+      .gte(1)
+      .lte(30)
+      .describe(
+        "Max results per page. Caps at 30. Defaults to 10 when omitted; pass a value when you need a specific number of results.",
+      )
+      .optional(),
+  })
+  .strict();
+
+const definition = defineTool({
+  name: "searchOtherContacts",
+  title: "Search Other Contacts",
+  description:
+    'Search the user\'s "other contacts" by name, email, or phone (prefix matching). Same lazy-index caveat as searchContacts — recently-seen contacts may lag.',
+  inputSchema,
+  outputSchema: z.object({
+    results: z
+      .array(z.object({ person: PersonSchema.optional() }))
+      .optional()
+      .describe("Matching other contacts."),
+  }),
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "google-contacts",
+  run: async (input, ctx) => {
+    const url = new URL(
+      "https://people.googleapis.com/v1/otherContacts:search",
+    );
+    url.searchParams.set("query", input.query);
+    url.searchParams.set("readMask", input.readMask);
+    url.searchParams.set("pageSize", String(input.pageSize ?? 10));
+    const res = await ctx.fetch(url.toString(), { method: "GET" });
+    await throwForGoogleContacts(res, "searchOtherContacts");
+    // searchOtherContacts does not paginate (no pageToken in, no cursor out).
+    return res.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/updateContact.ts

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// updateContact is an etag read-modify-write — the People API rejects an update
+// without the contact's current etag (400 FAILED_PRECONDITION), so run() first GETs
+// the contact for the fresh etag, then PATCHes :updateContact. The updatePersonFields
+// mask is derived from exactly the fields supplied so an untouched section is never
+// cleared (the API replaces every named field array wholesale).
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  AddressInput,
+  BiographyInput,
+  BirthdayInput,
+  ContactEventInput,
+  DEFAULT_PERSON_FIELDS,
+  deriveUpdatePersonFields,
+  EmailAddressInput,
+  NameInput,
+  OrganizationInput,
+  PersonSchema,
+  PhoneNumberInput,
+  RelationInput,
+  throwForGoogleContacts,
+  UrlInput,
+  UserDefinedInput,
+} from "../lib/google-contacts.ts";
+
+const inputSchema = z
+  .object({
+    resourceName: z
+      .string()
+      .describe(
+        "Contact to update, e.g. people/c12345 (from listContacts or searchContacts). Pass it whole, including the people/ prefix.",
+      ),
+    names: z
+      .array(NameInput)
+      .describe(
+        "Replaces the full names array. unstructuredName is rebuilt from the parts if you omit it.",
+      )
+      .optional(),
+    emailAddresses: z
+      .array(EmailAddressInput)
+      .describe(
+        "Replaces the full email list. To add one without losing the others, getContact first, append, then send the complete array.",
+      )
+      .optional(),
+    phoneNumbers: z
+      .array(PhoneNumberInput)
+      .describe(
+        "Replaces the full phone list. To add one without losing the others, getContact first, append, then send the complete array.",
+      )
+      .optional(),
+    addresses: z
+      .array(AddressInput)
+      .describe("Replaces the full addresses array.")
+      .optional(),
+    organizations: z
+      .array(OrganizationInput)
+      .describe("Replaces the full organizations array.")
+      .optional(),
+    biographies: z
+      .array(BiographyInput)
+      .describe("Replaces the full notes (biographies) array.")
+      .optional(),
+    birthdays: z
+      .array(BirthdayInput)
+      .describe("Replaces the full birthdays array.")
+      .optional(),
+    urls: z
+      .array(UrlInput)
+      .describe("Replaces the full urls array.")
+      .optional(),
+    events: z
+      .array(ContactEventInput)
+      .describe("Replaces the full custom-events array.")
+      .optional(),
+    relations: z
+      .array(RelationInput)
+      .describe("Replaces the full relations array.")
+      .optional(),
+    userDefined: z
+      .array(UserDefinedInput)
+      .describe("Replaces the full userDefined key/value array.")
+      .optional(),
+  })
+  .strict();
+
+/** Rebuild names[].unstructuredName from the parts when the agent set name parts
+ * but not the full name, so the contact's display name doesn't go stale. */
+function withUnstructuredNames(
+  names: z.infer<typeof NameInput>[],
+): z.infer<typeof NameInput>[] {
+  return names.map((n) => {
+    if (n.unstructuredName) return n;
+    const parts = [
+      n.honorificPrefix,
+      n.givenName,
+      n.middleName,
+      n.familyName,
+      n.honorificSuffix,
+    ].filter((p): p is string => Boolean(p && p.trim()));
+    if (parts.length === 0) return n;
+    return { ...n, unstructuredName: parts.join(" ") };
+  });
+}
+
+const definition = defineTool({
+  name: "updateContact",
+  title: "Update Contact",
+  description:
+    "Update fields on an existing contact. Each array you send REPLACES that whole field (e.g. sending emailAddresses replaces every email) — to add to a list, getContact first, append, then send the full array. Fields you omit are left untouched. Does not change group membership (use modifyContactGroupMembers).",
+  inputSchema,
+  outputSchema: PersonSchema,
+  annotations: {
+    readOnlyHint: false,
+    // Each array field is replace-not-merge: sending one (e.g. emailAddresses)
+    // overwrites the whole field and silently drops any values not included.
+    // That is a non-additive (destructive) update, so the host should treat it
+    // as such and not suppress a confirmation.
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "google-contacts",
+  run: async (input, ctx) => {
+    const { resourceName, ...fields } = input;
+    const updatePersonFields = deriveUpdatePersonFields(fields);
+    if (updatePersonFields === "") {
+      throw new Error(
+        "Google Contacts updateContact: no fields to update — supply at least one of names, emailAddresses, phoneNumbers, addresses, organizations, biographies, birthdays, urls, events, relations, or userDefined.",
+      );
+    }
+
+    // resourceName (people/c…) is a Google resource path — the slash is significant
+    // and must NOT be percent-encoded.
+    // Step 1: read the current contact for its fresh etag (required by the API).
+    const getUrl = new URL(`https://people.googleapis.com/v1/${resourceName}`);
+    getUrl.searchParams.set("personFields", "metadata");
+    const getRes = await ctx.fetch(getUrl.toString(), { method: "GET" });
+    await throwForGoogleContacts(getRes, "updateContact");
+    const current = (await getRes.json()) as { etag?: string };
+
+    // Step 2: build the PATCH body — etag + only the supplied sections; rebuild
+    // unstructuredName so the display name stays in sync with edited name parts.
+    const body: Record<string, unknown> = { etag: current.etag, ...fields };
+    if (fields.names) body.names = withUnstructuredNames(fields.names);
+
+    const patchUrl = new URL(
+      `https://people.googleapis.com/v1/${resourceName}:updateContact`,
+    );
+    patchUrl.searchParams.set("updatePersonFields", updatePersonFields);
+    patchUrl.searchParams.set("personFields", DEFAULT_PERSON_FIELDS);
+    const patchRes = await ctx.fetch(patchUrl.toString(), {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    await throwForGoogleContacts(patchRes, "updateContact");
+    return patchRes.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/updateContactGroup.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// updateContactGroup is an etag read-modify-write — contactGroups.update (PUT) requires
+// the group's current etag, so run() first GETs the group for the fresh etag, then PUTs.
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  ContactGroupSchema,
+  throwForGoogleContacts,
+} from "../lib/google-contacts.ts";
+
+const inputSchema = z
+  .object({
+    resourceName: z
+      .string()
+      .describe(
+        "Contact group to rename, e.g. contactGroups/1a2b3c (from listContactGroups). System groups (myContacts, starred) cannot be renamed.",
+      ),
+    name: z.string().describe("The new contact group (label) name."),
+  })
+  .strict();
+
+const definition = defineTool({
+  name: "updateContactGroup",
+  title: "Update Contact Group",
+  description:
+    "Rename an existing user contact group (label). Only USER_CONTACT_GROUPs can be renamed — system groups (myContacts, starred) are rejected. Check groupType via listContactGroups.",
+  inputSchema,
+  outputSchema: ContactGroupSchema,
+  annotations: {
+    readOnlyHint: false,
+    // Rename overwrites the existing group name (replace, not add) — non-additive.
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "google-contacts",
+  run: async (input, ctx) => {
+    // resourceName (contactGroups/…) is a Google resource path — the slash is
+    // significant and must NOT be percent-encoded.
+    const base = `https://people.googleapis.com/v1/${input.resourceName}`;
+
+    // Step 1: read the current group for its fresh etag (required by the API).
+    const getUrl = new URL(base);
+    getUrl.searchParams.set("groupFields", "metadata");
+    const getRes = await ctx.fetch(getUrl.toString(), { method: "GET" });
+    await throwForGoogleContacts(getRes, "updateContactGroup");
+    const current = (await getRes.json()) as { etag?: string };
+
+    // Step 2: PUT the new name with the etag.
+    const putRes = await ctx.fetch(base, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        contactGroup: { etag: current.etag, name: input.name },
+        updateGroupFields: "name",
+      }),
+    });
+    await throwForGoogleContacts(putRes, "updateContactGroup");
+    return putRes.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/updateContactPhoto.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  PersonResponseSchema,
+  throwForGoogleContacts,
+} from "../lib/google-contacts.ts";
+
+const inputSchema = z
+  .object({
+    resourceName: z
+      .string()
+      .describe(
+        "Contact resource name, e.g. people/c12345 (from listContacts or searchContacts). Pass it whole, including the people/ prefix.",
+      ),
+    photoBytes: z
+      .string()
+      .describe("The contact photo as a base64-encoded image string."),
+    personFields: z
+      .string()
+      .describe(
+        "Which fields to return on the updated contact. Defaults to a comprehensive set.",
+      )
+      .default("names,emailAddresses,phoneNumbers,photos,metadata"),
+  })
+  .strict();
+
+const definition = defineTool({
+  name: "updateContactPhoto",
+  title: "Update Contact Photo",
+  description:
+    "Set or replace a contact's photo. photoBytes is the image as a base64-encoded string (not a URL or file path).",
+  inputSchema,
+  outputSchema: PersonResponseSchema,
+  annotations: {
+    readOnlyHint: false,
+    // Overwrites the contact's existing photo (replace, not add) — non-additive.
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
+  connection: "google-contacts",
+  run: async (input, ctx) => {
+    // resourceName (people/c…) is a Google resource path — the slash is significant
+    // and must NOT be percent-encoded.
+    const url = `https://people.googleapis.com/v1/${input.resourceName}:updateContactPhoto`;
+    const res = await ctx.fetch(url, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        photoBytes: input.photoBytes,
+        personFields: input.personFields,
+      }),
+    });
+    await throwForGoogleContacts(res, "updateContactPhoto");
+    return res.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/tsup.config.ts

@@ -0,0 +1,63 @@
+/**
+ * tsup build config for connectors.
+ *
+ * Compiles index.ts (library entry, bundled) and cli.ts (CLI, bundled but
+ * with the connector's index module kept external).
+ *
+ * The cli.ts entry externalises ./index.ts → ./index.js via an esbuild plugin
+ * so that dist/cli.js imports the pre-built dist/index.js as a separate module
+ * rather than inlining scripts. Without this, each script's top-level
+ * `await handleIfScriptMain(import.meta, …)` ends up inside the single-file
+ * bundle; in Node 22.18+ import.meta.main is true for the bundle entry,
+ * causing every script to execute when the dispatch CLI starts instead of
+ * routing via runDispatchCli.
+ *
+ * Managed by @zapier/connectors-dev — do not edit; synced byte-for-byte
+ * across every connector.
+ */
+import { defineConfig } from "tsup";
+
+export default defineConfig([
+  {
+    entry: ["index.ts"],
+    format: ["esm"],
+    dts: false,
+    clean: true,
+    target: "es2022",
+    external: [
+      "@modelcontextprotocol/sdk",
+      "@zapier/zapier-sdk",
+      "zod",
+      "@zapier/connectors-sdk",
+    ],
+  },
+  {
+    entry: ["cli.ts"],
+    format: ["esm"],
+    dts: false,
+    clean: false,
+    target: "es2022",
+    external: [
+      "@modelcontextprotocol/sdk",
+      "@zapier/zapier-sdk",
+      "zod",
+      "@zapier/connectors-sdk",
+    ],
+    esbuildPlugins: [
+      {
+        name: "externalize-connector-index",
+        setup(build) {
+          // Resolve ./index.ts to the pre-built ./index.js and mark it external
+          // so scripts are not inlined into dist/cli.js. When dist/index.js is
+          // imported (not the entry), import.meta.main is false inside it and
+          // handleIfScriptMain's existing !meta.main guard suppresses per-script
+          // execution — no SDK changes required.
+          build.onResolve({ filter: /^\.\/index(\.ts)?$/ }, () => ({
+            path: "./index.js",
+            external: true,
+          }));
+        },
+      },
+    ],
+  },
+]);