@zapier/google-contacts-connector 0.0.0 → 0.1.0

package/scripts/createContact.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  AddressInput,
+  BiographyInput,
+  BirthdayInput,
+  ContactEventInput,
+  DEFAULT_PERSON_FIELDS,
+  EmailAddressInput,
+  MembershipInput,
+  NameInput,
+  OrganizationInput,
+  PersonSchema,
+  PhoneNumberInput,
+  RelationInput,
+  throwForGoogleContacts,
+  UrlInput,
+  UserDefinedInput,
+} from "../lib/google-contacts.ts";
+
+const inputSchema = z
+  .object({
+    names: z
+      .array(NameInput)
+      .describe(
+        "Name parts. Set unstructuredName (the full formatted name) or it is derived from the parts.",
+      )
+      .optional(),
+    emailAddresses: z
+      .array(EmailAddressInput)
+      .describe("Email addresses.")
+      .optional(),
+    phoneNumbers: z
+      .array(PhoneNumberInput)
+      .describe("Phone numbers.")
+      .optional(),
+    addresses: z.array(AddressInput).describe("Postal addresses.").optional(),
+    organizations: z
+      .array(OrganizationInput)
+      .describe("Companies / job titles.")
+      .optional(),
+    biographies: z
+      .array(BiographyInput)
+      .describe("Notes about the contact.")
+      .optional(),
+    birthdays: z
+      .array(BirthdayInput)
+      .describe(
+        "Birthdays. Use a structured date (year optional for year-less birthdays).",
+      )
+      .optional(),
+    urls: z.array(UrlInput).describe("Websites or profile links.").optional(),
+    events: z
+      .array(ContactEventInput)
+      .describe("Custom dates such as anniversaries.")
+      .optional(),
+    relations: z
+      .array(RelationInput)
+      .describe("Related people (e.g. spouse, manager).")
+      .optional(),
+    userDefined: z
+      .array(UserDefinedInput)
+      .describe("Custom key/value fields.")
+      .optional(),
+    memberships: z
+      .array(MembershipInput)
+      .describe(
+        "Contact groups to add this new contact to at creation. For an EXISTING contact use modifyContactGroupMembers instead. Resolve ids via listContactGroups.",
+      )
+      .optional(),
+    personFields: z
+      .string()
+      .describe(
+        "Comma-separated list of contact fields to return (e.g. names,emailAddresses,phoneNumbers). Defaults to a comprehensive set; narrow it to reduce payload. Include metadata for the etag.",
+      )
+      .default(DEFAULT_PERSON_FIELDS),
+  })
+  .strict()
+  .refine(
+    (i) =>
+      (i.names?.length ?? 0) > 0 ||
+      (i.emailAddresses?.length ?? 0) > 0 ||
+      (i.phoneNumbers?.length ?? 0) > 0,
+    {
+      message:
+        "Provide at least one of names, emailAddresses, or phoneNumbers — a contact with no name and no contact method is not useful.",
+    },
+  );
+
+const definition = defineTool({
+  name: "createContact",
+  title: "Create Contact",
+  description:
+    "Create a new contact from structured name, email, phone, address, and organization fields. Provide at least a name or one contact method.",
+  inputSchema,
+  outputSchema: PersonSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "google-contacts",
+  run: async (input, ctx) => {
+    const { personFields, memberships, ...sections } = input;
+    // Only attach sections that carry values — the API rejects empty optional
+    // sections ([] / [{}]) with INVALID_ARGUMENT.
+    const body: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(sections)) {
+      if (value !== undefined) body[key] = value;
+    }
+    // memberships is agent-friendly ([{contactGroupResourceName}]); the wire shape
+    // nests it under contactGroupMembership.
+    if (memberships !== undefined) {
+      body.memberships = memberships.map((m) => ({
+        contactGroupMembership: {
+          contactGroupResourceName: m.contactGroupResourceName,
+        },
+      }));
+    }
+    const url = new URL(
+      "https://people.googleapis.com/v1/people:createContact",
+    );
+    url.searchParams.set("personFields", personFields);
+    const res = await ctx.fetch(url.toString(), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    await throwForGoogleContacts(res, "createContact");
+    return res.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/createContactGroup.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+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({
+    name: z
+      .string()
+      .describe(
+        "The contact group (label) name. A duplicate name returns an already-exists error.",
+      ),
+  })
+  .strict();
+
+const definition = defineTool({
+  name: "createContactGroup",
+  title: "Create Contact Group",
+  description:
+    "Create a new user contact group (label). Returns the resourceName used to add members via modifyContactGroupMembers.",
+  inputSchema,
+  outputSchema: ContactGroupSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "google-contacts",
+  run: async (input, ctx) => {
+    const res = await ctx.fetch(
+      "https://people.googleapis.com/v1/contactGroups",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ contactGroup: { name: input.name } }),
+      },
+    );
+    await throwForGoogleContacts(res, "createContactGroup");
+    return res.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/deleteContact.ts

@@ -0,0 +1,52 @@
+#!/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 resource name, e.g. people/c12345 (from listContacts or searchContacts). Pass it whole, including the people/ prefix.",
+      ),
+  })
+  .strict();
+
+const definition = defineTool({
+  name: "deleteContact",
+  title: "Delete Contact",
+  description:
+    "Delete a contact from the user's account. A 404 means nothing was deleted — the resourceName wasn't found (already deleted, or a wrong/typo'd id); it is NOT a success. Re-resolve the contact via searchContacts/listContacts before retrying.",
+  inputSchema,
+  outputSchema: z.object({
+    success: z
+      .boolean()
+      .describe(
+        "True when the contact was deleted (the API returns an empty body).",
+      ),
+  }),
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    // Not idempotent: a 404 (already-deleted or wrong id) throws rather than
+    // reporting success, so a blind retry isn't safe — the agent must re-resolve.
+    idempotentHint: false,
+    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}:deleteContact`;
+    const res = await ctx.fetch(url, { method: "DELETE" });
+    await throwForGoogleContacts(res, "deleteContact");
+    return { success: true };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/deleteContactGroup.ts

@@ -0,0 +1,61 @@
+#!/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). Pass it whole, including the contactGroups/ prefix.",
+      ),
+    deleteContacts: z
+      .boolean()
+      .describe(
+        "When true, also delete the contacts that were in the group (not just the label). Defaults to false (label only).",
+      )
+      .default(false),
+  })
+  .strict();
+
+const definition = defineTool({
+  name: "deleteContactGroup",
+  title: "Delete Contact Group",
+  description:
+    "Delete a user contact group (label). System groups (myContacts, starred) cannot be deleted. Optionally delete the member contacts too. A 404 means nothing was deleted — the resourceName wasn't found (already deleted, or a wrong id); it is NOT a success. Re-resolve via listContactGroups before retrying.",
+  inputSchema,
+  outputSchema: z.object({
+    success: z
+      .boolean()
+      .describe(
+        "True when the group was deleted (the API returns an empty body).",
+      ),
+  }),
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    // Not idempotent: a 404 (already-deleted or wrong id) throws rather than
+    // reporting success, so a blind retry isn't safe — the agent must re-resolve.
+    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 = new URL(
+      `https://people.googleapis.com/v1/${input.resourceName}`,
+    );
+    url.searchParams.set("deleteContacts", String(input.deleteContacts));
+    const res = await ctx.fetch(url.toString(), { method: "DELETE" });
+    await throwForGoogleContacts(res, "deleteContactGroup");
+    return { success: true };
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/deleteContactPhoto.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  DEFAULT_PERSON_FIELDS,
+  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.",
+      ),
+    personFields: z
+      .string()
+      .describe(
+        "Comma-separated list of contact fields to return (e.g. names,emailAddresses,phoneNumbers). Defaults to a comprehensive set; narrow it to reduce payload. Include metadata for the etag.",
+      )
+      .default(DEFAULT_PERSON_FIELDS),
+  })
+  .strict();
+
+const definition = defineTool({
+  name: "deleteContactPhoto",
+  title: "Delete Contact Photo",
+  description: "Remove a contact's photo, reverting to the default avatar.",
+  inputSchema,
+  outputSchema: PersonResponseSchema,
+  annotations: {
+    readOnlyHint: false,
+    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 = new URL(
+      `https://people.googleapis.com/v1/${input.resourceName}:deleteContactPhoto`,
+    );
+    url.searchParams.set("personFields", input.personFields);
+    const res = await ctx.fetch(url.toString(), { method: "DELETE" });
+    await throwForGoogleContacts(res, "deleteContactPhoto");
+    return res.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/getContact.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 {
+  DEFAULT_PERSON_FIELDS,
+  PersonSchema,
+  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.",
+      ),
+    personFields: z
+      .string()
+      .describe(
+        "Comma-separated list of contact fields to return (e.g. names,emailAddresses,phoneNumbers). Defaults to a comprehensive set; narrow it to reduce payload. Include metadata for the etag.",
+      )
+      .default(DEFAULT_PERSON_FIELDS),
+  })
+  .strict();
+
+const definition = defineTool({
+  name: "getContact",
+  title: "Get Contact",
+  description:
+    "Retrieve a single contact by resource name, with full field detail. Call before an additive update to read the existing arrays.",
+  inputSchema,
+  outputSchema: PersonSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    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, so it is interpolated raw, not via encodeURIComponent.
+    const url = new URL(
+      `https://people.googleapis.com/v1/${input.resourceName}`,
+    );
+    url.searchParams.set("personFields", input.personFields);
+    const res = await ctx.fetch(url.toString(), { method: "GET" });
+    await throwForGoogleContacts(res, "getContact");
+    return res.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/getContactGroup.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// A single GET /v1/contactGroups/{id}. Kept as its own tool because the bare
+// "GET /{resourceName}" path+method is shared with getContact (people/* vs
+// contactGroups/*), and the two resources need different field params and parsing.
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  ContactGroupSchema,
+  DEFAULT_GROUP_FIELDS,
+  throwForGoogleContacts,
+} from "../lib/google-contacts.ts";
+
+const inputSchema = z
+  .object({
+    resourceName: z
+      .string()
+      .describe(
+        "Contact group resource name, e.g. contactGroups/1a2b3c (from listContactGroups). Pass it whole, including the contactGroups/ prefix.",
+      ),
+    maxMembers: z
+      .number()
+      .int()
+      .gte(1)
+      .describe(
+        "Include up to this many member contact resource names (people/c…) in memberResourceNames. Omit to return group metadata only.",
+      )
+      .optional(),
+    groupFields: z
+      .string()
+      .describe(
+        "Comma-separated list of contact-group fields to return (e.g. name,groupType,memberCount).",
+      )
+      .default(DEFAULT_GROUP_FIELDS),
+  })
+  .strict();
+
+const definition = defineTool({
+  name: "getContactGroup",
+  title: "Get Contact Group",
+  description:
+    "Get a single contact group (label) by resource name, optionally with its member contact resource names (set maxMembers).",
+  inputSchema,
+  outputSchema: ContactGroupSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    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 url = new URL(
+      `https://people.googleapis.com/v1/${input.resourceName}`,
+    );
+    url.searchParams.set("groupFields", input.groupFields);
+    if (input.maxMembers !== undefined) {
+      url.searchParams.set("maxMembers", String(input.maxMembers));
+    }
+    const res = await ctx.fetch(url.toString(), { method: "GET" });
+    await throwForGoogleContacts(res, "getContactGroup");
+    return res.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/listContactGroups.ts

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  ContactGroupSchema,
+  DEFAULT_GROUP_FIELDS,
+  throwForGoogleContacts,
+} from "../lib/google-contacts.ts";
+
+const inputSchema = z
+  .object({
+    groupFields: z
+      .string()
+      .describe(
+        "Comma-separated list of contact-group fields to return (e.g. name,groupType,memberCount).",
+      )
+      .default(DEFAULT_GROUP_FIELDS),
+    pageSize: z
+      .number()
+      .int()
+      .gte(1)
+      .lte(1000)
+      .describe(
+        "Max groups 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: "listContactGroups",
+  title: "List Contact Groups",
+  description:
+    "List the account's contact groups (labels), user and system, with id, name, type, and member count. The resolver for any contactGroupResourceName.",
+  inputSchema,
+  outputSchema: z.object({
+    contactGroups: z
+      .array(ContactGroupSchema)
+      .optional()
+      .describe("The page of contact groups."),
+    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/contactGroups");
+    url.searchParams.set("groupFields", input.groupFields);
+    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, "listContactGroups");
+    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/listContacts.ts

@@ -0,0 +1,110 @@
+#!/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({
+    personFields: z
+      .string()
+      .describe(
+        "Comma-separated list of contact fields to return (e.g. names,emailAddresses,phoneNumbers). Defaults to a comprehensive set; narrow it to reduce payload. Include metadata for the etag.",
+      )
+      .default(DEFAULT_PERSON_FIELDS),
+    sortOrder: z
+      .enum([
+        "LAST_MODIFIED_ASCENDING",
+        "LAST_MODIFIED_DESCENDING",
+        "FIRST_NAME_ASCENDING",
+        "LAST_NAME_ASCENDING",
+      ])
+      .describe("Order of the returned contacts.")
+      .optional(),
+    pageSize: z
+      .number()
+      .int()
+      .gte(1)
+      .lte(1000)
+      .describe(
+        "Max 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: "listContacts",
+  title: "List Contacts",
+  description:
+    "List the user's contacts, paginated, with full field detail. The primary contact enumerator and resourceName resolver. Use this (not searchContacts) when freshness matters.",
+  inputSchema,
+  outputSchema: z.object({
+    contacts: z
+      .array(PersonSchema)
+      .optional()
+      .describe("The page of contacts."),
+    next_page_token: z
+      .string()
+      .optional()
+      .describe("Cursor for the next page; absent when there are no more."),
+    total_people: z
+      .number()
+      .int()
+      .optional()
+      .describe("Total contacts on the account."),
+  }),
+  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/me/connections",
+    );
+    url.searchParams.set("personFields", input.personFields);
+    if (input.sortOrder !== undefined) {
+      url.searchParams.set("sortOrder", input.sortOrder);
+    }
+    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, "listContacts");
+    const payload = (await res.json()) as Record<string, unknown>;
+    if (payload && typeof payload === "object") {
+      if ("connections" in payload) {
+        payload.contacts = payload.connections;
+        delete payload.connections;
+      }
+      if ("nextPageToken" in payload) {
+        payload.next_page_token = payload.nextPageToken;
+        delete payload.nextPageToken;
+      }
+      if ("totalPeople" in payload) {
+        payload.total_people = payload.totalPeople;
+        delete payload.totalPeople;
+      }
+    }
+    return payload;
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });