@zapier/zapier-sdk 0.112.6 → 0.113.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @zapier/zapier-sdk
 
+## 0.113.0
+
+### Minor Changes
+
+- 1c1a95d: Added `@zapier/zapier-sdk/beta`, a second non-stable import path alongside `@zapier/zapier-sdk/experimental`. Every method now belongs to one of three tiers, chosen by import path, and each tier states what the SDK commits to:
+
+  | Tier             | Import                            | Contract                                                                                                                                                                                                                      |
+  | ---------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | **Stable**       | `@zapier/zapier-sdk`              | The surface we intend to keep. While the SDK is in Open Beta (0.x), a breaking change can still land in a minor release; we deprecate first where we can, and every one is called out in the changelog with a migration note. |
+  | **Beta**         | `@zapier/zapier-sdk/beta`         | Functionally complete and ready to build against, but the shape may still change as it settles. Changes land in minor releases with a changelog migration note, without a deprecation period.                                 |
+  | **Experimental** | `@zapier/zapier-sdk/experimental` | Still being designed; may change shape or disappear in any release, without notice.                                                                                                                                           |
+
+  A tier is a promise about the SDK surface, not a status report on the service behind it.
+
+  The beta tier ships empty, so `/beta` currently exposes exactly the stable surface. Nothing moved out of `/experimental` — the subpaths nest, so each one includes everything from the tiers below it, and a method can only ever move toward stable.
+
+  The first call to any non-stable method now logs a once-per-process warning naming the tier and quoting its contract:
+
+  ```
+  [zapier-sdk] listWorkflows() is marked experimental. Still being designed; may change shape or disappear in any release, without notice.
+  ```
+
+### Patch Changes
+
+- Updated dependencies [1c1a95d]
+  - @zapier/kitcore@0.21.2
+
 ## 0.112.6
 
 ### Patch Changes

package/README.md

@@ -3,6 +3,7 @@
 ## Table of Contents
 
 - [Documentation](#documentation)
+- [Stability](#stability)
 - [Quick Start](#quick-start)
 - [Installation](#installation)
 - [Walkthrough](#walkthrough)
@@ -125,6 +126,24 @@ https://docs.zapier.com/sdk
 
 Agents are sometimes blocked from viewing docs on npm, so you may want to provide them a link to the official docs or copy the docs here into a prompt.
 
+## Stability
+
+Every SDK method belongs to one of three stability tiers, chosen by import path. A tier is a commitment made by this SDK: the import path tells you everything you need to know about what can break.
+
+The SDK is in Open Beta. Every package is at version 0.x, and a minor release can contain a breaking change. The tiers describe how much warning you get before one lands, not whether one can land.
+
+| Tier             | Contract                                                                                                                                                                                                                      |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Stable**       | The surface we intend to keep. While the SDK is in Open Beta (0.x), a breaking change can still land in a minor release; we deprecate first where we can, and every one is called out in the changelog with a migration note. |
+| **Beta**         | Functionally complete and ready to build against, but the shape may still change as it settles. Changes land in minor releases with a changelog migration note, without a deprecation period.                                 |
+| **Experimental** | Still being designed; may change shape or disappear in any release, without notice.                                                                                                                                           |
+
+- **Stable** — `import { createZapierSdk } from "@zapier/zapier-sdk"`
+- **Beta** — `import { createZapierSdk } from "@zapier/zapier-sdk/beta"`
+- **Experimental** — `import { createZapierSdk } from "@zapier/zapier-sdk/experimental"`
+
+Each subpath is a superset of the one above it — `/beta` includes everything stable, `/experimental` includes everything beta — so opting into a wider tier never takes methods away. Non-stable methods announce themselves: the first call to each logs a once-per-process warning, and every non-stable section in the reference below is prefaced with its tier's contract.
+
 ## Quick Start
 
 _For new projects._
@@ -1220,7 +1239,7 @@ for await (const clientCredentials of zapier.listClientCredentials().items()) {
 
 ### Code Workflows (Experimental)
 
-> ℹ️ **Experimental.** Import from `"@zapier/zapier-sdk/experimental"` to use these methods. Methods and behavior may change.
+> ℹ️ **Experimental.** Still being designed; may change shape or disappear in any release, without notice. Import from `"@zapier/zapier-sdk/experimental"` to use these methods.
 
 #### `cancelDurableRun` 🧪 _experimental_
 
@@ -3016,7 +3035,7 @@ const result = await zapier.fetch("https://example.com", {});
 
 ### Human Inputs (Experimental)
 
-> ℹ️ **Experimental.** Import from `"@zapier/zapier-sdk/experimental"` to use these methods. Methods and behavior may change.
+> ℹ️ **Experimental.** Still being designed; may change shape or disappear in any release, without notice. Import from `"@zapier/zapier-sdk/experimental"` to use these methods.
 
 #### `createForm` 🧪 _experimental_
 
@@ -4357,7 +4376,7 @@ await zapier.watchTriggerInbox({
 
 ### Virtual File System (Experimental)
 
-> ℹ️ **Experimental.** Import from `"@zapier/zapier-sdk/experimental"` to use these methods. Methods and behavior may change.
+> ℹ️ **Experimental.** Still being designed; may change shape or disappear in any release, without notice. Import from `"@zapier/zapier-sdk/experimental"` to use these methods.
 
 #### `appendVfsFile` 🧪 _experimental_