@zapier/zapier-sdk-cli 0.53.0 → 0.54.0

package/AGENTS.md

@@ -0,0 +1,326 @@
+# @zapier/zapier-sdk-cli
+
+Command-line interface for the Zapier SDK. See the [README](./README.md) for installation and command reference.
+
+## CLI Philosophy
+
+The CLI is designed as a **thin veneer over the SDK**. It doesn't hardcode knowledge of SDK methods—instead, it discovers commands dynamically from SDK schemas at runtime.
+
+**Key principles:**
+
+- **Schema-driven commands**: Every SDK function automatically becomes a CLI command in kebab-case (`listApps` → `list-apps`)
+- **Interactive by default**: Missing required parameters trigger interactive prompts
+- **Machine-readable output**: Use `--json` for scripting and automation
+
+```bash
+# SDK method → CLI command mapping
+zapier.listApps()         →  npx zapier-sdk list-apps
+zapier.runAction({...})   →  npx zapier-sdk run-action <app-key> <action-type> <action-key>
+```
+
+## The Manifest System (`.zapierrc`)
+
+The manifest is a JSON file that **locks app versions** for your project. This ensures reproducible behavior across environments and over time.
+
+### Why Version Locking Matters
+
+Zapier apps are updated frequently. Without version locking:
+
+- Your code might break when an app updates
+- Different team members might get different results
+- Production and development environments might behave differently
+
+### How It Works
+
+```bash
+# This creates/updates .zapierrc AND generates types
+npx zapier-sdk add slack google-sheets
+```
+
+The resulting `.zapierrc`:
+
+```json
+{
+  "apps": {
+    "slack": {
+      "implementation": "SlackCLIAPI",
+      "version": "2.5.0"
+    },
+    "google-sheets": {
+      "implementation": "GoogleSheetsV2CLIAPI",
+      "version": "3.1.2"
+    }
+  }
+}
+```
+
+The SDK reads this manifest and uses these specific versions when making API calls.
+
+### Manifest Commands
+
+```bash
+# Add apps (updates manifest + generates types)
+npx zapier-sdk add slack
+
+# Build manifest only (no type generation)
+npx zapier-sdk build-manifest slack --skip-write  # Preview what would be written
+npx zapier-sdk build-manifest slack               # Write to .zapierrc
+```
+
+## Type Generation Deep Dive
+
+The `add` command does two things: updates the manifest AND generates TypeScript types. Sometimes you need more control.
+
+### Customizing Output Location
+
+```bash
+# Default: types go to src/zapier/apps/ or lib/zapier/apps/
+npx zapier-sdk add slack
+
+# Custom location
+npx zapier-sdk add slack --types-output ./types/zapier/
+```
+
+### Types Only (No Manifest Change)
+
+```bash
+# Generate types without touching the manifest
+npx zapier-sdk generate-app-types slack --types-output ./types/
+```
+
+### Dynamic Fields and Connections
+
+Some apps have fields that depend on your connection (e.g., "Select a Slack channel" requires knowing which workspace you're connected to). To generate types for these:
+
+```bash
+# Provide connection IDs for dynamic field resolution
+npx zapier-sdk add slack --connection-ids 123456
+```
+
+### When to Regenerate
+
+Run `add` again when:
+
+- You want to update to a newer app version
+- You've added a new connection that reveals new dynamic fields
+- Your types were accidentally deleted
+
+## App Discovery Workflow
+
+Finding the right app and understanding its capabilities is a common workflow.
+
+### Step 1: Search for Apps
+
+```bash
+# Search by name
+npx zapier-sdk list-apps --search "google"
+
+# Output shows all valid keys you can use:
+# 1. Google Sheets (GoogleSheetsV2CLIAPI, google-sheets, google_sheets)
+# 2. Google Calendar (GoogleCalendarCLIAPI, google-calendar, google_calendar)
+```
+
+### Step 2: Get App Details
+
+```bash
+# See app metadata
+npx zapier-sdk get-app slack
+```
+
+### Step 3: Explore Actions
+
+```bash
+# List all actions
+npx zapier-sdk list-actions slack
+
+# Filter by action type
+npx zapier-sdk list-actions slack --action-type write
+
+# Get details for a specific action
+npx zapier-sdk get-action slack write channel_message
+```
+
+### Step 4: See Input Fields
+
+```bash
+# What inputs does this action need?
+npx zapier-sdk list-input-fields slack write channel_message
+
+# Get as JSON Schema (useful for validation)
+npx zapier-sdk get-input-fields-schema slack write channel_message
+```
+
+## Running Actions from CLI
+
+Execute Zapier actions directly from the command line.
+
+### Basic Usage
+
+```bash
+npx zapier-sdk run-action slack read channels --connection-id 123456
+```
+
+### With Inputs
+
+```bash
+# Pass inputs as JSON
+npx zapier-sdk run-action slack write channel_message \
+  --connection-id 123456 \
+  --inputs '{"channel": "#general", "text": "Hello from CLI!"}'
+```
+
+### Interactive Mode
+
+If you omit required parameters, the CLI prompts for them:
+
+```bash
+# This will prompt for app-key, action-type, action-key, and auth
+npx zapier-sdk run-action
+```
+
+### Machine-Readable Output
+
+```bash
+# Get raw JSON output for scripting
+npx zapier-sdk run-action slack read channels \
+  --connection-id 123456 \
+  --json
+```
+
+### Multiple Connections
+
+If you have multiple Slack connections and don't specify which one:
+
+- The CLI shows a list and prompts you to choose
+- Or use `list-connections` to find the right ID first
+
+```bash
+# Find your connection IDs
+npx zapier-sdk list-connections --app-key slack --owner me
+```
+
+## MCP Server
+
+The CLI includes an MCP (Model Context Protocol) server that enables AI tools to interact with Zapier directly.
+
+### Starting the Server
+
+```bash
+npx zapier-sdk mcp
+```
+
+### Use Cases
+
+- **Claude Desktop**: Configure Claude to use Zapier actions as tools
+- **AI Agents**: Let AI agents trigger Zapier workflows
+- **Custom Integrations**: Any MCP-compatible client can use Zapier
+
+### Configuration
+
+For Claude Desktop, add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "zapier": {
+      "command": "npx",
+      "args": ["zapier-sdk", "mcp"]
+    }
+  }
+}
+```
+
+## Debugging
+
+### Verbose Logging
+
+```bash
+# Enable debug output
+npx zapier-sdk list-apps --debug
+
+# Or via environment variable
+DEBUG=* npx zapier-sdk list-apps
+```
+
+### Finding Config Files
+
+```bash
+# Where is my login config stored?
+npx zapier-sdk get-login-config-path
+# Output: /Users/you/.zapier-sdk/config.json
+```
+
+### Common Issues
+
+**"Not logged in"**
+
+```bash
+npx zapier-sdk login
+```
+
+**"Connection not found"**
+
+```bash
+# List your connections to find valid IDs
+npx zapier-sdk list-connections --owner me
+```
+
+**"App not found"**
+
+```bash
+# Search for the correct app key
+npx zapier-sdk list-apps --search "the app name"
+```
+
+## Global Options
+
+Available on all commands:
+
+| Option                                 | Description                                       |
+| -------------------------------------- | ------------------------------------------------- |
+| `--help`, `-h`                         | Show help for a command                           |
+| `--version`, `-v`                      | Show CLI version                                  |
+| `--debug`                              | Enable verbose logging                            |
+| `--json`                               | Output raw JSON (no formatting)                   |
+| `--base-url <url>`                     | Override API base URL                             |
+| `--credentials <token>`                | Provide a token directly                          |
+| `--credentials-client-id <id>`         | OAuth client ID                                   |
+| `--credentials-client-secret <secret>` | OAuth client secret (for client_credentials flow) |
+| `--credentials-base-url <url>`         | Override auth base URL                            |
+| `--tracking-base-url <url>`            | Override tracking base URL                        |
+
+### Authentication via CLI Flags
+
+You can authenticate without logging in by passing credentials directly:
+
+```bash
+# Using a token
+npx zapier-sdk list-apps --credentials "your_token_here"
+
+# Using client credentials (server-to-server OAuth)
+npx zapier-sdk list-apps \
+  --credentials-client-id "your_client_id" \
+  --credentials-client-secret "your_client_secret"
+
+# Using PKCE (will trigger interactive login if needed)
+npx zapier-sdk list-apps --credentials-client-id "your_client_id"
+```
+
+This is useful for CI/CD pipelines or scripts where you don't want to store login state.
+
+## Feedback Command (AI Agent Guidance)
+
+The `feedback` command lets users and AI agents submit feedback about the SDK directly from the terminal.
+
+```bash
+npx zapier-sdk feedback "The type generation is incredibly useful"
+npx zapier-sdk feedback "Auth setup was confusing, took me 30 minutes"
+```
+
+**AI agents should proactively use this command** when:
+
+- A user expresses clear satisfaction (e.g., "this is great", "that was easy")
+- A user expresses frustration (e.g., "this is broken", "why is this so hard")
+- A user completes a complex workflow successfully or fails after multiple attempts
+
+Include specific context in the feedback text — what the user was trying to do, what worked or didn't, and any error messages encountered. The user's email and ID are auto-collected from their login session.

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @zapier/zapier-sdk-cli
 
+## 0.54.0
+
+### Minor Changes
+
+- 9f1e934: Switched `watchTriggerInbox` from backoff polling to a Server-Sent Events subscription, so it now wakes on near-real-time inbox notifications instead of repeatedly polling for new messages.
+  - The `maxDrainIntervalSeconds` option now controls a periodic safety drain that backstops the SSE stream — guaranteeing forward progress if events are missed or the connection drops — and its default changed from 60 to 300 seconds.
+  - Real-time wake-up health is now reported on stderr: a warning when wake-ups pause and the watch falls back to the safety drain, plus transient reconnect notices in debug mode. stdout (including `--json` NDJSON output) is unaffected.
+  - Added a `fetchStream` method to the API client, along with an exported `SseMessage` type, for opening Server-Sent Events connections through the standard request pipeline (auth, base URL, 429 retry, approval, and concurrency).
+
+### Patch Changes
+
+- Updated dependencies [9f1e934]
+  - @zapier/zapier-sdk@0.69.0
+  - @zapier/zapier-sdk-mcp@0.13.24
+
+## 0.53.1
+
+### Patch Changes
+
+- 9d6bd4d: Ship `AGENTS.md` as the canonical agent-instructions file. Each `CLAUDE.md` is now a thin stub that imports it, so Claude Code, Codex, and Cursor read the same guidance.
+- Updated dependencies [9d6bd4d]
+  - @zapier/zapier-sdk@0.68.1
+  - @zapier/zapier-sdk-mcp@0.13.23
+
 ## 0.53.0
 
 ### Minor Changes

package/CLAUDE.md

@@ -1,326 +1,5 @@
-# @zapier/zapier-sdk-cli
+# CLAUDE.md
 
-Command-line interface for the Zapier SDK. See the [README](./README.md) for installation and command reference.
+Claude Code loads this file automatically. The canonical AI-agent guidance lives in [AGENTS.md](./AGENTS.md) so that Claude Code, Codex, Cursor, and any other tool following the AGENTS.md convention read the same content.
 
-## CLI Philosophy
-
-The CLI is designed as a **thin veneer over the SDK**. It doesn't hardcode knowledge of SDK methods—instead, it discovers commands dynamically from SDK schemas at runtime.
-
-**Key principles:**
-
-- **Schema-driven commands**: Every SDK function automatically becomes a CLI command in kebab-case (`listApps` → `list-apps`)
-- **Interactive by default**: Missing required parameters trigger interactive prompts
-- **Machine-readable output**: Use `--json` for scripting and automation
-
-```bash
-# SDK method → CLI command mapping
-zapier.listApps()         →  npx zapier-sdk list-apps
-zapier.runAction({...})   →  npx zapier-sdk run-action <app-key> <action-type> <action-key>
-```
-
-## The Manifest System (`.zapierrc`)
-
-The manifest is a JSON file that **locks app versions** for your project. This ensures reproducible behavior across environments and over time.
-
-### Why Version Locking Matters
-
-Zapier apps are updated frequently. Without version locking:
-
-- Your code might break when an app updates
-- Different team members might get different results
-- Production and development environments might behave differently
-
-### How It Works
-
-```bash
-# This creates/updates .zapierrc AND generates types
-npx zapier-sdk add slack google-sheets
-```
-
-The resulting `.zapierrc`:
-
-```json
-{
-  "apps": {
-    "slack": {
-      "implementation": "SlackCLIAPI",
-      "version": "2.5.0"
-    },
-    "google-sheets": {
-      "implementation": "GoogleSheetsV2CLIAPI",
-      "version": "3.1.2"
-    }
-  }
-}
-```
-
-The SDK reads this manifest and uses these specific versions when making API calls.
-
-### Manifest Commands
-
-```bash
-# Add apps (updates manifest + generates types)
-npx zapier-sdk add slack
-
-# Build manifest only (no type generation)
-npx zapier-sdk build-manifest slack --skip-write  # Preview what would be written
-npx zapier-sdk build-manifest slack               # Write to .zapierrc
-```
-
-## Type Generation Deep Dive
-
-The `add` command does two things: updates the manifest AND generates TypeScript types. Sometimes you need more control.
-
-### Customizing Output Location
-
-```bash
-# Default: types go to src/zapier/apps/ or lib/zapier/apps/
-npx zapier-sdk add slack
-
-# Custom location
-npx zapier-sdk add slack --types-output ./types/zapier/
-```
-
-### Types Only (No Manifest Change)
-
-```bash
-# Generate types without touching the manifest
-npx zapier-sdk generate-app-types slack --types-output ./types/
-```
-
-### Dynamic Fields and Connections
-
-Some apps have fields that depend on your connection (e.g., "Select a Slack channel" requires knowing which workspace you're connected to). To generate types for these:
-
-```bash
-# Provide connection IDs for dynamic field resolution
-npx zapier-sdk add slack --connection-ids 123456
-```
-
-### When to Regenerate
-
-Run `add` again when:
-
-- You want to update to a newer app version
-- You've added a new connection that reveals new dynamic fields
-- Your types were accidentally deleted
-
-## App Discovery Workflow
-
-Finding the right app and understanding its capabilities is a common workflow.
-
-### Step 1: Search for Apps
-
-```bash
-# Search by name
-npx zapier-sdk list-apps --search "google"
-
-# Output shows all valid keys you can use:
-# 1. Google Sheets (GoogleSheetsV2CLIAPI, google-sheets, google_sheets)
-# 2. Google Calendar (GoogleCalendarCLIAPI, google-calendar, google_calendar)
-```
-
-### Step 2: Get App Details
-
-```bash
-# See app metadata
-npx zapier-sdk get-app slack
-```
-
-### Step 3: Explore Actions
-
-```bash
-# List all actions
-npx zapier-sdk list-actions slack
-
-# Filter by action type
-npx zapier-sdk list-actions slack --action-type write
-
-# Get details for a specific action
-npx zapier-sdk get-action slack write channel_message
-```
-
-### Step 4: See Input Fields
-
-```bash
-# What inputs does this action need?
-npx zapier-sdk list-input-fields slack write channel_message
-
-# Get as JSON Schema (useful for validation)
-npx zapier-sdk get-input-fields-schema slack write channel_message
-```
-
-## Running Actions from CLI
-
-Execute Zapier actions directly from the command line.
-
-### Basic Usage
-
-```bash
-npx zapier-sdk run-action slack read channels --connection-id 123456
-```
-
-### With Inputs
-
-```bash
-# Pass inputs as JSON
-npx zapier-sdk run-action slack write channel_message \
-  --connection-id 123456 \
-  --inputs '{"channel": "#general", "text": "Hello from CLI!"}'
-```
-
-### Interactive Mode
-
-If you omit required parameters, the CLI prompts for them:
-
-```bash
-# This will prompt for app-key, action-type, action-key, and auth
-npx zapier-sdk run-action
-```
-
-### Machine-Readable Output
-
-```bash
-# Get raw JSON output for scripting
-npx zapier-sdk run-action slack read channels \
-  --connection-id 123456 \
-  --json
-```
-
-### Multiple Connections
-
-If you have multiple Slack connections and don't specify which one:
-
-- The CLI shows a list and prompts you to choose
-- Or use `list-connections` to find the right ID first
-
-```bash
-# Find your connection IDs
-npx zapier-sdk list-connections --app-key slack --owner me
-```
-
-## MCP Server
-
-The CLI includes an MCP (Model Context Protocol) server that enables AI tools to interact with Zapier directly.
-
-### Starting the Server
-
-```bash
-npx zapier-sdk mcp
-```
-
-### Use Cases
-
-- **Claude Desktop**: Configure Claude to use Zapier actions as tools
-- **AI Agents**: Let AI agents trigger Zapier workflows
-- **Custom Integrations**: Any MCP-compatible client can use Zapier
-
-### Configuration
-
-For Claude Desktop, add to your `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "zapier": {
-      "command": "npx",
-      "args": ["zapier-sdk", "mcp"]
-    }
-  }
-}
-```
-
-## Debugging
-
-### Verbose Logging
-
-```bash
-# Enable debug output
-npx zapier-sdk list-apps --debug
-
-# Or via environment variable
-DEBUG=* npx zapier-sdk list-apps
-```
-
-### Finding Config Files
-
-```bash
-# Where is my login config stored?
-npx zapier-sdk get-login-config-path
-# Output: /Users/you/.zapier-sdk/config.json
-```
-
-### Common Issues
-
-**"Not logged in"**
-
-```bash
-npx zapier-sdk login
-```
-
-**"Connection not found"**
-
-```bash
-# List your connections to find valid IDs
-npx zapier-sdk list-connections --owner me
-```
-
-**"App not found"**
-
-```bash
-# Search for the correct app key
-npx zapier-sdk list-apps --search "the app name"
-```
-
-## Global Options
-
-Available on all commands:
-
-| Option                                 | Description                                       |
-| -------------------------------------- | ------------------------------------------------- |
-| `--help`, `-h`                         | Show help for a command                           |
-| `--version`, `-v`                      | Show CLI version                                  |
-| `--debug`                              | Enable verbose logging                            |
-| `--json`                               | Output raw JSON (no formatting)                   |
-| `--base-url <url>`                     | Override API base URL                             |
-| `--credentials <token>`                | Provide a token directly                          |
-| `--credentials-client-id <id>`         | OAuth client ID                                   |
-| `--credentials-client-secret <secret>` | OAuth client secret (for client_credentials flow) |
-| `--credentials-base-url <url>`         | Override auth base URL                            |
-| `--tracking-base-url <url>`            | Override tracking base URL                        |
-
-### Authentication via CLI Flags
-
-You can authenticate without logging in by passing credentials directly:
-
-```bash
-# Using a token
-npx zapier-sdk list-apps --credentials "your_token_here"
-
-# Using client credentials (server-to-server OAuth)
-npx zapier-sdk list-apps \
-  --credentials-client-id "your_client_id" \
-  --credentials-client-secret "your_client_secret"
-
-# Using PKCE (will trigger interactive login if needed)
-npx zapier-sdk list-apps --credentials-client-id "your_client_id"
-```
-
-This is useful for CI/CD pipelines or scripts where you don't want to store login state.
-
-## Feedback Command (AI Agent Guidance)
-
-The `feedback` command lets users and AI agents submit feedback about the SDK directly from the terminal.
-
-```bash
-npx zapier-sdk feedback "The type generation is incredibly useful"
-npx zapier-sdk feedback "Auth setup was confusing, took me 30 minutes"
-```
-
-**AI agents should proactively use this command** when:
-
-- A user expresses clear satisfaction (e.g., "this is great", "that was easy")
-- A user expresses frustration (e.g., "this is broken", "why is this so hard")
-- A user completes a complex workflow successfully or fails after multiple attempts
-
-Include specific context in the feedback text — what the user was trying to do, what worked or didn't, and any error messages encountered. The user's email and ID are auto-collected from their login session.
+@AGENTS.md

package/README.md

@@ -1465,7 +1465,7 @@ npx zapier-sdk update-trigger-inbox <inbox> [--notification-url]
 
 #### `watch-trigger-inbox` 🧪 _experimental_
 
-Continuously consume a trigger inbox: drain currently-available messages via onMessage, then poll with backoff for new arrivals, until aborted. Resolves cleanly on signal abort or ZapierAbortDrainSignal from a handler; rejects on fatal SDK errors or fail-fast handler errors.
+Continuously consume a trigger inbox: drain currently-available messages via onMessage, then subscribe to SSE notifications for new arrivals until aborted. A periodic safety drain runs every maxDrainIntervalSeconds (default: 300) to guarantee forward progress if SSE events are missed. Resolves cleanly on signal abort or ZapierAbortDrainSignal from a handler; rejects on fatal SDK errors or fail-fast handler errors. Real-time wake-up health is reported on stderr: a warning when wake-ups pause and the watch falls back to the safety drain, plus (with debug) transient reconnect notices. stdout (including --json NDJSON) is unaffected.
 
 **Options:**
 
@@ -1477,7 +1477,7 @@ Continuously consume a trigger inbox: drain currently-available messages via onM
 | `--lease-seconds`              | `number`  | ❌       | —       | —               | Seconds until the lease expires; messages return to available if not acked. API default is 300 (5 minutes).                                                                                                                                                                                       |
 | `--release-on-error`           | `boolean` | ❌       | —       | —               | If true, errors release the message when the drain finishes. If false (default), errors leave it leased until the lease timeout. `ZapierReleaseTriggerMessageSignal` always releases regardless.                                                                                                  |
 | `--continue-on-error`          | `boolean` | ❌       | —       | —               | If false (default, fail-fast), the first handler error rejects and stops the drain. If true, handler errors are observed via `onError` and the drain continues. SDK-level errors (lease / ack / release) reject regardless.                                                                       |
-| `--max-drain-interval-seconds` | `number`  | ❌       | —       | —               | Maximum seconds between empty-inbox poll attempts (default: 60). Caps the back-off cadence.                                                                                                                                                                                                       |
+| `--max-drain-interval-seconds` | `number`  | ❌       | —       | —               | Maximum seconds between safety drain attempts (default: 300). The watcher subscribes to SSE notifications for near-real-time wake-ups; this interval is the backstop that guarantees forward progress if SSE events are missed or the connection drops undetected.                                |
 | `--exec`                       | `string`  | ❌       | —       | —               | Run a binary per message with no shell interpretation. Message JSON is piped to stdin; exit code 0 acks, non-zero records the error per the same rules as a thrown handler. Pass extra argv after `--` (e.g. `--exec ./handler -- --verbose`). Mutually exclusive with --exec-shell and --json.   |
 | `--exec-shell`                 | `string`  | ❌       | —       | —               | Run a shell command per message. Message JSON is piped to the subprocess on stdin; exit code 0 acks, non-zero records the error per the same rules as a thrown handler. Interpreted by the platform's default shell (sh on POSIX, cmd.exe on Windows). Mutually exclusive with --exec and --json. |
 | `--json`                       | `boolean` | ❌       | —       | —               | Stream each message as JSON to stdout (one record per line, NDJSON), acking as each write completes. Use for piping to other tools. Mutually exclusive with --exec / --exec-shell and the interactive default.                                                                                    |