@zapier/trello-connector 0.0.0 → 0.1.0

package/index.ts

@@ -0,0 +1,145 @@
+import { defineConnector, toFunctions } from "@zapier/connectors-sdk";
+
+import { connectionResolvers } from "./connections.ts";
+import addCardAttachmentDefinition from "./scripts/addCardAttachment.ts";
+import addCardLabelDefinition from "./scripts/addCardLabel.ts";
+import addCardMemberDefinition from "./scripts/addCardMember.ts";
+import addChecklistItemDefinition from "./scripts/addChecklistItem.ts";
+import addMemberToBoardDefinition from "./scripts/addMemberToBoard.ts";
+import archiveCardDefinition from "./scripts/archiveCard.ts";
+import closeBoardDefinition from "./scripts/closeBoard.ts";
+import completeChecklistItemDefinition from "./scripts/completeChecklistItem.ts";
+import copyBoardDefinition from "./scripts/copyBoard.ts";
+import createBoardDefinition from "./scripts/createBoard.ts";
+import createCardDefinition from "./scripts/createCard.ts";
+import createChecklistDefinition from "./scripts/createChecklist.ts";
+import createCommentDefinition from "./scripts/createComment.ts";
+import createLabelDefinition from "./scripts/createLabel.ts";
+import createListDefinition from "./scripts/createList.ts";
+import deleteChecklistDefinition from "./scripts/deleteChecklist.ts";
+import findBoardDefinition from "./scripts/findBoard.ts";
+import findChecklistDefinition from "./scripts/findChecklist.ts";
+import findChecklistItemDefinition from "./scripts/findChecklistItem.ts";
+import findLabelDefinition from "./scripts/findLabel.ts";
+import findListDefinition from "./scripts/findList.ts";
+import findOrganizationMemberDefinition from "./scripts/findOrganizationMember.ts";
+import getActionDefinition from "./scripts/getAction.ts";
+import getBoardDefinition from "./scripts/getBoard.ts";
+import getCardDefinition from "./scripts/getCard.ts";
+import getChecklistDefinition from "./scripts/getChecklist.ts";
+import getChecklistItemDefinition from "./scripts/getChecklistItem.ts";
+import getCurrentMemberDefinition from "./scripts/getCurrentMember.ts";
+import getLabelDefinition from "./scripts/getLabel.ts";
+import getListDefinition from "./scripts/getList.ts";
+import getMemberDefinition from "./scripts/getMember.ts";
+import getOrganizationDefinition from "./scripts/getOrganization.ts";
+import listBoardMembersDefinition from "./scripts/listBoardMembers.ts";
+import listBoardsDefinition from "./scripts/listBoards.ts";
+import listCardAttachmentsDefinition from "./scripts/listCardAttachments.ts";
+import listCardsDefinition from "./scripts/listCards.ts";
+import listCustomFieldsDefinition from "./scripts/listCustomFields.ts";
+import listLabelsDefinition from "./scripts/listLabels.ts";
+import listListsDefinition from "./scripts/listLists.ts";
+import listOrganizationsDefinition from "./scripts/listOrganizations.ts";
+import moveCardDefinition from "./scripts/moveCard.ts";
+import removeCardLabelDefinition from "./scripts/removeCardLabel.ts";
+import searchCardsDefinition from "./scripts/searchCards.ts";
+import updateCardDefinition from "./scripts/updateCard.ts";
+
+const connector = defineConnector({
+  scripts: {
+    addCardAttachment: addCardAttachmentDefinition,
+    addCardLabel: addCardLabelDefinition,
+    addCardMember: addCardMemberDefinition,
+    addChecklistItem: addChecklistItemDefinition,
+    addMemberToBoard: addMemberToBoardDefinition,
+    archiveCard: archiveCardDefinition,
+    closeBoard: closeBoardDefinition,
+    completeChecklistItem: completeChecklistItemDefinition,
+    copyBoard: copyBoardDefinition,
+    createBoard: createBoardDefinition,
+    createCard: createCardDefinition,
+    createChecklist: createChecklistDefinition,
+    createComment: createCommentDefinition,
+    createLabel: createLabelDefinition,
+    createList: createListDefinition,
+    deleteChecklist: deleteChecklistDefinition,
+    findBoard: findBoardDefinition,
+    findChecklist: findChecklistDefinition,
+    findChecklistItem: findChecklistItemDefinition,
+    findLabel: findLabelDefinition,
+    findList: findListDefinition,
+    findOrganizationMember: findOrganizationMemberDefinition,
+    getAction: getActionDefinition,
+    getBoard: getBoardDefinition,
+    getCard: getCardDefinition,
+    getChecklist: getChecklistDefinition,
+    getChecklistItem: getChecklistItemDefinition,
+    getCurrentMember: getCurrentMemberDefinition,
+    getLabel: getLabelDefinition,
+    getList: getListDefinition,
+    getMember: getMemberDefinition,
+    getOrganization: getOrganizationDefinition,
+    listBoardMembers: listBoardMembersDefinition,
+    listBoards: listBoardsDefinition,
+    listCardAttachments: listCardAttachmentsDefinition,
+    listCards: listCardsDefinition,
+    listCustomFields: listCustomFieldsDefinition,
+    listLabels: listLabelsDefinition,
+    listLists: listListsDefinition,
+    listOrganizations: listOrganizationsDefinition,
+    moveCard: moveCardDefinition,
+    removeCardLabel: removeCardLabelDefinition,
+    searchCards: searchCardsDefinition,
+    updateCard: updateCardDefinition,
+  },
+  connectionResolvers,
+});
+
+export default connector;
+export const {
+  addCardAttachment,
+  addCardLabel,
+  addCardMember,
+  addChecklistItem,
+  addMemberToBoard,
+  archiveCard,
+  closeBoard,
+  completeChecklistItem,
+  copyBoard,
+  createBoard,
+  createCard,
+  createChecklist,
+  createComment,
+  createLabel,
+  createList,
+  deleteChecklist,
+  findBoard,
+  findChecklist,
+  findChecklistItem,
+  findLabel,
+  findList,
+  findOrganizationMember,
+  getAction,
+  getBoard,
+  getCard,
+  getChecklist,
+  getChecklistItem,
+  getCurrentMember,
+  getLabel,
+  getList,
+  getMember,
+  getOrganization,
+  listBoardMembers,
+  listBoards,
+  listCardAttachments,
+  listCards,
+  listCustomFields,
+  listLabels,
+  listLists,
+  listOrganizations,
+  moveCard,
+  removeCardLabel,
+  searchCards,
+  updateCard,
+} = toFunctions(connector);

package/package.json

@@ -1,7 +1,62 @@
 {
   "name": "@zapier/trello-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 Trello tools — create and update cards, manage boards, lists, labels, checklists, and search. Use when the user mentions Trello or wants to create cards, move tasks, or manage boards, even if they do not name Trello explicitly.",
   "license": "Elastic-2.0",
-  "private": false
-}
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./index.ts"
+    }
+  },
+  "bin": {
+    "@zapier/trello-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": [
+    "trello",
+    "zapier",
+    "connector",
+    "tools",
+    "skills",
+    "mcp",
+    "agent",
+    "ai",
+    "automation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zapier/connectors.git",
+    "directory": "apps/trello"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "version": "0.1.0",
+  "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/trello-api-gotchas.md

@@ -0,0 +1,81 @@
+# Trello API — gotchas & durable knowledge
+
+Per-app behavior the agent needs to call Trello's REST API correctly. Every claim
+here is sourced from [Trello's public developer documentation](https://developer.atlassian.com/cloud/trello/).
+Mechanical details (auth wiring, Zod shapes, connector helpers) live in code, not here.
+
+## Auth & tokens
+
+- **OAuth 1.0a via `Authorization` header.** Trello accepts
+  `Authorization: OAuth oauth_consumer_key="{{apiKey}}", oauth_token="{{apiToken}}"`
+  ([Authorization guide](https://developer.atlassian.com/cloud/trello/guides/rest-api/authorization/)).
+  Query `key=` / `token=` parameters and PUT/POST body fields are alternate paths; this connector uses the header.
+- **The API key is public; the token is secret.** "[An API key by itself doesn't grant access to a user's Trello data](https://developer.atlassian.com/cloud/trello/guides/rest-api/api-introduction/)"
+  but tokens grant full account access and "[should be kept secret](https://developer.atlassian.com/cloud/trello/guides/rest-api/authorization/)."
+- **Revoked or invalid tokens return 401.** When a token has been revoked, the API responds with HTTP 401 and
+  `invalid token`; integrations should prompt re-authorization
+  ([Authorization guide](https://developer.atlassian.com/cloud/trello/guides/rest-api/authorization/)).
+- **Member email requires `account` scope.** "[Member emails can only be accessed when the `account` scope is requested](https://developer.atlassian.com/cloud/trello/guides/rest-api/authorization/)."
+
+## Object IDs
+
+- **Trello ids are 24-character MongoDB ObjectIds** (hex). They appear on boards, lists, cards, members, labels, etc.
+  Search and list responses use the same shape (e.g. `"id": "5abbe4b7ddc1b351ef961414"` in the
+  [Search API reference](https://developer.atlassian.com/cloud/trello/rest/api-group-search/)).
+- **Resolve ids before writes.** List/find tools return candidate arrays; the agent must pick the correct id — the API does not auto-select a single match for you.
+
+## Rate limits
+
+- **300 requests per 10 seconds per API key; 100 per 10 seconds per token.**
+  ([Rate limits](https://developer.atlassian.com/cloud/trello/guides/rest-api/rate-limits/))
+- **429 responses name the limit.** Token exhaustion returns `{ "error": "API_TOKEN_LIMIT_EXCEEDED", ... }`;
+  key exhaustion returns `{ "error": "API_KEY_LIMIT_EXCEEDED", ... }`
+  ([Rate limits](https://developer.atlassian.com/cloud/trello/guides/rest-api/rate-limits/)).
+- **`/1/members/` has an extra limit: 100 requests per 900 seconds** (anti-enumeration)
+  ([Rate limits](https://developer.atlassian.com/cloud/trello/guides/rest-api/rate-limits/)).
+- **Search and member search are "special routes"** with stricter limits — use nested resources when possible
+  (e.g. `/1/boards/:id/members` instead of hammering `/1/members`)
+  ([Rate limits](https://developer.atlassian.com/cloud/trello/guides/rest-api/rate-limits/)).
+- **Honor `x-rate-limit-*` response headers** to stay within limits
+  ([Rate limits](https://developer.atlassian.com/cloud/trello/guides/rest-api/rate-limits/)).
+
+## Search
+
+- **`GET /1/search` requires a `query` string** and accepts `modelTypes` to restrict results to boards, cards, members, etc.
+  ([Search API](https://developer.atlassian.com/cloud/trello/rest/api-group-search/)).
+- **Use search sparingly** — it counts against special-route limits; prefer list/find on a known board when the scope is narrow.
+- **Member search is a separate endpoint:** `GET /1/search/members/` with `query`, optional `idBoard` / `idOrganization`
+  ([Search API](https://developer.atlassian.com/cloud/trello/rest/api-group-search/)).
+
+## Nested resources & pagination
+
+- **Prefer nested routes over many single-object GETs.** Example: all cards on a board via
+  `GET /1/boards/{boardId}/cards` instead of iterating individual card ids
+  ([Nested resources](https://developer.atlassian.com/cloud/trello/guides/rest-api/nested-resources/),
+  [Rate limits — Working With Rate Limits](https://developer.atlassian.com/cloud/trello/guides/rest-api/rate-limits/)).
+- **Card list endpoints support cursor-style paging** via `before` (card id) and `limit` — return one page and loop explicitly; do not assume full-board hydration in one call.
+- **Large action loads can fail.** Requesting all board cards with `actions=all` may hit
+  `API_TOO_MANY_CARDS_REQUESTED`; fetch actions in follow-up calls
+  ([Rate limits — Response Size Limits](https://developer.atlassian.com/cloud/trello/guides/rest-api/rate-limits/)).
+
+## Cards, lists, and boards
+
+- **Creating a card requires `idList`.** `POST /1/cards` takes `idList` (and optional name, desc, due, etc.)
+  ([Cards API](https://developer.atlassian.com/cloud/trello/rest/api-group-cards/)).
+- **`closed: true` archives a card or board** (soft-close). There is no hard-delete tool in this connector; reopen with `closed: false` via update tools.
+- **Moving a card changes `idList` (and optionally `idBoard`).** Resolve the destination list id via `listLists` or `findList` before calling move/update.
+- **Comments are actions.** Adding a comment creates a `commentCard` action on the card; `getAction` retrieves it by action id.
+
+## Writes & attachments
+
+- **POST/PUT bodies may use JSON or form fields.** The authorization guide shows JSON bodies with embedded `key`/`token`;
+  many Trello write endpoints also accept standard form fields. Prefer `application/x-www-form-urlencoded` for writes when the API accepts it.
+- **URL attachments vs file upload.** This connector's `addCardAttachment` accepts a URL or remote file URL — not local binary upload. Multipart upload is out of scope.
+
+## Connector output shape
+
+- **List/find tools return `{ items: [...] }`.** The SDK requires object-shaped outputs; array results are wrapped — read `.items`, not the raw top-level array.
+
+## Out of scope (say so, don't fake it)
+
+- Webhooks, Butler automations, Power-Ups admin, enterprise governance APIs, and batch/plugin-only surfaces are not exposed by this connector.

package/scripts/addCardAttachment.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// Authored by the implementation agent: multipart file upload or URL form POST to
+// POST /cards/{id}/attachments — outside codegen's single JSON-call model.
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  TRELLO_BASE,
+  TRELLO_ID_REGEX,
+  trelloError,
+  trelloFormBody,
+  trelloFormHeaders,
+} from "../lib/trello.ts";
+
+const inputSchema = z
+  .object({
+    id: z.string().describe("24-char hex card id."),
+    url: z
+      .string()
+      .url()
+      .describe(
+        "URL to attach (link attachment). Mutually exclusive with fileUrl.",
+      )
+      .optional(),
+    fileUrl: z
+      .string()
+      .url()
+      .describe(
+        "Remote file URL to download and upload. Mutually exclusive with url.",
+      )
+      .optional(),
+    name: z.string().describe("Attachment display name.").optional(),
+    mimeType: z.string().optional(),
+  })
+  .strict()
+  .refine((v) => (v.url ? !v.fileUrl : !!v.fileUrl), {
+    message: "Provide exactly one of url or fileUrl.",
+  });
+
+const outputSchema = z.object({
+  id: z.string().regex(TRELLO_ID_REGEX),
+  name: z.string(),
+  url: z.string(),
+  mimeType: z.string().nullable().optional(),
+  bytes: z.number().nullable().optional(),
+  isUpload: z.boolean().nullable().optional(),
+});
+
+const definition = defineTool({
+  name: "addCardAttachment",
+  title: "Add Card Attachment",
+  description:
+    "Add a URL link attachment or upload a file from a remote URL to a card. Provide url OR fileUrl, not both.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "trello",
+  run: async (input, ctx) => {
+    const cardPath = `${TRELLO_BASE}/cards/${encodeURIComponent(input.id)}/attachments`;
+
+    if (input.fileUrl) {
+      const fileRes = await ctx.fetch(input.fileUrl);
+      if (!fileRes.ok) await trelloError("addCardAttachment", fileRes);
+      const buffer = await fileRes.arrayBuffer();
+      const fileName = input.name ?? "attachment";
+      const form = new FormData();
+      form.append(
+        "file",
+        new Blob([buffer], {
+          type:
+            input.mimeType ?? fileRes.headers.get("content-type") ?? undefined,
+        }),
+        fileName,
+      );
+      form.append("name", fileName);
+      if (input.mimeType) form.append("mimeType", input.mimeType);
+      const uploadRes = await ctx.fetch(cardPath, {
+        method: "POST",
+        body: form,
+      });
+      if (!uploadRes.ok) await trelloError("addCardAttachment", uploadRes);
+      return uploadRes.json() as Promise<z.infer<typeof outputSchema>>;
+    }
+
+    const linkRes = await ctx.fetch(cardPath, {
+      method: "POST",
+      headers: trelloFormHeaders,
+      body: trelloFormBody({
+        url: input.url!,
+        name: input.name ?? input.url!,
+        mimeType: input.mimeType,
+      }),
+    });
+    if (!linkRes.ok) await trelloError("addCardAttachment", linkRes);
+    return linkRes.json() as Promise<z.infer<typeof outputSchema>>;
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/addCardLabel.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+
+const inputSchema = z
+  .object({
+    id: z.string().describe("24-char hex card id."),
+    value: z.string().describe("Label id from listLabels."),
+  })
+  .strict();
+const outputSchema = z.object({
+  id: z
+    .string()
+    .regex(new RegExp("^[0-9a-fA-F]{24}$"))
+    .describe("Trello object id (24 hex chars)."),
+  name: z.string(),
+  desc: z.string().nullable().optional(),
+  closed: z.boolean().nullable().optional(),
+  idBoard: z.string(),
+  idList: z.string(),
+  idShort: z.number().int().nullable().optional(),
+  shortLink: z.string().nullable().optional(),
+  shortUrl: z.string().nullable().optional(),
+  url: z.string().nullable().optional(),
+  due: z.union([z.string().datetime({ offset: true }), z.null()]).optional(),
+  dueComplete: z.boolean().nullable().optional(),
+  dateLastActivity: z.string().datetime({ offset: true }).nullable().optional(),
+  idLabels: z.array(z.string()).nullable().optional(),
+  idMembers: z.array(z.string()).nullable().optional(),
+  labels: z
+    .array(
+      z.object({
+        id: z
+          .string()
+          .regex(new RegExp("^[0-9a-fA-F]{24}$"))
+          .describe("Trello object id (24 hex chars)."),
+        idBoard: z.string(),
+        name: z.string().nullable().optional(),
+        color: z.string().nullable().optional(),
+      }),
+    )
+    .nullable()
+    .optional(),
+  pos: z.number().nullable().optional(),
+  customFields: z
+    .record(z.string(), z.any())
+    .nullable()
+    .describe("Custom field values keyed by field name when requested.")
+    .optional(),
+});
+
+const definition = defineTool({
+  name: "addCardLabel",
+  title: "Add Card Label",
+  description: "Add an existing board label to a card by label id.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "trello",
+  run: async (input, ctx) => {
+    const url = `https://api.trello.com/1/cards/${encodeURIComponent(input.id)}/idLabels`;
+    const body: Record<string, unknown> = {};
+    if (input.value !== undefined) body["value"] = input.value;
+    const res = await ctx.fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const errBody = await res.text();
+      throw new Error(`Trello addCardLabel ${res.status}: ${errBody}`);
+    }
+    const cardRes = await ctx.fetch(
+      `https://api.trello.com/1/cards/${encodeURIComponent(input.id)}`,
+    );
+    if (!cardRes.ok) {
+      const errBody = await cardRes.text();
+      throw new Error(`Trello addCardLabel ${cardRes.status}: ${errBody}`);
+    }
+    return cardRes.json();
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });