@zapier/google-contacts-connector 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/NOTICE

@@ -0,0 +1,8 @@
+Independent, unofficial connector for Google Contacts.
+
+Zapier licenses only the connector code in this package, under the Elastic
+License 2.0. Zapier grants no rights in Google Contacts's API, services, data,
+schemas, documentation, or other materials, which remain the property of
+Google Contacts. Google Contacts and its logos are trademarks of their owner, used only to
+identify the service this connector works with. Not affiliated with, endorsed
+by, or sponsored by Google Contacts.

package/README.md

@@ -1,4 +1,108 @@
 # @zapier/google-contacts-connector
 
-> **Placeholder** — published to bootstrap OIDC Trusted Publisher configuration.
-> The real package is published via GitLab CI once trust is established.
+_Independent, unofficial connector for Google Contacts. Not affiliated with, endorsed by, or sponsored by Google Contacts. "Google Contacts" is a trademark of its owner, used only to identify the service this connector works with._
+
+Agent-callable tools for Google Contacts, wrapping the [Google People API](https://developers.google.com/people/api/rest). It lets an agent create, read, update, and delete a person's contacts; search contacts by name, email, or phone; set or remove contact photos; create and manage contact groups (labels) and their membership; and browse the auto-saved "other contacts" surface. Authentication is OAuth 2.0 — either a Zapier-managed connection (recommended) or a direct Google access token.
+
+This connector is the same artifact across four shapes: MCP server, CLI bin, importable Node module, and an [Agent Skill](https://agentskills.io/) anchored by [`SKILL.md`](SKILL.md). Pick the shape that matches how your agent runs.
+
+## Install
+
+```bash
+# Run a tool with zero install — npx fetches the package on first use
+GOOGLE_CONTACTS_ACCESS_TOKEN=xxx npx @zapier/google-contacts-connector run <toolName> '{ ... }' --connection env:GOOGLE_CONTACTS_ACCESS_TOKEN
+
+# Install as a dependency to import the tools in your own code
+npm install @zapier/google-contacts-connector
+
+# Or install as an Agent Skill (https://agentskills.io)
+npx skills zapier/connectors --skill google-contacts
+```
+
+Auth is one `[<resolver>:]<value>` connection string passed with `--connection`. The value is a _selector_, not the secret: `--connection zapier:<connection-id>` routes through Zapier-managed auth (recommended; no third-party secret enters the agent's environment — store the id in `GOOGLE_CONTACTS_ZAPIER_CONNECTION_ID` and pass `--connection "zapier:$GOOGLE_CONTACTS_ZAPIER_CONNECTION_ID"` if you like), and `--connection env:GOOGLE_CONTACTS_ACCESS_TOKEN` reads a direct token from `$GOOGLE_CONTACTS_ACCESS_TOKEN` (the token stays in `env`, never on argv). The `<resolver>:` prefix is optional — a bare value is claimed by the first matching resolver. See [`SKILL.md`](SKILL.md#auth) for tradeoffs and how to find a connection ID.
+
+## Tools
+
+| Tool                        | Description                                                                                |
+| --------------------------- | ------------------------------------------------------------------------------------------ |
+| `createContact`             | Create a contact from structured name, email, phone, address, and organization fields.     |
+| `getContact`                | Retrieve a single contact by resource name, with full field detail.                        |
+| `updateContact`             | Update a contact; each array sent replaces that whole field, omitted fields are untouched. |
+| `deleteContact`             | Delete a contact from the account.                                                         |
+| `listContacts`              | List the account's contacts, paginated — the primary resourceName resolver.                |
+| `searchContacts`            | Search contacts by name, nickname, email, phone, or organization (prefix match).           |
+| `updateContactPhoto`        | Set or replace a contact's photo from a base64-encoded image.                              |
+| `deleteContactPhoto`        | Remove a contact's photo, reverting to the default avatar.                                 |
+| `listContactGroups`         | List contact groups (labels), user and system — the contactGroupResourceName resolver.     |
+| `getContactGroup`           | Get a single contact group, optionally with its member contact resource names.             |
+| `createContactGroup`        | Create a new user contact group (label).                                                   |
+| `updateContactGroup`        | Rename a user contact group (system groups cannot be renamed).                             |
+| `deleteContactGroup`        | Delete a user contact group (label), optionally with its member contacts.                  |
+| `modifyContactGroupMembers` | Add and/or remove contacts in a group without disturbing other memberships.                |
+| `listOtherContacts`         | List auto-saved "other contacts" (people interacted with but never saved).                 |
+| `searchOtherContacts`       | Search "other contacts" by name, email, or phone (prefix match).                           |
+| `copyOtherContact`          | Promote an "other contact" into saved contacts, returning an editable contact.             |
+
+Run `npx @zapier/google-contacts-connector run <toolName> --help` to see any tool's exact input contract + the available resolvers.
+
+## Usage
+
+```ts
+import { searchContacts } from "@zapier/google-contacts-connector";
+
+// Each named export is the consumer-facing (input, opts) => Promise<{ data, meta }>.
+const { data } = await searchContacts(
+  { query: "jane" },
+  { connection: "env:GOOGLE_CONTACTS_ACCESS_TOKEN" },
+);
+// data.results[].person is the canonical People API Person resource.
+```
+
+## MCP Server
+
+Add one stanza to any MCP-aware client (Claude Desktop, Cursor, Claude Code, …) to auto-discover the tools over stdio:
+
+<!-- prettier-ignore -->
+```jsonc
+// e.g. claude_desktop_config.json or .cursor/mcp.json
+{
+  "mcpServers": {
+    "google-contacts": {
+      "command": "npx",
+      "args": ["@zapier/google-contacts-connector", "mcp", "--connection", "zapier:<connection-id>"],
+    }
+  }
+}
+```
+
+No Zapier account? Use the `env:` resolver — point `--connection` at an env-var name and keep the token in `env`: `"args": ["@zapier/google-contacts-connector", "mcp", "--connection", "env:GOOGLE_CONTACTS_ACCESS_TOKEN"]` with `"env": { "GOOGLE_CONTACTS_ACCESS_TOKEN": "xxx" }`.
+
+## When to use this
+
+Use this connector to manage a person's own Google Contacts — saving and finding people, editing their details, organizing them into groups/labels, and turning auto-saved "other contacts" into real contacts. It's the right pick for contact-CRUD, contact search, and label management against a single Google account over the People API.
+
+## When NOT to use this
+
+- **Google Workspace directory lookups** (org-wide people search) — not covered; this connector manages the user's personal contacts, not the domain directory.
+- **Bulk/batch contact imports or mass edits** — there are no batch tools; act on one contact at a time.
+- **Contact merge/dedupe** — not supported by these tools.
+
+## Links
+
+- [`SKILL.md`](SKILL.md) — runtime guidance for agents
+- [Google People API reference](https://developers.google.com/people/api/rest) — the upstream API this connector wraps
+- [Source](https://github.com/zapier/connectors/tree/main/apps/google-contacts)
+
+## Legal
+
+**Scope of license.** Zapier licenses only the connector code in this package. Zapier grants no rights in Google Contacts's API, services, data, schemas, documentation, or other materials, which remain the property of Google Contacts. Your use of Google Contacts's API is governed by your own agreement with Google Contacts.
+
+**Trademarks and affiliation.** Google Contacts and its logos are trademarks of their owner, used here only to identify the service this connector works with. This connector is not affiliated with, endorsed by, or sponsored by Google Contacts.
+
+**Your responsibility.** This connector calls Google Contacts's API using credentials you supply. You are responsible for holding a valid Google Contacts account, for complying with Google Contacts's API terms, developer policies, and acceptable use rules, and for the data you send and receive through it.
+
+**No warranty.** This connector is provided "as is," without warranty of any kind, and is not an official Google Contacts product. Zapier is not responsible for changes Google Contacts makes to its API or for any consequence of your use of Google Contacts's API. See the repository LICENSE for the full disclaimer.
+
+**Forks.** You may fork and modify this connector under the Elastic License 2.0. You may state that your fork is "based on" Zapier's connector, but you may not use the "Zapier" name or logo as the name or branding of your fork, or in any way that suggests Zapier produces, endorses, or supports it.
+
+Licensed under the Elastic License 2.0. See the repository LICENSE and NOTICE.

package/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: google-contacts
+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
+compatibility: Requires Node.js 22.18+ or Bun 1.x; run `npm install` in this directory first.
+metadata:
+  title: Google Contacts
+  source: https://github.com/zapier/connectors/blob/main/apps/google-contacts/SKILL.md
+  zapier-app-key: GoogleContactsCLIAPI
+  api-docs: https://developers.google.com/people/api/rest
+---
+
+# Google Contacts
+
+_Independent, unofficial connector for Google Contacts. Not affiliated with, endorsed by, or sponsored by Google Contacts. "Google Contacts" is a trademark of its owner, used only to identify the service this connector works with._
+
+Agent-callable tools for Google Contacts, wrapping the [Google People API](https://developers.google.com/people/api/rest). Create, read, update, and delete a person's contacts; search contacts by name, email, or phone; set or remove contact photos; create and manage contact groups (labels) and their membership; and browse the auto-saved "other contacts" surface. Every tool uses a single OAuth connection; capability is gated by the granted scope.
+
+## When to use this connector
+
+- Saving, finding, updating, or deleting a person's Google Contacts ("add Jane to my contacts", "what's Bob's email", "remove this contact").
+- Organizing contacts into groups/labels and adding or removing members.
+- Setting or removing a contact's photo.
+- Finding someone the user has interacted with (e.g. emailed) but never explicitly saved — the "other contacts" surface — and promoting them into saved contacts.
+
+## Scripts
+
+One file per tool in [`scripts/`](scripts/); each tool's `inputSchema` / `outputSchema` (Zod) in the script file is the source of truth for its contract. All tools use the single connection `google-contacts`.
+
+| Script                                                                         | Tool name                   | Connections       | Description                                                                                |
+| ------------------------------------------------------------------------------ | --------------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
+| [`scripts/createContact.ts`](scripts/createContact.ts)                         | `createContact`             | `google-contacts` | Create a contact from structured name, email, phone, address, and organization fields.     |
+| [`scripts/getContact.ts`](scripts/getContact.ts)                               | `getContact`                | `google-contacts` | Retrieve a single contact by resource name, with full field detail.                        |
+| [`scripts/updateContact.ts`](scripts/updateContact.ts)                         | `updateContact`             | `google-contacts` | Update a contact; each array sent replaces that whole field, omitted fields are untouched. |
+| [`scripts/deleteContact.ts`](scripts/deleteContact.ts)                         | `deleteContact`             | `google-contacts` | Delete a contact from the account.                                                         |
+| [`scripts/listContacts.ts`](scripts/listContacts.ts)                           | `listContacts`              | `google-contacts` | List the account's contacts, paginated — the primary resourceName resolver.                |
+| [`scripts/searchContacts.ts`](scripts/searchContacts.ts)                       | `searchContacts`            | `google-contacts` | Search contacts by name, nickname, email, phone, or organization (prefix match).           |
+| [`scripts/updateContactPhoto.ts`](scripts/updateContactPhoto.ts)               | `updateContactPhoto`        | `google-contacts` | Set or replace a contact's photo from a base64-encoded image.                              |
+| [`scripts/deleteContactPhoto.ts`](scripts/deleteContactPhoto.ts)               | `deleteContactPhoto`        | `google-contacts` | Remove a contact's photo, reverting to the default avatar.                                 |
+| [`scripts/listContactGroups.ts`](scripts/listContactGroups.ts)                 | `listContactGroups`         | `google-contacts` | List contact groups (labels), user and system — the contactGroupResourceName resolver.     |
+| [`scripts/getContactGroup.ts`](scripts/getContactGroup.ts)                     | `getContactGroup`           | `google-contacts` | Get a single contact group, optionally with its member contact resource names.             |
+| [`scripts/createContactGroup.ts`](scripts/createContactGroup.ts)               | `createContactGroup`        | `google-contacts` | Create a new user contact group (label).                                                   |
+| [`scripts/updateContactGroup.ts`](scripts/updateContactGroup.ts)               | `updateContactGroup`        | `google-contacts` | Rename a user contact group (system groups cannot be renamed).                             |
+| [`scripts/deleteContactGroup.ts`](scripts/deleteContactGroup.ts)               | `deleteContactGroup`        | `google-contacts` | Delete a user contact group (label), optionally with its member contacts.                  |
+| [`scripts/modifyContactGroupMembers.ts`](scripts/modifyContactGroupMembers.ts) | `modifyContactGroupMembers` | `google-contacts` | Add and/or remove contacts in a group without disturbing other memberships.                |
+| [`scripts/listOtherContacts.ts`](scripts/listOtherContacts.ts)                 | `listOtherContacts`         | `google-contacts` | List auto-saved "other contacts" (people interacted with but never saved).                 |
+| [`scripts/searchOtherContacts.ts`](scripts/searchOtherContacts.ts)             | `searchOtherContacts`       | `google-contacts` | Search "other contacts" by name, email, or phone (prefix match).                           |
+| [`scripts/copyOtherContact.ts`](scripts/copyOtherContact.ts)                   | `copyOtherContact`          | `google-contacts` | Promote an "other contact" into saved contacts, returning an editable contact.             |
+
+## Disambiguation & refusals
+
+- **Resolve names before writing.** Before `updateContact` / `deleteContact` / `modifyContactGroupMembers` on a contact identified by name, call `searchContacts` (or `listContacts`) and count _exact_, case-insensitive name matches. One match → act on it; don't over-ask. Two or more that tie → **stop, list the candidates with a distinguishing field (email or phone), and ask which one** — never silently pick. The same rule applies to groups via `listContactGroups`.
+- **Editing a list field replaces it.** `updateContact` replaces each array you send (e.g. `emailAddresses`) wholesale. To _add_ a value without dropping the others, `getContact` first, append, then send the full array. For group membership, prefer `modifyContactGroupMembers` (element-level) over `updateContact`.
+- **Out of scope — decline, don't substitute.** This connector does **not** do bulk/batch contact create-update-delete, Google Workspace **directory** lookups, or contact **merge/dedupe**. If asked for one of these, say it isn't supported and stop — do not call another tool and report it as done.
+- **No bulk operations — never loop to fake one.** There is no batch endpoint. If asked to change, add, or delete a field across **many or all** contacts at once (e.g. "set everyone's company to Acme"), **decline and explain it isn't supported** — do **not** loop `updateContact` / `deleteContact` / `modifyContactGroupMembers` over multiple contacts to simulate a bulk operation. Acting on a single, explicitly-identified contact is fine; fanning out across the address book is not.
+
+## Output format
+
+Every script returns a `{ data, meta }` envelope (same shape across the CLI's JSON output, the imported SDK return value, and the MCP tool's `structuredContent`):
+
+- **`data`** — the script's result (the shape declared by its `outputSchema`).
+- **`meta.outputDataValidation`** — what validating `data` did:
+  - `{ skipped: false, droppedPaths: null }` — validated, nothing removed.
+  - `{ skipped: false, droppedPaths: [...], instruction }` — validated, but those paths (fields the API returned that the `outputSchema` doesn't declare) were stripped from `data`. If you need them, re-run with output validation skipped.
+  - `{ skipped: true }` — validation was bypassed; `data` is the raw, unchecked API output.
+
+**Reading dropped fields / `skipOutputDataValidation`.** To receive the raw, unvalidated result, set the single token `skipOutputDataValidation` — CLI: append `--skipOutputDataValidation`; MCP: pass `meta: { skipOutputDataValidation: true }` as a tool argument; SDK: pass `{ skipOutputDataValidation: true }` in the run options. Input validation is never skipped.
+
+**Trimming the result / `filterOutputData`.** To shrink a large result down to the fields you need, pass a jq expression that post-processes `data` — CLI: append `--filterOutputData '<jq>'`; MCP: pass `meta: { filterOutputData: "<jq>" }` as a tool argument. The jq runs against `data` only, NOT the `{ data, meta }` envelope, so write it rooted at `data` (see this script's output schema). The transformed value replaces `data`, `meta` is preserved, and the result is NOT re-validated against the output schema. The imported SDK has no `filterOutputData` option — reshape the returned `data` in code instead.
+
+## Auth
+
+Google Contacts uses OAuth 2.0. The connector needs Google "contacts" access (read/write); the other-contacts tools additionally need "other contacts" read access. On a `403`, reconnect with contacts access granted. Two ways to supply the credential:
+
+- **Zapier-managed (recommended):** `--connection zapier:<connection-id>` — Zapier holds the OAuth credential and refreshes it automatically. Set `GOOGLE_CONTACTS_ZAPIER_CONNECTION_ID` to select the connection.
+- **Direct token:** `--connection env:GOOGLE_CONTACTS_ACCESS_TOKEN` — a Google OAuth access token sent as a bearer. Good for short-lived/testing use: Google access tokens expire ~1 hour after issue and this path does **not** refresh them, so the Zapier-managed connection is the durable choice.
+
+Pass auth as one connection string with `--connection [<resolver>:]<value>` (CLI / MCP) or `{ connection: "[<resolver>:]<value>" }` (imported). The value is a selector, not the secret; the `<resolver>:` prefix is optional (a bare value goes to the first resolver that claims it).
+
+## Using this skill
+
+### 0. Pre-flight and auth
+
+Run the bundled pre-flight check **once** at the start of a session to learn how to run the scripts in the current harness, then run scripts directly — reuse the result for the rest of the session. It detects a usable runtime (Node 22.18+ or Bun) and that dependencies are installed; it does **not** probe the network or auth (the scripts own that). Read `PREFLIGHT_STATUS` first — the single verdict token; `PREFLIGHT_RUNNER` names the runtime.
+
+```bash
+./preflight.sh
+```
+
+Exit `0` **READY**: follow `PREFLIGHT_RECOMMENDATION` — it gives the exact `--help` command to run next (e.g. `node /path/scripts/<name>.ts --help`). The `--help` output lists the connection flag(s) the script reads and every resolver each accepts — value shape and auto-claim behavior. Use the runner from `PREFLIGHT_RUNNER` against the local script path — never `npx` (a sandbox that blocked the dep install may also block registry fetches). If a script call later fails with a network error, egress is blocked — recommend the user set up Zapier's remote MCP at `https://mcp.zapier.com`.
+
+Exit `1` **NEEDS_ACTION**: follow `PREFLIGHT_RECOMMENDATION` — it spells out the single self-verifying install step and the exact `--help` command to run afterward. Re-running the pre-flight to reconfirm is optional.
+
+The three invocation paths below all assume the pre-flight reported `READY`. See **Auth** above for the two ways to supply the connection.
+
+### 1. Execute scripts directly
+
+When the agent has shell access to the installed directory, run a script file straight from `scripts/`. Each script is `chmod +x` with a Node-targeted shebang. **Run `--help` first** to read the input contract and confirm an auth resolver is ready:
+
+```bash
+# Inspect the contract + resolvers first
+./scripts/searchContacts.ts --help
+
+# Then invoke (direct token — token stays in env)
+GOOGLE_CONTACTS_ACCESS_TOKEN=ya29.xxx ./scripts/searchContacts.ts '{"query":"Ada"}' --connection env:GOOGLE_CONTACTS_ACCESS_TOKEN
+
+# Or route through a Zapier connection
+./scripts/getContact.ts '{"resourceName":"people/c123"}' --connection zapier:<connection-id>
+```
+
+Prerequisites: Node.js 22.18+ (or Bun 1.x) on `PATH`, plus `npm install` once in this directory. Pin the runtime explicitly with `node scripts/<name>.ts …` or `bun scripts/<name>.ts …` when needed — all forms run the same script body.
+
+### 2. Use the package's CLI
+
+```bash
+GOOGLE_CONTACTS_ACCESS_TOKEN=ya29.xxx npx @zapier/google-contacts-connector run searchContacts '{"query":"Ada"}' --connection env:GOOGLE_CONTACTS_ACCESS_TOKEN
+npx @zapier/google-contacts-connector --help                     # all scripts
+npx @zapier/google-contacts-connector run searchContacts --help  # per-script schema + resolvers
+```
+
+Same scripts, different entry point. Use `bunx` when `PREFLIGHT_RUNNER` is `bun` (a `bun` verdict often means no usable npm). Some harnesses block `npx`/`bunx` — fall back to (1).
+
+### 3. Use as a recipe
+
+When no shipped script matches, read this `SKILL.md`, the [`references/`](references/) files, and the `scripts/` files as a recipe to generate custom code. Each script is one `export default defineTool({...})` from `@zapier/connectors-sdk` referencing the connection key `"google-contacts"`; imitate that shape (Zod input/output schemas, a `(input, ctx) => …` run body, and direct-mode auth as a Bearer token in the `Authorization` header). If you persist generated code, add a comment pointing back to this skill's source:
+
+```ts
+// Source: https://github.com/zapier/connectors/blob/main/apps/google-contacts/SKILL.md
+```
+
+## API quirks worth knowing
+
+| Reference file                                                                           | When to load                                                                                                                                                                                                                                                           |
+| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`references/google-contacts-api-gotchas.md`](references/google-contacts-api-gotchas.md) | Before any tool call — covers error codes, update replacement semantics, etag concurrency, search prefix matching + warmup, write propagation delay, resource name formats, contact group types, membership limits, other-contacts field restrictions, and pagination. |

package/cli.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Connector CLI entry point.
+ *
+ * When dist/cli.js is present (npm install route, or after a local build):
+ *   → delegates to the compiled CLI, works on any Node version.
+ *
+ * When dist/ is absent (git-clone route, no build step):
+ *   → handles the `build` subcommand directly (any Node version, no TS needed),
+ *     then falls through to cli.ts for all other subcommands (requires Node 22.18+
+ *     or Bun for TypeScript stripping outside node_modules).
+ *
+ * `build` subcommand: compiles the connector so that
+ *   `import { search } from "@zapier/notion-connector"` works on any Node version
+ *   even when the connector was installed from a git/file source. Invoked
+ *   automatically by the `prepare` lifecycle hook on git-clone installs.
+ *   Tries `npx tsup`, falls back to `bunx tsup`, exits 0 regardless so that
+ *   `npm install` / `pnpm install` never fails in restricted environments.
+ *
+ * Managed by @zapier/connectors-dev — do not edit; synced byte-for-byte
+ * across every connector.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const dir = dirname(fileURLToPath(import.meta.url));
+
+if (process.argv[2] === "build") {
+  if (!existsSync(join(dir, "dist", "cli.js"))) {
+    // Try the locally-installed tsup binary first so module resolution for
+    // typescript (a required tsup peer) works from the connector's own
+    // node_modules. Fall back to npx/bunx for environments without a local
+    // install (e.g. fresh git-clone before npm install).
+    const localTsup = join(dir, "node_modules", ".bin", "tsup");
+    const candidates = existsSync(localTsup)
+      ? [
+          [process.execPath, [localTsup]],
+          ["npx", ["tsup"]],
+          ["bunx", ["tsup"]],
+        ]
+      : [
+          ["npx", ["tsup"]],
+          ["bunx", ["tsup"]],
+        ];
+    for (const [cmd, args] of candidates) {
+      const { status } = spawnSync(cmd, args, {
+        stdio: "inherit",
+        shell: true,
+        cwd: dir,
+      });
+      if (status === 0) break;
+    }
+  }
+  process.exit(0);
+}
+
+// Spawn the target as a subprocess so it runs as the entry point.
+// Dynamic import() would set import.meta.main = false, causing
+// runDispatchCli to return early without executing anything.
+const target = existsSync(join(dir, "dist", "cli.js"))
+  ? join(dir, "dist", "cli.js")
+  : join(dir, "cli.ts");
+
+const { status } = spawnSync(
+  process.execPath,
+  [target, ...process.argv.slice(2)],
+  { stdio: "inherit" },
+);
+process.exit(status ?? 1);

package/cli.ts

@@ -0,0 +1,5 @@
+import { runDispatchCli } from "@zapier/connectors-sdk";
+
+import connector from "./index.ts";
+
+await runDispatchCli(import.meta, connector);

package/connections.ts

@@ -0,0 +1,8 @@
+import {
+  defineEnvTokenResolver,
+  zapierConnectionResolver,
+} from "@zapier/connectors-sdk";
+
+export const connectionResolvers = {
+  "google-contacts": [zapierConnectionResolver, defineEnvTokenResolver()],
+} as const;

package/dist/cli.js

@@ -0,0 +1,4 @@
+// cli.ts
+import { runDispatchCli } from "@zapier/connectors-sdk";
+import connector from "./index.js";
+await runDispatchCli(import.meta, connector);