@zapier/zapier-sdk 0.63.0 → 0.65.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @zapier/zapier-sdk
 
+## 0.65.0
+
+### Minor Changes
+
+- 9138968: Add the workflow-run experimental code-substrate plugins: `listWorkflowRuns`, `getWorkflowRun`, and `getTriggerRun`. All three live behind `@zapier/zapier-sdk/experimental` only — the stable subpath does not surface them. `listWorkflowRuns` is paginated against the backend's cursor + limit contract; `getWorkflowRun` looks up a run by id; `getTriggerRun` walks from a trigger id to its associated run, useful immediately after firing a trigger when the caller has the trigger id but not yet the run id. All ID inputs are UUID-validated at the schema boundary. Handlers pass the API response through verbatim — schemas stay as `outputSchema` for docs and types, but consumers see any richer fields the server adds without an SDK release. Adds `workflowRunIdResolver` — a dependent resolver scoped to the parent workflow — so CLI commands taking a run id present an interactive picker via `sdk.listWorkflowRuns({ workflow })`. `getTriggerRun` does not register a picker for `trigger`; users typically have the trigger id from a recent fire and pass it directly.
+
+## 0.64.0
+
+### Minor Changes
+
+- 913aa6b: Add the workflow-version experimental code-substrate plugins: `publishWorkflowVersion`, `listWorkflowVersions`, and `getWorkflowVersion`. All three are registered only in `@zapier/zapier-sdk/experimental`; the stable subpath does not expose them. `listWorkflowVersions` is paginated (cursor + pageSize); `publishWorkflowVersion` POSTs `source_files` (filename → contents) plus optional `dependencies`, `zapier_durable_version`, and `enabled` (defaults to true) to publish a new version; `getWorkflowVersion` returns the full version state including source files. Handlers pass API responses through verbatim (no client-side `.parse()` re-emission) so callers see any richer fields the server adds later without an SDK release. Adds `workflowVersionIdResolver` — a dependent resolver scoped to a parent workflow, mirrored on `tableRecordIdResolver`'s shape — so commands that take a version id present an interactive picker via `sdk.listWorkflowVersions({ workflow })` in the CLI. All ID inputs are UUID-validated at the boundary so non-UUID strings fail with a clear schema error instead of an opaque 500 from the backend's `::uuid` cast.
+
 ## 0.63.0
 
 ### Minor Changes

package/README.md

@@ -33,9 +33,15 @@
   - [`disableWorkflow`](#disableworkflow--experimental)
   - [`enableWorkflow`](#enableworkflow--experimental)
   - [`getDurableRun`](#getdurablerun--experimental)
+  - [`getTriggerRun`](#gettriggerrun--experimental)
   - [`getWorkflow`](#getworkflow--experimental)
+  - [`getWorkflowRun`](#getworkflowrun--experimental)
+  - [`getWorkflowVersion`](#getworkflowversion--experimental)
   - [`listDurableRuns`](#listdurableruns--experimental)
+  - [`listWorkflowRuns`](#listworkflowruns--experimental)
+  - [`listWorkflowVersions`](#listworkflowversions--experimental)
   - [`listWorkflows`](#listworkflows--experimental)
+  - [`publishWorkflowVersion`](#publishworkflowversion--experimental)
   - [`runDurable`](#rundurable--experimental)
   - [`updateWorkflow`](#updateworkflow--experimental)
 - [Connections](#connections)
@@ -1258,6 +1264,40 @@ const { data: durableRun } = await zapier.getDurableRun({
 });
 ```
 
+#### `getTriggerRun` 🧪 _experimental_
+
+Get the workflow run associated with a deployed workflow's trigger. Useful immediately after firing a trigger, when you have the trigger ID but not yet the run ID.
+
+**Parameters:**
+
+| Name          | Type     | Required | Default | Possible Values | Description         |
+| ------------- | -------- | -------- | ------- | --------------- | ------------------- |
+| `options`     | `object` | ✅       | —       | —               |                     |
+| ​ ↳ `trigger` | `string` | ✅       | —       | —               | Workflow trigger ID |
+
+**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)                                         |
+
+**Example:**
+
+```typescript
+const { data: workflowRun } = await zapier.getTriggerRun({
+  trigger: "example-trigger",
+});
+```
+
 #### `getWorkflow` 🧪 _experimental_
 
 Get a durable workflow with its current version details and trigger claim status
@@ -1298,6 +1338,76 @@ const { data: workflow } = await zapier.getWorkflow({
 });
 ```
 
+#### `getWorkflowRun` 🧪 _experimental_
+
+Get the current state of a workflow run (a triggered execution of a deployed workflow)
+
+**Parameters:**
+
+| Name           | Type     | Required | Default | Possible Values | Description                                                                             |
+| -------------- | -------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------------- |
+| `options`      | `object` | ✅       | —       | —               |                                                                                         |
+| ​ ↳ `workflow` | `string` | ❌       | —       | —               | Parent workflow ID — used only to scope the CLI run-id picker; ignored by the API call. |
+| ​ ↳ `run`      | `string` | ✅       | —       | —               | Workflow run ID                                                                         |
+
+**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)                                         |
+
+**Example:**
+
+```typescript
+const { data: workflowRun } = await zapier.getWorkflowRun({
+  run: "example-run",
+});
+```
+
+#### `getWorkflowVersion` 🧪 _experimental_
+
+Get full details of a workflow version including source files
+
+**Parameters:**
+
+| Name           | Type     | Required | Default | Possible Values | Description         |
+| -------------- | -------- | -------- | ------- | --------------- | ------------------- |
+| `options`      | `object` | ✅       | —       | —               |                     |
+| ​ ↳ `workflow` | `string` | ✅       | —       | —               | Durable workflow ID |
+| ​ ↳ `version`  | `string` | ✅       | —       | —               | Workflow version ID |
+
+**Returns:** `Promise<WorkflowVersionItem>`
+
+| Name                         | Type     | Required | Possible Values | Description                                                         |
+| ---------------------------- | -------- | -------- | --------------- | ------------------------------------------------------------------- |
+| `data`                       | `object` | ✅       | —               |                                                                     |
+| ​ ↳ `id`                     | `string` | ✅       | —               | Workflow version ID (UUID)                                          |
+| ​ ↳ `workflow_id`            | `string` | ✅       | —               | Parent workflow ID (UUID)                                           |
+| ​ ↳ `source_files`           | `object` | ✅       | —               | Source files keyed by filename → contents                           |
+| ​ ↳ `zapier_durable_version` | `string` | ✅       | —               | Pinned semver of @zapier/zapier-durable used by this version's runs |
+| ​ ↳ `dependencies`           | `object` | ✅       | —               | Additional npm dependencies pinned for this version (or null)       |
+| ​ ↳ `created_by_user_id`     | `string` | ✅       | —               | ID of the user who published this version                           |
+| ​ ↳ `created_at`             | `string` | ✅       | —               | When the version was published (ISO-8601)                           |
+
+**Example:**
+
+```typescript
+const { data: workflowVersion } = await zapier.getWorkflowVersion({
+  workflow: "example-workflow",
+  version: "example-version",
+});
+```
+
 #### `listDurableRuns` 🧪 _experimental_
 
 List run-once durable runs for the authenticated account, newest first
@@ -1344,6 +1454,115 @@ for await (const durableRun of zapier.listDurableRuns().items()) {
 }
 ```
 
+#### `listWorkflowRuns` 🧪 _experimental_
+
+List workflow runs (triggered executions) for a specific deployed workflow, newest first
+
+**Parameters:**
+
+| Name           | Type     | Required | Default | Possible Values | Description                                   |
+| -------------- | -------- | -------- | ------- | --------------- | --------------------------------------------- |
+| `options`      | `object` | ✅       | —       | —               |                                               |
+| ​ ↳ `workflow` | `string` | ✅       | —       | —               | Durable workflow ID                           |
+| ​ ↳ `pageSize` | `number` | ❌       | —       | —               | Number of runs per page (max 100)             |
+| ​ ↳ `cursor`   | `string` | ❌       | —       | —               | Pagination cursor                             |
+| ​ ↳ `maxItems` | `number` | ❌       | —       | —               | Maximum total runs to return across all pages |
+
+**Returns:** `Promise<PaginatedResult<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. Null for runs created without a trigger. |
+| ​ ↳ `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)                                  |
+| ​ ↳ `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                          |
+
+**Example:**
+
+```typescript
+// Get first page and a cursor for the second page
+const { data: workflowRuns, nextCursor } = await zapier.listWorkflowRuns({
+  workflow: "example-workflow",
+});
+
+// Or iterate over all pages
+for await (const page of zapier.listWorkflowRuns({
+  workflow: "example-workflow",
+})) {
+  // Do something with each page
+}
+
+// Or iterate over individual items across all pages
+for await (const workflowRun of zapier
+  .listWorkflowRuns({
+    workflow: "example-workflow",
+  })
+  .items()) {
+  // Do something with each workflowRun
+}
+```
+
+#### `listWorkflowVersions` 🧪 _experimental_
+
+List published versions for a workflow, newest first
+
+**Parameters:**
+
+| Name           | Type     | Required | Default | Possible Values | Description                                       |
+| -------------- | -------- | -------- | ------- | --------------- | ------------------------------------------------- |
+| `options`      | `object` | ✅       | —       | —               |                                                   |
+| ​ ↳ `workflow` | `string` | ✅       | —       | —               | Durable workflow ID                               |
+| ​ ↳ `pageSize` | `number` | ❌       | —       | —               | Number of versions per page (max 100)             |
+| ​ ↳ `cursor`   | `string` | ❌       | —       | —               | Pagination cursor                                 |
+| ​ ↳ `maxItems` | `number` | ❌       | —       | —               | Maximum total versions to return across all pages |
+
+**Returns:** `Promise<PaginatedResult<WorkflowVersionItem>>`
+
+| Name                         | Type       | Required | Possible Values | Description                                                         |
+| ---------------------------- | ---------- | -------- | --------------- | ------------------------------------------------------------------- |
+| `data[]`                     | `object[]` | ✅       | —               |                                                                     |
+| ​ ↳ `id`                     | `string`   | ✅       | —               | Workflow version ID (UUID)                                          |
+| ​ ↳ `workflow_id`            | `string`   | ✅       | —               | Parent workflow ID (UUID)                                           |
+| ​ ↳ `zapier_durable_version` | `string`   | ✅       | —               | Pinned semver of @zapier/zapier-durable used by this version's runs |
+| ​ ↳ `dependencies`           | `object`   | ✅       | —               | Additional npm dependencies pinned for this version (or null)       |
+| ​ ↳ `created_by_user_id`     | `string`   | ✅       | —               | ID of the user who published this version                           |
+| ​ ↳ `created_at`             | `string`   | ✅       | —               | When the version was published (ISO-8601)                           |
+| `nextCursor`                 | `string`   | ❌       | —               | Cursor for the next page; omitted when there are no more pages      |
+
+**Example:**
+
+```typescript
+// Get first page and a cursor for the second page
+const { data: workflowVersions, nextCursor } =
+  await zapier.listWorkflowVersions({
+    workflow: "example-workflow",
+  });
+
+// Or iterate over all pages
+for await (const page of zapier.listWorkflowVersions({
+  workflow: "example-workflow",
+})) {
+  // Do something with each page
+}
+
+// Or iterate over individual items across all pages
+for await (const workflowVersion of zapier
+  .listWorkflowVersions({
+    workflow: "example-workflow",
+  })
+  .items()) {
+  // Do something with each workflowVersion
+}
+```
+
 #### `listWorkflows` 🧪 _experimental_
 
 List all active durable workflows for the authenticated account
@@ -1389,6 +1608,43 @@ for await (const workflow of zapier.listWorkflows().items()) {
 }
 ```
 
+#### `publishWorkflowVersion` 🧪 _experimental_
+
+Publish a new version of a durable workflow. Enables the workflow by default.
+
+**Parameters:**
+
+| Name                         | Type      | Required | Default | Possible Values | Description                                                                                                     |
+| ---------------------------- | --------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------------------------------------- |
+| `options`                    | `object`  | ✅       | —       | —               |                                                                                                                 |
+| ​ ↳ `workflow`               | `string`  | ✅       | —       | —               | Durable workflow ID                                                                                             |
+| ​ ↳ `source_files`           | `object`  | ✅       | —       | —               | Source files keyed by filename → contents                                                                       |
+| ​ ↳ `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. |
+| ​ ↳ `enabled`                | `boolean` | ❌       | —       | —               | Enable the workflow after publishing. Defaults to true; pass false to publish without enabling.                 |
+
+**Returns:** `Promise<WorkflowVersionItem>`
+
+| Name                         | Type     | Required | Possible Values | Description                                                         |
+| ---------------------------- | -------- | -------- | --------------- | ------------------------------------------------------------------- |
+| `data`                       | `object` | ✅       | —               |                                                                     |
+| ​ ↳ `id`                     | `string` | ✅       | —               | Workflow version ID (UUID)                                          |
+| ​ ↳ `workflow_id`            | `string` | ✅       | —               | Parent workflow ID (UUID)                                           |
+| ​ ↳ `source_files`           | `object` | ✅       | —               | Source files keyed by filename → contents                           |
+| ​ ↳ `zapier_durable_version` | `string` | ✅       | —               | Pinned semver of @zapier/zapier-durable used by this version's runs |
+| ​ ↳ `dependencies`           | `object` | ✅       | —               | Additional npm dependencies pinned for this version (or null)       |
+| ​ ↳ `created_by_user_id`     | `string` | ✅       | —               | ID of the user who published this version                           |
+| ​ ↳ `created_at`             | `string` | ✅       | —               | When the version was published (ISO-8601)                           |
+
+**Example:**
+
+```typescript
+const result = await zapier.publishWorkflowVersion({
+  workflow: "example-workflow",
+  source_files: {},
+});
+```
+
 #### `runDurable` 🧪 _experimental_
 
 Run a workflow source file as a run-once durable run on sdkdurableapi (no deployed workflow required). Returns the run ID immediately; poll via getDurableRun for terminal status.