@zapier/zapier-sdk 0.65.0 → 0.68.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @zapier/zapier-sdk
 
+## 0.68.0
+
+### Minor Changes
+
+- 41a7c26: Add `zapier-sdk signup` for browser-based account setup and local SDK credential provisioning.
+  Add the `signup_success` SDK lifecycle telemetry event type for successful signup OAuth callback acceptance.
+
+## 0.67.0
+
+### Minor Changes
+
+- 9096184: Extract the plugin framework into a new sibling package `kitcore` that
+  `@zapier/zapier-sdk` consumes as a workspace devDependency (bundled into
+  the published dist, not a runtime dep). Existing SDK code is unaffected:
+  `createZapierSdk`, `createSdk`, the `ZapierSdk` type, every SDK method, and
+  the full `Zapier*` error hierarchy keep their names, codes, and `instanceof`
+  semantics. Internally `createZapierSdk` now builds via the linear
+  `createPluginStack().use(...).toSdk()` path, which substantially speeds up
+  construction. One behavior change to note: `normalizeError` no longer wraps
+  thrown `Error` subclasses, so a handler's `TypeError` or a userland
+  `MyAppError` bubbles through unchanged and `instanceof` works again; only
+  non-`Error` throws get wrapped.
+
+  New stack-based composition surface for building on top of the SDK:
+  `createZapierSdkStack(options)` (from the root and `/experimental`) returns
+  the unsealed `PluginStack` that `createZapierSdk` materializes, and
+  `createPluginStack`, `createCorePlugin`, and `addPlugin` are re-exported from
+  the root. Build by chaining `.use(...)` and sealing with `.toSdk()`, or
+  extend a sealed SDK in place with `addPlugin(sdk, plugin)`. The chain-style
+  `createSdk().addPlugin(...)` pattern is deprecated (now logs a one-time
+  warning) but still works; the CLI and MCP packages moved their internal
+  assembly to stacks with no change to their commands or tools.
+
+### Patch Changes
+
+- a950509: Route all debug, diagnostic, and telemetry log output to stderr (`console.error`) instead of stdout (`console.log`) across the SDK and CLI packages. The CLI now reserves stdout exclusively for the program's data payload — command output, JSON envelopes, response bodies — so callers can safely pipe CLI output through `jq`, `> redirect`, or `JSON.parse` even when `--debug` is on or telemetry/logging flags are enabled. Interactive terminal users see no change since both streams interleave in a TTY.
+
+## 0.66.0
+
+### Minor Changes
+
+- 0eb6a76: Add the `triggerWorkflow` experimental code-substrate plugin. Lives behind `@zapier/zapier-sdk/experimental` only — the stable subpath does not surface it. Looks up the workflow's `trigger_url` via the durableworkflowzaps API, then POSTs the user-supplied JSON payload to that URL. The trigger endpoint is tokenized (the URL embeds a secret) and takes no auth header, so the SDK uses a raw `fetch` rather than the api plugin for the second leg. Custom fetch flows through `sdk.context.options.fetch` for tests. The workflow id is UUID-validated at the input boundary; trigger endpoint failures (non-2xx, or workflow with no published version) surface as descriptive errors. The CLI gets the `workflowIdResolver` picker for the workflow input.
+
+### Patch Changes
+
+- 66db7cb: Limit approval polling waits to at most 5 seconds while preserving the existing generic polling cadence.
+- c7c8f64: Route `--debug` log output to stderr (`console.error`) instead of stdout (`console.log`) in `auth.ts` and `api/debug.ts`. This restores stdout's Unix contract — stdout carries only the program's data payload — so callers can safely pipe CLI output through `jq`, redirect to a file, or `JSON.parse` it even when `--debug` is on. Debug output still appears in CI logs and developer terminals (both streams interleave there).
+
 ## 0.65.0
 
 ### Minor Changes

package/README.md

@@ -43,6 +43,7 @@
   - [`listWorkflows`](#listworkflows--experimental)
   - [`publishWorkflowVersion`](#publishworkflowversion--experimental)
   - [`runDurable`](#rundurable--experimental)
+  - [`triggerWorkflow`](#triggerworkflow--experimental)
   - [`updateWorkflow`](#updateworkflow--experimental)
 - [Connections](#connections)
   - [`findFirstConnection`](#findfirstconnection)
@@ -1248,8 +1249,8 @@ Get the full state of a run-once durable run, including its operations journal
 | `data`           | `object`  | ✅       | —                                                           |                                                                                                         |
 | ​ ↳ `id`         | `string`  | ✅       | —                                                           | Run ID (UUID)                                                                                           |
 | ​ ↳ `status`     | `string`  | ✅       | `initialized`, `started`, `finished`, `failed`, `cancelled` | Run lifecycle status. `finished` / `failed` / `cancelled` are terminal.                                 |
-| ​ ↳ `input`      | `string`  | ✅       | —                                                           | Input data passed to the run                                                                            |
-| ​ ↳ `output`     | `string`  | ✅       | —                                                           | Return value, present when status is `finished`                                                         |
+| ​ ↳ `input`      | `unknown` | ✅       | —                                                           | Input data passed to the run                                                                            |
+| ​ ↳ `output`     | `unknown` | ✅       | —                                                           | Return value, present when status is `finished`                                                         |
 | ​ ↳ `error`      | `object`  | ✅       | —                                                           | Structured error details when the run failed (null otherwise)                                           |
 | ​ ↳ `execution`  | `object`  | ✅       | —                                                           | Linked execution, including the operations journal. Null while the run is still in `initialized` state. |
 | ​ ↳ `is_private` | `boolean` | ✅       | —                                                           | When true, the run is visible only to the creating user; otherwise visible across the account.          |
@@ -1277,18 +1278,18 @@ Get the workflow run associated with a deployed workflow's trigger. Useful immed
 
 **Returns:** `Promise<WorkflowRunItem>`
 
-| Name                      | Type     | Required | Possible Values                                             | Description                                                                      |
-| ------------------------- | -------- | -------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `data`                    | `object` | ✅       | —                                                           |                                                                                  |
-| ​ ↳ `id`                  | `string` | ✅       | —                                                           | Workflow run ID (UUID)                                                           |
-| ​ ↳ `durable_run_id`      | `string` | ✅       | —                                                           | Linked sdkdurableapi run ID. Null until the durable run is created.              |
-| ​ ↳ `workflow_version_id` | `string` | ✅       | —                                                           | Workflow version the run is bound to                                             |
-| ​ ↳ `status`              | `string` | ✅       | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
-| ​ ↳ `input`               | `string` | ✅       | —                                                           | Input passed to the run                                                          |
-| ​ ↳ `output`              | `string` | ✅       | —                                                           | Return value, present when status is `finished`                                  |
-| ​ ↳ `error`               | `string` | ✅       | —                                                           | Error payload when status is `failed` (null otherwise)                           |
-| ​ ↳ `created_at`          | `string` | ✅       | —                                                           | When the run was created (ISO-8601)                                              |
-| ​ ↳ `updated_at`          | `string` | ✅       | —                                                           | When the run was last updated (ISO-8601)                                         |
+| Name                      | Type      | Required | Possible Values                                             | Description                                                                      |
+| ------------------------- | --------- | -------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `data`                    | `object`  | ✅       | —                                                           |                                                                                  |
+| ​ ↳ `id`                  | `string`  | ✅       | —                                                           | Workflow run ID (UUID)                                                           |
+| ​ ↳ `durable_run_id`      | `string`  | ✅       | —                                                           | Linked sdkdurableapi run ID. Null until the durable run is created.              |
+| ​ ↳ `workflow_version_id` | `string`  | ✅       | —                                                           | Workflow version the run is bound to                                             |
+| ​ ↳ `status`              | `string`  | ✅       | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
+| ​ ↳ `input`               | `unknown` | ✅       | —                                                           | Input passed to the run                                                          |
+| ​ ↳ `output`              | `unknown` | ✅       | —                                                           | Return value, present when status is `finished`                                  |
+| ​ ↳ `error`               | `unknown` | ✅       | —                                                           | Error payload when status is `failed` (null otherwise)                           |
+| ​ ↳ `created_at`          | `string`  | ✅       | —                                                           | When the run was created (ISO-8601)                                              |
+| ​ ↳ `updated_at`          | `string`  | ✅       | —                                                           | When the run was last updated (ISO-8601)                                         |
 
 **Example:**
 
@@ -1352,19 +1353,19 @@ Get the current state of a workflow run (a triggered execution of a deployed wor
 
 **Returns:** `Promise<WorkflowRunItem>`
 
-| Name                      | Type     | Required | Possible Values                                             | Description                                                                      |
-| ------------------------- | -------- | -------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `data`                    | `object` | ✅       | —                                                           |                                                                                  |
-| ​ ↳ `id`                  | `string` | ✅       | —                                                           | Workflow run ID (UUID)                                                           |
-| ​ ↳ `trigger_id`          | `string` | ✅       | —                                                           | ID of the trigger that fired this run, if any                                    |
-| ​ ↳ `durable_run_id`      | `string` | ✅       | —                                                           | Linked sdkdurableapi run ID. Null until the durable run is created.              |
-| ​ ↳ `workflow_version_id` | `string` | ✅       | —                                                           | Workflow version the run is bound to                                             |
-| ​ ↳ `status`              | `string` | ✅       | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
-| ​ ↳ `input`               | `string` | ✅       | —                                                           | Input passed to the run                                                          |
-| ​ ↳ `output`              | `string` | ✅       | —                                                           | Return value, present when status is `finished`                                  |
-| ​ ↳ `error`               | `string` | ✅       | —                                                           | Error payload when status is `failed` (null otherwise)                           |
-| ​ ↳ `created_at`          | `string` | ✅       | —                                                           | When the run was created (ISO-8601)                                              |
-| ​ ↳ `updated_at`          | `string` | ✅       | —                                                           | When the run was last updated (ISO-8601)                                         |
+| Name                      | Type      | Required | Possible Values                                             | Description                                                                      |
+| ------------------------- | --------- | -------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `data`                    | `object`  | ✅       | —                                                           |                                                                                  |
+| ​ ↳ `id`                  | `string`  | ✅       | —                                                           | Workflow run ID (UUID)                                                           |
+| ​ ↳ `trigger_id`          | `string`  | ✅       | —                                                           | ID of the trigger that fired this run, if any                                    |
+| ​ ↳ `durable_run_id`      | `string`  | ✅       | —                                                           | Linked sdkdurableapi run ID. Null until the durable run is created.              |
+| ​ ↳ `workflow_version_id` | `string`  | ✅       | —                                                           | Workflow version the run is bound to                                             |
+| ​ ↳ `status`              | `string`  | ✅       | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal. |
+| ​ ↳ `input`               | `unknown` | ✅       | —                                                           | Input passed to the run                                                          |
+| ​ ↳ `output`              | `unknown` | ✅       | —                                                           | Return value, present when status is `finished`                                  |
+| ​ ↳ `error`               | `unknown` | ✅       | —                                                           | Error payload when status is `failed` (null otherwise)                           |
+| ​ ↳ `created_at`          | `string`  | ✅       | —                                                           | When the run was created (ISO-8601)                                              |
+| ​ ↳ `updated_at`          | `string`  | ✅       | —                                                           | When the run was last updated (ISO-8601)                                         |
 
 **Example:**
 
@@ -1428,8 +1429,8 @@ List run-once durable runs for the authenticated account, newest first
 | `data[]`           | `object[]` | ✅       | —                                                           |                                                                                                |
 | ​ ↳ `id`           | `string`   | ✅       | —                                                           | Run ID (UUID)                                                                                  |
 | ​ ↳ `status`       | `string`   | ✅       | `initialized`, `started`, `finished`, `failed`, `cancelled` | Run lifecycle status. `finished` / `failed` / `cancelled` are terminal.                        |
-| ​ ↳ `input`        | `string`   | ✅       | —                                                           | Input data passed to the run                                                                   |
-| ​ ↳ `output`       | `string`   | ✅       | —                                                           | Return value, present when status is `finished`                                                |
+| ​ ↳ `input`        | `unknown`  | ✅       | —                                                           | Input data passed to the run                                                                   |
+| ​ ↳ `output`       | `unknown`  | ✅       | —                                                           | Return value, present when status is `finished`                                                |
 | ​ ↳ `error`        | `object`   | ✅       | —                                                           | Structured error details when the run failed (null otherwise)                                  |
 | ​ ↳ `execution_id` | `string`   | ✅       | —                                                           | Linked execution ID. Null until the run leaves the `initialized` state.                        |
 | ​ ↳ `is_private`   | `boolean`  | ✅       | —                                                           | When true, the run is visible only to the creating user; otherwise visible across the account. |
@@ -1478,9 +1479,9 @@ List workflow runs (triggered executions) for a specific deployed workflow, newe
 | ​ ↳ `durable_run_id`      | `string`   | ✅       | —                                                           | Linked sdkdurableapi run ID. Null until the durable run is created.                     |
 | ​ ↳ `workflow_version_id` | `string`   | ✅       | —                                                           | Workflow version the run is bound to. Null in rare edge cases.                          |
 | ​ ↳ `status`              | `string`   | ✅       | `initialized`, `started`, `finished`, `failed`, `cancelled` | Workflow run lifecycle status. `finished` / `failed` / `cancelled` are terminal.        |
-| ​ ↳ `input`               | `string`   | ✅       | —                                                           | Input passed to the run                                                                 |
-| ​ ↳ `output`              | `string`   | ✅       | —                                                           | Return value, present when status is `finished`                                         |
-| ​ ↳ `error`               | `string`   | ✅       | —                                                           | Error payload when status is `failed` (null otherwise)                                  |
+| ​ ↳ `input`               | `unknown`  | ✅       | —                                                           | Input passed to the run                                                                 |
+| ​ ↳ `output`              | `unknown`  | ✅       | —                                                           | Return value, present when status is `finished`                                         |
+| ​ ↳ `error`               | `unknown`  | ✅       | —                                                           | Error payload when status is `failed` (null otherwise)                                  |
 | ​ ↳ `created_at`          | `string`   | ✅       | —                                                           | When the run was created (ISO-8601)                                                     |
 | ​ ↳ `updated_at`          | `string`   | ✅       | —                                                           | When the run was last updated (ISO-8601)                                                |
 | `nextCursor`              | `string`   | ❌       | —                                                           | Cursor for the next page; omitted when there are no more pages                          |
@@ -1655,7 +1656,7 @@ Run a workflow source file as a run-once durable run on sdkdurableapi (no deploy
 | ---------------------------- | --------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------------------------------------- |
 | `options`                    | `object`  | ✅       | —       | —               |                                                                                                                 |
 | ​ ↳ `source_files`           | `object`  | ✅       | —       | —               | Source files keyed by filename → contents                                                                       |
-| ​ ↳ `input`                  | `string`  | ❌       | —       | —               | Input data passed to the run                                                                                    |
+| ​ ↳ `input`                  | `unknown` | ❌       | —       | —               | Input data passed to the run                                                                                    |
 | ​ ↳ `dependencies`           | `object`  | ❌       | —       | —               | Optional npm package dependencies                                                                               |
 | ​ ↳ `zapier_durable_version` | `string`  | ❌       | —       | —               | Exact semver of @zapier/zapier-durable to use (e.g. "1.2.3"). Defaults to server-configured version if omitted. |
 | ​ ↳ `connections`            | `object`  | ❌       | —       | —               | Named connection aliases. Maps alias names to Zapier connection IDs.                                            |
@@ -1680,6 +1681,35 @@ const result = await zapier.runDurable({
 });
 ```
 
+#### `triggerWorkflow` 🧪 _experimental_
+
+Look up a workflow's trigger URL and fire it manually. The trigger endpoint is tokenized (the URL contains a secret) and takes no auth header, so the SDK uses a raw fetch rather than the api plugin.
+
+**Parameters:**
+
+| Name           | Type      | Required | Default | Possible Values | Description                                                                                              |
+| -------------- | --------- | -------- | ------- | --------------- | -------------------------------------------------------------------------------------------------------- |
+| `options`      | `object`  | ✅       | —       | —               |                                                                                                          |
+| ​ ↳ `workflow` | `string`  | ✅       | —       | —               | Durable workflow ID                                                                                      |
+| ​ ↳ `input`    | `unknown` | ❌       | —       | —               | JSON payload delivered as the trigger body. Sent as `application/json`; omit to fire with an empty body. |
+
+**Returns:** `Promise<WorkflowRunItem>`
+
+| Name           | Type      | Required | Possible Values | Description                                                                                                                         |
+| -------------- | --------- | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `data`         | `object`  | ✅       | —               |                                                                                                                                     |
+| ​ ↳ `workflow` | `string`  | ✅       | —               | The workflow ID that was triggered                                                                                                  |
+| ​ ↳ `status`   | `number`  | ✅       | —               | HTTP status returned by the trigger endpoint                                                                                        |
+| ​ ↳ `body`     | `unknown` | ✅       | —               | Response body from the trigger endpoint. Parsed as JSON when the response body parses, otherwise returned as the raw response text. |
+
+**Example:**
+
+```typescript
+const result = await zapier.triggerWorkflow({
+  workflow: "example-workflow",
+});
+```
+
 #### `updateWorkflow` 🧪 _experimental_
 
 Update a durable workflow's name and/or description
@@ -2296,7 +2326,7 @@ List records in a table with optional filtering and sorting
 | ​ ↳ `filters[]`   | `object[]` | ❌       | —         | —                                                                                                                                     | Filter conditions for the query                                                                                                                                              |
 | ​   ↳ `fieldKey`  | `string`   | ✅       | —         | —                                                                                                                                     | The field key to filter on (e.g. f1, f2)                                                                                                                                     |
 | ​   ↳ `operator`  | `string`   | ✅       | —         | `exact`, `different`, `contains`, `icontains`, `gte`, `gt`, `lt`, `lte`, `range`, `in`, `isnull`, `startswith`, `search`, `is_within` | The comparison operator                                                                                                                                                      |
-| ​   ↳ `value`     | `string`   | ❌       | —         | —                                                                                                                                     | The value to compare against                                                                                                                                                 |
+| ​   ↳ `value`     | `unknown`  | ❌       | —         | —                                                                                                                                     | The value to compare against                                                                                                                                                 |
 | ​ ↳ `sort`        | `object`   | ❌       | —         | —                                                                                                                                     | Sort records by a field                                                                                                                                                      |
 | ​   ↳ `fieldKey`  | `string`   | ✅       | —         | —                                                                                                                                     | The field key to sort by                                                                                                                                                     |
 | ​   ↳ `direction` | `string`   | ❌       | `"asc"`   | —                                                                                                                                     | Sort direction                                                                                                                                                               |

package/dist/api/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAGjB,MAAM,SAAS,CAAC;AA2qCjB,eAAO,MAAM,eAAe,GAAI,SAAS,gBAAgB,KAAG,SAW3D,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAGjB,MAAM,SAAS,CAAC;AA8qCjB,eAAO,MAAM,eAAe,GAAI,SAAS,gBAAgB,KAAG,SAW3D,CAAC"}

package/dist/api/client.js

@@ -28,6 +28,7 @@ const PollApprovalResponseSchema = z.object({
     status: ApprovalStatusSchema,
     approval_id: z.string(),
 });
+const APPROVAL_MAX_POLLING_INTERVAL_MS = 5000;
 /**
  * Parse rate limit information from response headers
  */
@@ -847,6 +848,7 @@ class ZapierApiClient {
                     headers: { Accept: "application/json" },
                 })),
                 timeoutMs,
+                maxPollingIntervalMs: APPROVAL_MAX_POLLING_INTERVAL_MS,
                 isPending: (body) => {
                     const parsed = PollApprovalResponseSchema.safeParse(body);
                     return parsed.success && parsed.data.status === "pending_approval";

package/dist/api/debug.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/api/debug.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAa3C,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAwC/D;AAED,wBAAgB,aAAa,CAC3B,OAAO,CAAC,EAAE,WAAW,GACpB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAwCpC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IACxC,aAAa,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IACvC,QAAQ,EAAE,WAAW,CAAC;CACvB,IAEe,OAAO,WAAW,GAAG,GAAG,EAAE,UAAU,WAAW,uBA0C9D"}
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/api/debug.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAa3C,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CA0C/D;AAED,wBAAgB,aAAa,CAC3B,OAAO,CAAC,EAAE,WAAW,GACpB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAwCpC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IACxC,aAAa,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IACvC,QAAQ,EAAE,WAAW,CAAC;CACvB,IAEe,OAAO,WAAW,GAAG,GAAG,EAAE,UAAU,WAAW,uBA0C9D"}

package/dist/api/debug.js

@@ -25,12 +25,14 @@ export function createDebugLogger(enabled) {
         });
     }
     return (message, data) => {
+        // Route debug output to stderr so it never pollutes stdout when callers
+        // pipe CLI output (e.g. `--json` responses) into a JSON parser.
         if (data === undefined || data === "") {
-            console.log(`[Zapier SDK] ${message}`);
+            console.error(`[Zapier SDK] ${message}`);
             return;
         }
         // Use cached module if available for sync logging. Yes, this means if the util module isn't yet loaded, we'll fall
-        // back to a plain old console.log, which might mean we don't see proper formatting/nesting. But that's unlikely
+        // back to a plain old console.error, which might mean we don't see proper formatting/nesting. But that's unlikely
         // since this logging happens during async fetching. Alternatively, we could switch to async logging, but this
         // seems fine since we have to have a fallback anyway.
         if (utilModule) {
@@ -39,11 +41,11 @@ export function createDebugLogger(enabled) {
                 depth: null,
                 breakLength: 80,
             });
-            console.log(`[Zapier SDK] ${message}`, formatted);
+            console.error(`[Zapier SDK] ${message}`, formatted);
         }
         else {
             // Fallback - browser will handle formatting automatically
-            console.log(`[Zapier SDK] ${message}`, data);
+            console.error(`[Zapier SDK] ${message}`, data);
         }
     };
 }

package/dist/api/polling.d.ts

@@ -29,6 +29,8 @@ export interface PollOptions<TResult = unknown> {
     resultExtractor?: (response: unknown) => TResult;
     /** Initial delay before the first poll attempt (in milliseconds) */
     initialDelay?: number;
+    /** Maximum sleep duration between poll attempts after backoff is applied. */
+    maxPollingIntervalMs?: number;
     /**
      * Abort signal observed by the initial delay, the inter-poll sleep,
      * and (when forwarded into `fetchPoll`) the in-flight HTTP request.

package/dist/api/polling.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"polling.d.ts","sourceRoot":"","sources":["../../src/api/polling.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiCH;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,OAAO,GAAG,OAAO;IAC5C,8CAA8C;IAC9C,SAAS,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uGAAuG;IACvG,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC;IAC3C,uDAAuD;IACvD,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC;IACjD,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAWD,mBAAW,UAAU;IACnB,OAAO,YAAY;IACnB,QAAQ,aAAa;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,CAAC,OAAO,GAAG,OAAO,IAAI;IAC1C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAgEF;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,GAAG,OAAO,EACvD,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,GAC5B,OAAO,CAAC,OAAO,CAAC,CA8GlB"}
+{"version":3,"file":"polling.d.ts","sourceRoot":"","sources":["../../src/api/polling.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiCH;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,OAAO,GAAG,OAAO;IAC5C,8CAA8C;IAC9C,SAAS,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uGAAuG;IACvG,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC;IAC3C,uDAAuD;IACvD,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC;IACjD,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAWD,mBAAW,UAAU;IACnB,OAAO,YAAY;IACnB,QAAQ,aAAa;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,CAAC,OAAO,GAAG,OAAO,IAAI;IAC1C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAgEF;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,GAAG,OAAO,EACvD,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,GAC5B,OAAO,CAAC,OAAO,CAAC,CA4HlB"}

package/dist/api/polling.js

@@ -96,7 +96,7 @@ const processResponse = async (response, successStatus, pendingStatus, isPending
  * @throws {ZapierApiError} When the API returns consecutive errors
  */
 export async function pollUntilComplete(options) {
-    const { fetchPoll, timeoutMs = DEFAULT_TIMEOUT_MS, initialDelay = DEFAULT_INITIAL_DELAY_MS, successStatus = DEFAULT_SUCCESS_STATUS, pendingStatus = DEFAULT_PENDING_STATUS, isPending, resultExtractor = (response) => response, signal, } = options;
+    const { fetchPoll, timeoutMs = DEFAULT_TIMEOUT_MS, initialDelay = DEFAULT_INITIAL_DELAY_MS, successStatus = DEFAULT_SUCCESS_STATUS, pendingStatus = DEFAULT_PENDING_STATUS, isPending, resultExtractor = (response) => response, signal, maxPollingIntervalMs, } = options;
     // Validate input parameters
     if (timeoutMs <= 0) {
         throw new ZapierValidationError("Timeout must be greater than 0", {
@@ -108,6 +108,11 @@ export async function pollUntilComplete(options) {
             details: { initialDelay },
         });
     }
+    if (maxPollingIntervalMs !== undefined && maxPollingIntervalMs <= 0) {
+        throw new ZapierValidationError("Max polling interval must be greater than 0", {
+            details: { maxPollingIntervalMs },
+        });
+    }
     if (signal?.aborted)
         throw makeAbortError();
     const startTime = Date.now();
@@ -136,7 +141,10 @@ export async function pollUntilComplete(options) {
         if (attempts > 0) {
             const interval = getPollingInterval(elapsedTime);
             const waitTime = calculateErrorBackoffMs(interval, errorCount);
-            await sleep(waitTime, signal);
+            const cappedWaitTime = maxPollingIntervalMs === undefined
+                ? waitTime
+                : Math.min(waitTime, maxPollingIntervalMs);
+            await sleep(cappedWaitTime, signal);
             if (signal?.aborted)
                 throw makeAbortError();
         }

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/auth.js

@@ -284,7 +284,10 @@ async function tryStoredClientCredentialToken(options) {
     const cached = await readCachedToken(cacheKey, cache);
     if (cached !== undefined) {
         if (options.debug)
-            console.log(`[auth] Using cached token (clientId: ${activeCredential.clientId})`);
+            // Debug output goes to stderr so it never pollutes stdout when callers
+            // (smoke tests, scripts) pipe `zapier-sdk --debug ... --json` into a
+            // JSON parser.
+            console.error(`[auth] Using cached token (clientId: ${activeCredential.clientId})`);
         emitAuthResolved(options.onEvent, "client_credentials");
         return cached;
     }
@@ -302,7 +305,7 @@ async function tryStoredClientCredentialToken(options) {
         throw new ZapierAuthenticationError(`Stored client credential is missing its secret (clientId: ${activeCredential.clientId}). Run \`zapier-sdk login\` to recreate it.`);
     }
     if (options.debug)
-        console.log(`[auth] Using stored client credential (clientId: ${storedCredential.clientId})`);
+        console.error(`[auth] Using stored client credential (clientId: ${storedCredential.clientId})`);
     const token = await resolveAuthTokenFromCredentials(storedCredential, options);
     emitAuthResolved(options.onEvent, "client_credentials");
     return token;
@@ -337,7 +340,7 @@ export async function resolveAuthToken(options = {}) {
     if (storedToken !== undefined)
         return storedToken;
     if (options.debug) {
-        console.log("[auth] Using JWT (no stored client credential found)");
+        console.error("[auth] Using JWT (no stored client credential found)");
     }
     const jwtToken = await getTokenFromCliLogin({
         onEvent: options.onEvent,
@@ -379,7 +382,7 @@ async function resolveAuthTokenFromCredentials(credentials, options) {
         const cached = await readCachedToken(cacheKey, cache);
         if (cached !== undefined) {
             if (options.debug) {
-                console.log(`[auth] Using cached token (clientId: ${clientId})`);
+                console.error(`[auth] Using cached token (clientId: ${clientId})`);
             }
             return cached;
         }
@@ -395,7 +398,7 @@ async function resolveAuthTokenFromCredentials(credentials, options) {
             const recheck = await readCachedToken(cacheKey, cache);
             if (recheck !== undefined) {
                 if (options.debug) {
-                    console.log(`[auth] Using cached token (clientId: ${clientId}, locked recheck)`);
+                    console.error(`[auth] Using cached token (clientId: ${clientId}, locked recheck)`);
                 }
                 return recheck;
             }

package/dist/core-stack.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The minimal Zapier stack: an empty kitcore `createPluginStack()` seeded with
+ * just Zapier's core error adapter, no SDK methods. `.use(...)` your own
+ * plugins and `.toSdk()` to build a custom or test SDK; `createZapierSdkStack`
+ * is this plus the full plugin set. Kept in its own light module so importing
+ * it doesn't pull in the whole plugin graph.
+ *
+ *   const sdk = createZapierCoreStack()
+ *     .use(() => ({ context: { options: {} } }))
+ *     .use(() => ({ context: { api: mockApi } }))
+ *     .use(myPlugin)
+ *     .toSdk();
+ */
+export declare function createZapierCoreStack(): import("kitcore").PluginStack<object, {
+    context: {
+        meta: Record<string, import("kitcore").PluginMeta>;
+        hooks: import("kitcore").MethodHooks;
+    };
+} & {
+    context: {
+        core: import("kitcore").CoreOptions;
+    };
+}>;
+//# sourceMappingURL=core-stack.d.ts.map

package/dist/core-stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-stack.d.ts","sourceRoot":"","sources":["../src/core-stack.ts"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB;;;;;;;;;GAEpC"}

package/dist/core-stack.js

@@ -0,0 +1,32 @@
+import { createCorePlugin, createPluginStack } from "kitcore";
+import { zapierAdaptError } from "./types/errors";
+/**
+ * kitcore's core plugin wired with Zapier's `adaptError`, which produces
+ * `Zapier*` branded errors from kitcore's internal throw sites (validation,
+ * non-Error normalization) so consumers never see a neutral `CoreError`.
+ * Shared by every Zapier stack.
+ *
+ * Pagination shaping is intentionally NOT wired here: each paginated method
+ * declares its own `adaptPage` (e.g. `adaptPage: adaptZapierPage`), so the adapter
+ * travels with the plugin and stays type-checked, rather than relying on an
+ * ambient SDK-wide default that a lifted-out plugin would silently lose.
+ */
+const zapierCorePlugin = createCorePlugin({
+    adaptError: zapierAdaptError,
+});
+/**
+ * The minimal Zapier stack: an empty kitcore `createPluginStack()` seeded with
+ * just Zapier's core error adapter, no SDK methods. `.use(...)` your own
+ * plugins and `.toSdk()` to build a custom or test SDK; `createZapierSdkStack`
+ * is this plus the full plugin set. Kept in its own light module so importing
+ * it doesn't pull in the whole plugin graph.
+ *
+ *   const sdk = createZapierCoreStack()
+ *     .use(() => ({ context: { options: {} } }))
+ *     .use(() => ({ context: { api: mockApi } }))
+ *     .use(myPlugin)
+ *     .toSdk();
+ */
+export function createZapierCoreStack() {
+    return createPluginStack().use(zapierCorePlugin);
+}