@zapier/zapier-sdk 0.105.0 → 0.107.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,77 @@
1
1
  # @zapier/zapier-sdk
2
2
 
3
+ ## 0.107.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 17927b2: Added six experimental methods for putting a workflow under agentic management,
8
+ available from `@zapier/zapier-sdk/experimental`:
9
+ - `enableAgenticManagement` / `disableAgenticManagement` — turn management on or
10
+ off for one workflow. Disabling keeps the workflow's settings rather than
11
+ deleting them, so enabling it again resumes with the modes and approval choice
12
+ it had before.
13
+ - `getAgenticManagementConfig` / `updateAgenticManagementConfig` — read or change
14
+ the modes a workflow runs and whether fixes need approval. A `modes` list
15
+ replaces the whole current set in one step rather than adding to it; omit it to
16
+ change only the approval setting.
17
+ - `getAgenticManagementIntent` / `updateAgenticManagementIntent` — read or record
18
+ what a workflow version is meant to do. Each version stores its own intent and
19
+ never picks up another version's, so a newly published version starts with
20
+ none.
21
+
22
+ These operate on the same workflow `getWorkflow` and `listWorkflows` return, so
23
+ `workflow` accepts the id from either, and the methods resolve it the way the
24
+ other workflow methods do.
25
+
26
+ A workflow runs one or more modes — `heal`, `expand`, or `harden` — each
27
+ described on the `modes` parameter. `autoApprove` decides whether proposed fixes
28
+ are applied without prompting. Omit it and they are: a first enable applies
29
+ fixes without asking, and an update leaves the setting alone — so `false` is a
30
+ distinct third state rather than the same as leaving it out.
31
+
32
+ ## 0.106.0
33
+
34
+ ### Minor Changes
35
+
36
+ - 4b9d735: Callers who use the SDK's own methods rather than authoring plugins are
37
+ unaffected by everything below.
38
+
39
+ `createSdk` now checks that a plugin declared by id is satisfied by a provider
40
+ whose types match, not only that some provider exists. Building a graph from
41
+ `declareMethod` / `declareProperty` references and `defineMethod` /
42
+ `defineProperty` providers used to compile on the strength of the id string
43
+ alone, so a provider that contradicted the reference reached the consumer and
44
+ broke at runtime.
45
+
46
+ ```ts
47
+ const doubleRef = declareMethod<"double", { value: number }, number>({
48
+ id: "double",
49
+ });
50
+ // Written for a display surface: it formats instead of computing.
51
+ const formatsIt = defineMethod({
52
+ name: "double",
53
+ run: ({ input }: { input: { value: number } }) => `${input.value * 2}`,
54
+ });
55
+ // Compiled clean before. Rejected at createSdk now.
56
+ ```
57
+
58
+ A provider may accept **wider** input and must return a **subtype** of the
59
+ declared output, since the comparison is on the call a consumer makes. **This
60
+ can surface an error in a graph that compiled before**, which is the point:
61
+ correct the provider, or widen the reference to what the provider offers.
62
+
63
+ Added `ContractEntry`, `MethodContract`, `DeclarationSummary`, and
64
+ `OptionalDeclarationSummary`, for annotating a plugin by hand instead of letting
65
+ `define*` infer it. If you already annotate one, update it: `LeafSummary` now
66
+ requires the surfaced binding as a fourth argument, and a two-argument
67
+ `PluginSummary` still compiles while declaring no contract, which drops that
68
+ plugin out of the check silently.
69
+
70
+ ### Patch Changes
71
+
72
+ - Updated dependencies [4b9d735]
73
+ - @zapier/kitcore@0.20.0
74
+
3
75
  ## 0.105.0
4
76
 
5
77
  ### Minor Changes
package/README.md CHANGED
@@ -33,9 +33,13 @@
33
33
  - [`createWorkflow`](#createworkflow--experimental)
34
34
  - [`createWorkflowDraft`](#createworkflowdraft--experimental)
35
35
  - [`deleteWorkflow`](#deleteworkflow--experimental)
36
+ - [`disableAgenticManagement`](#disableagenticmanagement--experimental)
36
37
  - [`disableWorkflow`](#disableworkflow--experimental)
37
38
  - [`discardWorkflowDraft`](#discardworkflowdraft--experimental)
39
+ - [`enableAgenticManagement`](#enableagenticmanagement--experimental)
38
40
  - [`enableWorkflow`](#enableworkflow--experimental)
41
+ - [`getAgenticManagementConfig`](#getagenticmanagementconfig--experimental)
42
+ - [`getAgenticManagementIntent`](#getagenticmanagementintent--experimental)
39
43
  - [`getDurableRun`](#getdurablerun--experimental)
40
44
  - [`getTriggerRun`](#gettriggerrun--experimental)
41
45
  - [`getWorkflow`](#getworkflow--experimental)
@@ -52,6 +56,8 @@
52
56
  - [`publishWorkflowVersion`](#publishworkflowversion--experimental)
53
57
  - [`runDurable`](#rundurable--experimental)
54
58
  - [`triggerWorkflow`](#triggerworkflow--experimental)
59
+ - [`updateAgenticManagementConfig`](#updateagenticmanagementconfig--experimental)
60
+ - [`updateAgenticManagementIntent`](#updateagenticmanagementintent--experimental)
55
61
  - [`updateWorkflow`](#updateworkflow--experimental)
56
62
  - [`updateWorkflowDraft`](#updateworkflowdraft--experimental)
57
63
  - [`validateWorkflow`](#validateworkflow--experimental)
@@ -1336,6 +1342,32 @@ const result = await zapier.deleteWorkflow({
1336
1342
  });
1337
1343
  ```
1338
1344
 
1345
+ #### `disableAgenticManagement` 🧪 _experimental_
1346
+
1347
+ Stop Agentic Management from working on one workflow. Its settings are kept, not deleted: the modes and auto-approve choice stay on file, so calling enableAgenticManagement later resumes with those settings instead of the defaults.
1348
+
1349
+ **Parameters:**
1350
+
1351
+ | Name | Type | Required | Default | Possible Values | Description |
1352
+ | -------------- | -------- | -------- | ------- | --------------- | ----------------------------------------------------- |
1353
+ | `options` | `object` | ✅ | — | — | |
1354
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to take out of agentic management. |
1355
+
1356
+ **Returns:** `Promise<{ success: boolean }>`
1357
+
1358
+ | Name | Type | Required | Possible Values | Description |
1359
+ | -------- | --------- | -------- | --------------- | -------------------------------------------------------------------- |
1360
+ | `data` | `object` | ✅ | — | |
1361
+ | ​ ↳ `ok` | `boolean` | ✅ | — | True when Zapier accepted the request to stop managing the workflow. |
1362
+
1363
+ **Example:**
1364
+
1365
+ ```typescript
1366
+ const result = await zapier.disableAgenticManagement({
1367
+ workflow: "example-workflow",
1368
+ });
1369
+ ```
1370
+
1339
1371
  #### `disableWorkflow` 🧪 _experimental_
1340
1372
 
1341
1373
  Disable a durable workflow so it stops accepting triggers
@@ -1408,6 +1440,35 @@ const result = await zapier.discardWorkflowDraft({
1408
1440
  });
1409
1441
  ```
1410
1442
 
1443
+ #### `enableAgenticManagement` 🧪 _experimental_
1444
+
1445
+ Put one workflow under Agentic Management. A workflow disabled earlier comes back with the modes and auto-approve choice it had, unless you pass new ones here.
1446
+
1447
+ **Parameters:**
1448
+
1449
+ | Name | Type | Required | Default | Possible Values | Description |
1450
+ | ----------------- | --------- | -------- | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1451
+ | `options` | `object` | ✅ | — | — | |
1452
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to put under agentic management. |
1453
+ | ​ ↳ `modes` | `array` | ❌ | — | — | The modes to run for this workflow. Omit it and the workflow starts on `heal` alone. A mode is what Agentic Management watches for and what it changes in response. `heal` monitors runs for errors and, when something breaks, diagnoses the cause and drafts and tests a fix; it is the mode a workflow gets by default. `expand` grows what the workflow covers: it reviews runs that succeeded without actually doing anything — a lookup that matched nothing, a filter that passed no items, a trigger payload no branch handles — and proposes a new branch or step to handle that case, rather than rewriting the ones that already work. `harden` watches the AI steps: when an AI step keeps doing the same work the same way, it converts that step into fixed code, so the workflow runs faster, costs less, and behaves the same way every time. Modes stack — each one you name runs alongside the others, and a mode you leave out does nothing, so a workflow on `expand` alone does not repair failed runs. Whether a change goes live on its own or waits for someone to approve it is `autoApprove`, not the mode. |
1454
+ | ​ ↳ `autoApprove` | `boolean` | ❌ | — | — | Apply the fixes Agentic Management proposes without asking first. Set it to false and each fix waits for someone to approve it. Omit it and fixes are applied without asking, which is what a workflow enabled for the first time gets; a workflow being re-enabled keeps the setting it had before. |
1455
+
1456
+ **Returns:** `Promise<AgenticManagementEnableResultItem>`
1457
+
1458
+ | Name | Type | Required | Possible Values | Description |
1459
+ | ---------------- | -------- | -------- | --------------- | ----------------------------------------------------------------------- |
1460
+ | `data` | `object` | ✅ | — | |
1461
+ | ​ ↳ `manager_id` | `string` | ✅ | — | ID of the manager automation Zapier provisioned to watch this workflow. |
1462
+
1463
+ **Example:**
1464
+
1465
+ ```typescript
1466
+ const { data: agenticManagementEnableResult } =
1467
+ await zapier.enableAgenticManagement({
1468
+ workflow: "example-workflow",
1469
+ });
1470
+ ```
1471
+
1411
1472
  #### `enableWorkflow` 🧪 _experimental_
1412
1473
 
1413
1474
  Enable a durable workflow so it accepts triggers
@@ -1435,6 +1496,68 @@ const { data: workflow } = await zapier.enableWorkflow({
1435
1496
  });
1436
1497
  ```
1437
1498
 
1499
+ #### `getAgenticManagementConfig` 🧪 _experimental_
1500
+
1501
+ Read the Agentic Management config for one workflow.
1502
+
1503
+ **Parameters:**
1504
+
1505
+ | Name | Type | Required | Default | Possible Values | Description |
1506
+ | -------------- | -------- | -------- | ------- | --------------- | --------------------------- |
1507
+ | `options` | `object` | ✅ | — | — | |
1508
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to read. |
1509
+
1510
+ **Returns:** `Promise<AgenticManagementConfigItem>`
1511
+
1512
+ | Name | Type | Required | Possible Values | Description |
1513
+ | ------------------ | --------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1514
+ | `data` | `object` | ✅ | — | |
1515
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | The workflow this config describes. |
1516
+ | ​ ↳ `enabled` | `boolean` | ✅ | — | Whether Agentic Management is currently active for this workflow. |
1517
+ | ​ ↳ `auto_approve` | `boolean` | ✅ | — | Whether fixes are applied without asking for approval first. `false` when Agentic Management has never been set up for this workflow. |
1518
+ | ​ ↳ `modes` | `array` | ✅ | — | The modes the workflow runs. Still listed while `enabled` is false, because the settings are kept for a later re-enable — so read `enabled` to tell whether they are in effect, not this list. |
1519
+ | ​ ↳ `manager_id` | `string` | ❌ | — | ID of the manager automation Zapier provisioned for this workflow, once one exists; `null` otherwise. Use it to link to that automation to see the runs it has taken. |
1520
+
1521
+ **Example:**
1522
+
1523
+ ```typescript
1524
+ const { data: agenticManagementConfig } =
1525
+ await zapier.getAgenticManagementConfig({
1526
+ workflow: "example-workflow",
1527
+ });
1528
+ ```
1529
+
1530
+ #### `getAgenticManagementIntent` 🧪 _experimental_
1531
+
1532
+ Read the intent recorded for one workflow version: the plain-language description of what that version of the workflow is meant to do.
1533
+
1534
+ **Parameters:**
1535
+
1536
+ | Name | Type | Required | Default | Possible Values | Description |
1537
+ | -------------- | -------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1538
+ | `options` | `object` | ✅ | — | — | |
1539
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to read. |
1540
+ | ​ ↳ `version` | `string` | ❌ | — | — | The workflow version the intent belongs to. Each version stores its own intent, and a version never picks up the intent of another, so publishing a new version starts it with none. Omit this to use the workflow's current published version. |
1541
+
1542
+ **Returns:** `Promise<AgenticManagementIntentItem>`
1543
+
1544
+ | Name | Type | Required | Possible Values | Description |
1545
+ | ------------------------- | -------- | -------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1546
+ | `data` | `object` | ✅ | — | |
1547
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | The workflow the intent belongs to. |
1548
+ | ​ ↳ `workflow_version_id` | `string` | ✅ | — | The version this read or write actually landed on, so you can tell which one answered when you omitted `version`. `null` only when you read a workflow that has nothing published yet. |
1549
+ | ​ ↳ `intent` | `string` | ✅ | — | The intent stored for this version, or `null` when this version has none. Intent is never carried over from another version. |
1550
+ | ​ ↳ `updated_at` | `string` | ❌ | — | When the intent was last written; `null` when never captured. |
1551
+
1552
+ **Example:**
1553
+
1554
+ ```typescript
1555
+ const { data: agenticManagementIntent } =
1556
+ await zapier.getAgenticManagementIntent({
1557
+ workflow: "example-workflow",
1558
+ });
1559
+ ```
1560
+
1438
1561
  #### `getDurableRun` 🧪 _experimental_
1439
1562
 
1440
1563
  Get the full state of a run-once durable run, including its operations journal
@@ -2206,6 +2329,70 @@ const { data: workflowRun } = await zapier.triggerWorkflow({
2206
2329
  });
2207
2330
  ```
2208
2331
 
2332
+ #### `updateAgenticManagementConfig` 🧪 _experimental_
2333
+
2334
+ Change the modes a workflow runs, whether fixes are applied without approval, or both. A `modes` list replaces the whole current set rather than adding to it.
2335
+
2336
+ **Parameters:**
2337
+
2338
+ | Name | Type | Required | Default | Possible Values | Description |
2339
+ | ----------------- | --------- | -------- | ------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2340
+ | `options` | `object` | ✅ | — | — | |
2341
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to update. |
2342
+ | ​ ↳ `modes` | `array` | ❌ | — | — | The modes to run. The list you pass replaces the whole current set in one step; it is not added to what is already active. Omit it to leave the active modes as they are. A mode is what Agentic Management watches for and what it changes in response. `heal` monitors runs for errors and, when something breaks, diagnoses the cause and drafts and tests a fix; it is the mode a workflow gets by default. `expand` grows what the workflow covers: it reviews runs that succeeded without actually doing anything — a lookup that matched nothing, a filter that passed no items, a trigger payload no branch handles — and proposes a new branch or step to handle that case, rather than rewriting the ones that already work. `harden` watches the AI steps: when an AI step keeps doing the same work the same way, it converts that step into fixed code, so the workflow runs faster, costs less, and behaves the same way every time. Modes stack — each one you name runs alongside the others, and a mode you leave out does nothing, so a workflow on `expand` alone does not repair failed runs. Whether a change goes live on its own or waits for someone to approve it is `autoApprove`, not the mode. |
2343
+ | ​ ↳ `autoApprove` | `boolean` | ❌ | — | — | Apply the fixes Agentic Management proposes without asking first. Set it to false and each fix waits for someone to approve it before anything changes. Omit it to leave the current setting alone. |
2344
+
2345
+ **Returns:** `Promise<AgenticManagementConfigItem>`
2346
+
2347
+ | Name | Type | Required | Possible Values | Description |
2348
+ | ------------------ | --------- | -------- | --------------- | ------------------------------------------------------------- |
2349
+ | `data` | `object` | ✅ | — | |
2350
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | The workflow whose config was updated. |
2351
+ | ​ ↳ `modes` | `array` | ✅ | — | The modes the workflow runs after this update. |
2352
+ | ​ ↳ `auto_approve` | `boolean` | ✅ | — | Whether fixes are applied without approval after this update. |
2353
+
2354
+ **Example:**
2355
+
2356
+ ```typescript
2357
+ const { data: agenticManagementConfig } =
2358
+ await zapier.updateAgenticManagementConfig({
2359
+ workflow: "example-workflow",
2360
+ });
2361
+ ```
2362
+
2363
+ #### `updateAgenticManagementIntent` 🧪 _experimental_
2364
+
2365
+ Record what one workflow version is meant to do. Writing again for the same version replaces the text already stored, so there is no separate create and update.
2366
+
2367
+ **Parameters:**
2368
+
2369
+ | Name | Type | Required | Default | Possible Values | Description |
2370
+ | -------------- | -------- | -------- | ------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2371
+ | `options` | `object` | ✅ | — | — | |
2372
+ | ​ ↳ `workflow` | `string` | ✅ | — | — | ID of the workflow to write to. |
2373
+ | ​ ↳ `intent` | `string` | ✅ | — | — | What this version of the workflow is for, in your own words: the outcome it produces, what sets it off, and anything that must always hold true. Plain prose, not code. |
2374
+ | ​ ↳ `version` | `string` | ❌ | — | — | The workflow version the intent belongs to. Each version stores its own intent, and a version never picks up the intent of another, so publishing a new version starts it with none. Omit this to use the workflow's current published version. |
2375
+
2376
+ **Returns:** `Promise<AgenticManagementIntentItem>`
2377
+
2378
+ | Name | Type | Required | Possible Values | Description |
2379
+ | ------------------------- | -------- | -------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2380
+ | `data` | `object` | ✅ | — | |
2381
+ | ​ ↳ `workflow_id` | `string` | ✅ | — | The workflow the intent belongs to. |
2382
+ | ​ ↳ `workflow_version_id` | `string` | ✅ | — | The version this read or write actually landed on, so you can tell which one answered when you omitted `version`. `null` only when you read a workflow that has nothing published yet. |
2383
+ | ​ ↳ `intent` | `string` | ✅ | — | The intent stored for this version, or `null` when this version has none. Intent is never carried over from another version. |
2384
+ | ​ ↳ `updated_at` | `string` | ❌ | — | When the intent was last written; `null` when never captured. |
2385
+
2386
+ **Example:**
2387
+
2388
+ ```typescript
2389
+ const { data: agenticManagementIntent } =
2390
+ await zapier.updateAgenticManagementIntent({
2391
+ workflow: "example-workflow",
2392
+ intent: "example-intent",
2393
+ });
2394
+ ```
2395
+
2209
2396
  #### `updateWorkflow` 🧪 _experimental_
2210
2397
 
2211
2398
  Update a durable workflow's name and/or description
@@ -2227,6 +2227,16 @@ var pathConfig = {
2227
2227
  "/forms": {
2228
2228
  authHeader: "Authorization",
2229
2229
  subdomain: "api"
2230
+ },
2231
+ // e.g. /agentic-management/v0/<workflow-id> ->
2232
+ // https://api.zapier.com/agentic-management/v0/<workflow-id>
2233
+ // Like Forms, the Agentic Management API is registered on the Public API
2234
+ // Gateway and has no sdkapi proxy route, so it goes straight to the
2235
+ // gateway. Its governance metadata rewrites /agentic-management/v0/... to
2236
+ // the service's internal route, which is why no pathPrefix is applied here.
2237
+ "/agentic-management": {
2238
+ authHeader: "Authorization",
2239
+ subdomain: "api"
2230
2240
  }
2231
2241
  };
2232
2242
 
@@ -2675,7 +2685,7 @@ function logRouteOverride({
2675
2685
  }
2676
2686
 
2677
2687
  // src/sdk-version.ts
2678
- var SDK_VERSION = (typeof process !== "undefined" && process.env ? "0.105.0" : void 0) || "unknown";
2688
+ var SDK_VERSION = (typeof process !== "undefined" && process.env ? "0.107.0" : void 0) || "unknown";
2679
2689
 
2680
2690
  // src/utils/open-url.ts
2681
2691
  var nodePrefix = "node:";
@@ -2226,6 +2226,16 @@ var pathConfig = {
2226
2226
  "/forms": {
2227
2227
  authHeader: "Authorization",
2228
2228
  subdomain: "api"
2229
+ },
2230
+ // e.g. /agentic-management/v0/<workflow-id> ->
2231
+ // https://api.zapier.com/agentic-management/v0/<workflow-id>
2232
+ // Like Forms, the Agentic Management API is registered on the Public API
2233
+ // Gateway and has no sdkapi proxy route, so it goes straight to the
2234
+ // gateway. Its governance metadata rewrites /agentic-management/v0/... to
2235
+ // the service's internal route, which is why no pathPrefix is applied here.
2236
+ "/agentic-management": {
2237
+ authHeader: "Authorization",
2238
+ subdomain: "api"
2229
2239
  }
2230
2240
  };
2231
2241
 
@@ -2674,7 +2684,7 @@ function logRouteOverride({
2674
2684
  }
2675
2685
 
2676
2686
  // src/sdk-version.ts
2677
- var SDK_VERSION = (typeof process !== "undefined" && process.env ? "0.105.0" : void 0) || "unknown";
2687
+ var SDK_VERSION = (typeof process !== "undefined" && process.env ? "0.107.0" : void 0) || "unknown";
2678
2688
 
2679
2689
  // src/utils/open-url.ts
2680
2690
  var nodePrefix = "node:";