@redis-iris/agent-playbook 0.1.0-alpha.3 → 0.1.0-beta.1

package/FUNCTIONS.md

@@ -1,9 +1,5 @@
 # Standalone Functions
 
-> [!NOTE]
-> This section is useful if you are using a bundler and targeting browsers and
-> runtimes where the size of an application affects performance and load times. 
-
 Every method in this SDK is also available as a standalone function. This
 alternative API is suitable when targeting the browser or serverless runtimes
 and using a bundler to build your application since all unused functionality
@@ -13,7 +9,7 @@ impact on the application's final bundle size which grows very slowly as you use
 more and more functionality from this SDK.
 
 Calling methods through the main SDK class remains a valid and generally more
-more ergonomic option. Standalone functions represent an optimisation for a
+ergonomic option. Standalone functions represent an optimisation for a
 specific category of applications.
 
 ## Example
@@ -27,7 +23,7 @@ import { discoverEntries } from "@redis-iris/agent-playbook/funcs/discover-entri
 const playbook = new PlaybookCore({
   serverURL: "https://api.example.com",
   playbookId: "<id>",
-  apiKey: "<PLAYBOOK_API_KEY>",
+  apiKey: "<AGENT_PLAYBOOKS_API_KEY>",
 });
 
 async function run() {
@@ -59,45 +55,15 @@ run();
 
 ## Result types
 
-Standalone functions differ from SDK methods in that they return a
-`Result<Value, Error>` type to capture _known errors_ and document them using
-the type system. By avoiding throwing errors, application code maintains clear
-control flow and error-handling become part of the regular flow of application
-code.
-
-> We use the term "known errors" because standalone functions, and JavaScript
-> code in general, can still throw unexpected errors such as `TypeError`s,
-> `RangeError`s and `DOMException`s. Exhaustively catching all errors may be
-> something this SDK addresses in the future. Nevertheless, there is still a lot
-> of benefit from capturing most errors and turning them into values.
-
-The second reason for this style of programming is because these functions will
-typically be used in front-end applications where exception throwing is
-sometimes discouraged or considered unidiomatic. React and similar ecosystems
-and libraries tend to promote this style of programming so that components
-render useful content under all states (loading, success, error and so on).
-
-The general pattern when calling standalone functions looks like this:
-
-```typescript
-import { Core } from "<sdk-package-name>";
-import { fetchSomething } from "<sdk-package-name>/funcs/fetchSomething.js";
-
-const client = new Core();
+Standalone functions return a `Result<Value, Error>` for known API, validation,
+and transport failures. Check `result.ok` before reading `result.value` or
+`result.error`. Unexpected failures, such as exceptions from caller-provided
+code, can still throw.
 
-async function run() {
-  const result = await fetchSomething(client, { id: "123" });
-  if (!result.ok) {
-    // You can throw the error or handle it. It's your choice now.
-    throw result.error;
-  }
-
-  console.log(result.value);
-}
-
-run();
-```
+Use `PlaybookCore` for data-plane functions and `AgentPlaybooksServiceCore` from
+`@redis-iris/agent-playbook/controlplane/core.js` for control-plane functions.
+Their credentials and model namespaces are independent. A control-plane example
+is included in the [control-plane reference](docs/controlplane/README.md#standalone-functions).
 
-Notably, `result.error` above will have an explicit type compared to a try-catch
-variation where the error in the catch block can only be of type `unknown` (or
-`any` depending on your TypeScript settings).
+The package release tests cover Node.js 20, 22, and 24. Browser, Bun, Deno, and
+serverless runtime compatibility has not been validated.

package/README.md

@@ -1,6 +1,6 @@
 # @redis-iris/agent-playbook
 
-TypeScript SDK for Redis Agent Playbook: author, publish, and retrieve FAQs and Skills.
+TypeScript SDK for Redis AgentPlaybooks: manage Playbooks and author, publish, and retrieve FAQs and Skills.
 
 [![Built by Speakeasy](https://img.shields.io/badge/Built_by-SPEAKEASY-374151?style=for-the-badge&labelColor=f3f4f6)](https://www.speakeasy.com/?utm_source=@redis-iris/agent-playbook&utm_campaign=typescript)
 [![License: MIT](https://img.shields.io/badge/LICENSE_//_MIT-3b5bdb?style=for-the-badge&labelColor=eff6ff)](https://opensource.org/licenses/MIT)
@@ -9,7 +9,7 @@ TypeScript SDK for Redis Agent Playbook: author, publish, and retrieve FAQs and
 <!-- Start Summary [summary] -->
 ## Summary
 
-Redis Playbook: Public type-specific FAQ and Skill authoring, publication, and exact-version API.
+Redis AgentPlaybooks: Public type-specific FAQ and Skill authoring, publication, and exact-version API.
 
 For more information about the API: [Redis AI documentation](https://redis.io/docs/latest/develop/ai/)
 <!-- End Summary [summary] -->
@@ -25,26 +25,153 @@ For more information about the API: [Redis AI documentation](https://redis.io/do
   broader product context; [npm](https://www.npmjs.com/package/@redis-iris/agent-playbook)
   lists published package versions.
 
-Dedicated Playbook product guides are required before a stable release. Until
-then, the examples and workflows on this page are the Playbook SDK guide.
+The examples and workflows on this page form the Playbook SDK guide. The Redis AI
+documentation provides broader product context.
+
+## Two clients, one package
+
+AgentPlaybooks is the product; a Playbook is one instance managed by a user or operator.
+
+`AgentPlaybooksService` manages Playbook resources on the control plane. `Playbook`
+performs content operations against one Playbook on the data plane. Each client
+has its own endpoint, credential, timeout, retry configuration, and HTTP transport.
+
+```typescript
+import { Playbook, AgentPlaybooksService } from "@redis-iris/agent-playbook";
+
+const service = new AgentPlaybooksService({
+  serverURL: process.env["AGENT_PLAYBOOKS_CONTROL_PLANE_URL"]!,
+  token: process.env["AGENT_PLAYBOOKS_SERVICE_TOKEN"]!,
+});
+const instance = await service.getPlaybook(process.env["AGENT_PLAYBOOKS_PLAYBOOK_ID"]!);
+const playbook = new Playbook({
+  serverURL: process.env["AGENT_PLAYBOOKS_DATA_PLANE_URL"]!,
+  apiKey: process.env["AGENT_PLAYBOOKS_API_KEY"]!,
+  playbookId: instance.playbookId,
+});
+const faqs = await playbook.listFaqs();
+console.log(faqs);
+```
+
+Set these connection values before running the example:
+
+| Variable | Value |
+| --- | --- |
+| `AGENT_PLAYBOOKS_CONTROL_PLANE_URL` | Your deployment's control-plane endpoint |
+| `AGENT_PLAYBOOKS_DATA_PLANE_URL` | Its separate data-plane endpoint |
+| `AGENT_PLAYBOOKS_SERVICE_TOKEN` | An authorized control-plane bearer token |
+| `AGENT_PLAYBOOKS_API_KEY` | An agent key scoped to the selected Playbook |
+| `AGENT_PLAYBOOKS_PLAYBOOK_ID` | The service-issued ID of that Playbook |
+| `AGENT_PLAYBOOKS_DEBUG` | Enable data-plane HTTP debug logging |
+| `AGENT_PLAYBOOKS_SERVICE_DEBUG` | Enable control-plane HTTP debug logging |
+
+The SDKs automatically read the API key, Playbook ID, service token, and debug
+settings when the corresponding constructor option is omitted. Explicit options
+win, followed by `AGENT_PLAYBOOKS_*` variables, then legacy aliases:
+`PLAYBOOK_API_KEY`, `PLAYBOOK_PLAYBOOK_ID`, `PLAYBOOK_DEBUG`,
+`PLAYBOOK_SERVICE_TOKEN`, and `PLAYBOOK_SERVICE_DEBUG`. An explicitly set empty
+new variable suppresses its legacy alias. These aliases do not modify the process
+environment or allow credentials to cross between the two clients.
+
+The URL variables above are application settings used by these examples. Both
+clients require an explicit `server_url` (Python) or `serverURL` (TypeScript);
+the core SDKs do not automatically read URLs from the environment.
+
+Use an authorized control-plane bearer token for `token` and a resource-scoped
+agent key for `apiKey`. TypeScript accepts an async credential provider for either
+argument. Pass environment variables explicitly, as above. Creating a Playbook
+does not mint a data-plane key; obtain that key through your deployment's Identity
+Service. A freshly created resource may need to reach `ready` before DP calls.
+
+Control-plane methods take resource IDs per operation, such as
+`service.getPlaybook(playbookId)`. Existing data-plane methods and constructor
+arguments are unchanged. Both clients support `timeoutMs`, `retryConfig`,
+`debugLogger`, and a custom `httpClient`; neither retries requests by default.
+For a CP custom transport, import `HTTPClient` from
+`@redis-iris/agent-playbook/controlplane`. The root `HTTPClient` export belongs to
+DP. The two generated transport classes have separate TypeScript identities;
+they can wrap the same caller-supplied fetch function.
+
+Control-plane types are isolated under
+`@redis-iris/agent-playbook/controlplane/models`, with errors under
+`@redis-iris/agent-playbook/controlplane/models/errors`. The existing `/models`
+and `/models/errors` exports remain data-plane types. `AgentPlaybooksServiceOptions`
+is exported at the package root. See the control-plane reference
+for provisioning, lifecycle, clear, and extraction-management operations.
+
+The control-plane client covers:
+
+| Task | Methods |
+| --- | --- |
+| Provision and manage instances | `createPlaybook`, `listPlaybooks`, `getPlaybook`, `updatePlaybook`, `deletePlaybook` |
+| Clear content administratively | `clearPlaybook` (requires `product_admin` or `suite_admin`) |
+| Manage extraction | `listExtractionStores`, `listExtractionBindings`, `createExtractionBinding`, `getExtractionBinding`, `updateExtractionBinding`, `deleteExtractionBinding` |
+| Discover supported models | `listModels` |
+| Discover cloud resources | `listDatabases`, `getNetworkInfo` |
+| Manage cloud model credentials | `getModelCredential`, `putModelCredential`, `deleteModelCredential` |
+
+### Deployment availability
+
+The shared control-plane operations work with both cloud and on-prem deployments.
+`listModels` lists the deployment’s supported models, including the on-prem
+embedding allowlist. `listDatabases`, `getNetworkInfo`, `getModelCredential`,
+`putModelCredential`, and `deleteModelCredential` are **cloud only**. Their generated method documentation
+is labeled `Cloud only`.
+
+The optional `llm` field on create/update and resource responses is also **cloud
+only**. Omit it for on-prem requests; on-prem responses do not contain it. No
+constructor deployment flag is required: configure the appropriate endpoint.
+Credential reads return status only, never a provider API key. These provider
+credentials are separate from the control-plane token and data-plane agent key.
+
+Cloud resource management and database discovery require the cloud session
+cookie (`JSESSIONID`) and CSRF header (`X-CSRF-Token`) in addition to the operator
+token; supply these through the client’s HTTP transport. Cloud
+responses expose typed endpoint accessibility, egress addresses, and database
+network metadata. These optional fields may be absent on-prem.
+
+### Extraction binding access and readiness
+
+Store suggestions are scoped to the tenant and do not grant access. When creating
+an extraction binding, the deployment's admin token can bind any store; an OIDC caller needs
+a deployment-configured store or read access approved by the Identity Service
+through a configured RAM connection. Unauthorized requests return 403 without
+revealing whether the store exists.
+
+A new binding starts in `preparing` with `enabled=false`. Poll the binding until
+it is `ready`, then enable it with an update that passes its `version` as `expectedVersion`.
+Refused grants produce `blocked`; dependency outages remain pending for retry.
+Enabling extraction also requires the deployment's extraction feature to be enabled.
 
 ## Release status
 
-This SDK is an alpha prerelease. Breaking changes may land between alpha releases
-without a major-version increment. The prepared npm release is `0.1.0-alpha.3`,
-matching Python `0.1.0a3`. Install an exact published version and upgrade intentionally:
+This SDK is a beta prerelease. Breaking changes may land between beta releases
+without a major-version increment. The prepared npm release is `0.1.0-beta.1`,
+matching Python `0.1.0b1`. Install an exact published version and upgrade intentionally:
 
 ```bash
-npm install @redis-iris/agent-playbook@0.1.0-alpha.3
+npm install @redis-iris/agent-playbook@0.1.0-beta.1
 ```
 
 Node.js 20 or later is required. Both ESM and CommonJS imports are supported.
 
 The generated snippets below use `<id>`, `https://api.example.com`, and
-`<PLAYBOOK_API_KEY>` as placeholders. Replace them with your deployment URL,
+`<AGENT_PLAYBOOKS_API_KEY>` as placeholders. Replace them with your deployment URL,
 bearer token, and service-issued IDs before running a snippet. In particular,
 `<id>` does not satisfy the Playbook ID format and is rejected before a request.
 
+## Upgrading to beta.1
+
+The control-plane client is now `AgentPlaybooksService`, replacing
+`PlaybookService` without a compatibility alias. Update imports from both
+`@redis-iris/agent-playbook` and `@redis-iris/agent-playbook/controlplane`.
+Rename `PlaybookServiceOptions` to `AgentPlaybooksServiceOptions`, and import
+`AgentPlaybooksServiceError` from the control-plane errors subpath in place of
+`PlaybookServiceError`. The data-plane client remains `Playbook`. Environment variables now use the
+product prefix `AGENT_PLAYBOOKS`; the previous runtime names remain fallback
+aliases as described above. Endpoints are unchanged. Both clients are regenerated
+from the same Iris main revision recorded in the contract provenance.
+
 ## Upgrading from alpha.2
 
 Alpha.3 requires a server with the updated proposal contract. Publish both SDKs
@@ -60,8 +187,9 @@ SHA-1 or SHA-256 revision. Omit unavailable metadata and retain the original
 observation timestamp for retries. Creation `source` is immutable and does not
 increment `evidenceCount`/`evidence_count`. Proposal list/search support action and
 entry type selectors. `listProposals` now takes optional `actionType` and `entryType`
-before `RequestOptions`; move positional options to the eighth argument. The public clear operation and its models have been removed;
-use explicit FAQ/Skill deletion operations when needed.
+before `RequestOptions`; move positional options to the eighth argument. The data-plane clear operation and its models have been removed;
+use explicit FAQ/Skill deletion operations when needed. Administrative clear is
+available separately through `AgentPlaybooksService.clearPlaybook`.
 
 Proposal input content is distinct from normalized read content; only FAQ-add
 proposals are supported. Future response union members are retained in `raw`
@@ -75,7 +203,9 @@ contract for future actions without content.
 <!-- $toc-max-depth=2 -->
 * [@redis-iris/agent-playbook](#redis-irisagent-playbook)
   * [Documentation](#documentation)
+  * [Two clients, one package](#two-clients-one-package)
   * [Release status](#release-status)
+  * [Upgrading to beta.1](#upgrading-to-beta1)
   * [Upgrading from alpha.2](#upgrading-from-alpha2)
   * [SDK Installation](#sdk-installation)
   * [Requirements](#requirements)
@@ -102,25 +232,25 @@ The SDK can be installed with either [npm](https://www.npmjs.com/), [pnpm](https
 ### NPM
 
 ```bash
-npm add @redis-iris/agent-playbook@0.1.0-alpha.3
+npm add @redis-iris/agent-playbook@0.1.0-beta.1
 ```
 
 ### PNPM
 
 ```bash
-pnpm add @redis-iris/agent-playbook@0.1.0-alpha.3
+pnpm add @redis-iris/agent-playbook@0.1.0-beta.1
 ```
 
 ### Bun
 
 ```bash
-bun add @redis-iris/agent-playbook@0.1.0-alpha.3
+bun add @redis-iris/agent-playbook@0.1.0-beta.1
 ```
 
 ### Yarn
 
 ```bash
-yarn add @redis-iris/agent-playbook@0.1.0-alpha.3
+yarn add @redis-iris/agent-playbook@0.1.0-beta.1
 ```
 
 > [!NOTE]
@@ -131,7 +261,7 @@ yarn add @redis-iris/agent-playbook@0.1.0-alpha.3
 
 Node.js 20 or later is required. CI validates Node 20, 22, and 24, including
 ESM and CommonJS imports. The client uses Fetch and Web Streams APIs. Browser,
-Bun, and Deno compatibility has not been validated for this alpha release.
+Bun, and Deno compatibility has not been validated for this beta release.
 <!-- No Requirements [requirements] -->
 
 <!-- Start SDK Example Usage [usage] -->
@@ -147,7 +277,7 @@ import { Playbook } from "@redis-iris/agent-playbook";
 const playbook = new Playbook({
   serverURL: "https://api.example.com",
   playbookId: "<id>",
-  apiKey: "<PLAYBOOK_API_KEY>",
+  apiKey: "<AGENT_PLAYBOOKS_API_KEY>",
 });
 
 async function run() {
@@ -194,7 +324,7 @@ import { Playbook } from "@redis-iris/agent-playbook";
 const playbook = new Playbook({
   serverURL: "https://api.example.com",
   playbookId: "<id>",
-  apiKey: "<PLAYBOOK_API_KEY>",
+  apiKey: "<AGENT_PLAYBOOKS_API_KEY>",
 });
 
 async function run() {
@@ -244,7 +374,7 @@ import { Playbook } from "@redis-iris/agent-playbook";
 const playbook = new Playbook({
   serverURL: "https://api.example.com",
   playbookId: "<id>",
-  apiKey: "<PLAYBOOK_API_KEY>",
+  apiKey: "<AGENT_PLAYBOOKS_API_KEY>",
 });
 
 async function run() {
@@ -272,7 +402,7 @@ import { Playbook } from "@redis-iris/agent-playbook";
 const playbook = new Playbook({
   serverURL: "https://api.example.com",
   playbookId: "<id>",
-  apiKey: "<PLAYBOOK_API_KEY>",
+  apiKey: "<AGENT_PLAYBOOKS_API_KEY>",
 });
 
 async function run() {
@@ -313,7 +443,7 @@ import { Playbook } from "@redis-iris/agent-playbook";
 const playbook = new Playbook({
   serverURL: "https://api.example.com",
   playbookId: "<id>",
-  apiKey: "<PLAYBOOK_API_KEY>",
+  apiKey: "<AGENT_PLAYBOOKS_API_KEY>",
 });
 
 async function run() {
@@ -356,7 +486,7 @@ import { Playbook } from "@redis-iris/agent-playbook";
 const playbook = new Playbook({
   serverURL: "https://api.example.com",
   playbookId: "<id>",
-  apiKey: "<PLAYBOOK_API_KEY>",
+  apiKey: "<AGENT_PLAYBOOKS_API_KEY>",
 });
 
 async function run() {
@@ -389,7 +519,7 @@ import { Playbook } from "@redis-iris/agent-playbook";
 const playbook = new Playbook({
   serverURL: "https://api.example.com",
   playbookId: "<id>",
-  apiKey: "<PLAYBOOK_API_KEY>",
+  apiKey: "<AGENT_PLAYBOOKS_API_KEY>",
 });
 
 async function run() {
@@ -426,7 +556,7 @@ import { Playbook } from "@redis-iris/agent-playbook";
 const playbook = new Playbook({
   serverURL: "https://api.example.com",
   playbookId: "<id>",
-  apiKey: "<PLAYBOOK_API_KEY>",
+  apiKey: "<AGENT_PLAYBOOKS_API_KEY>",
 });
 
 async function run() {
@@ -483,7 +613,7 @@ import { Playbook } from "@redis-iris/agent-playbook";
 const playbook = new Playbook({
   serverURL: "https://api.example.com",
   playbookId: "<id>",
-  apiKey: "<PLAYBOOK_API_KEY>",
+  apiKey: "<AGENT_PLAYBOOKS_API_KEY>",
 });
 
 async function run() {
@@ -525,7 +655,7 @@ import { Playbook } from "@redis-iris/agent-playbook";
 const playbook = new Playbook({
   serverURL: "https://api.example.com",
   playbookId: "<id>",
-  apiKey: "<PLAYBOOK_API_KEY>",
+  apiKey: "<AGENT_PLAYBOOKS_API_KEY>",
 });
 
 async function run() {
@@ -561,7 +691,7 @@ import { Playbook } from "@redis-iris/agent-playbook";
 const playbook = new Playbook({
   serverURL: "https://api.example.com",
   playbookId: "pb_0123456789abcdef0123456789abcdef",
-  apiKey: "<PLAYBOOK_API_KEY>",
+  apiKey: "<AGENT_PLAYBOOKS_API_KEY>",
 });
 const content = {
   intents: ["Where is my refund?"],
@@ -596,7 +726,7 @@ import { readFile } from "node:fs/promises";
 import { Playbook } from "@redis-iris/agent-playbook";
 
 const playbook = new Playbook({ serverURL: "https://api.example.com",
-  playbookId: "pb_0123456789abcdef0123456789abcdef", apiKey: "<PLAYBOOK_API_KEY>" });
+  playbookId: "pb_0123456789abcdef0123456789abcdef", apiKey: "<AGENT_PLAYBOOKS_API_KEY>" });
 const content = { intents: ["Resolve a late delivery"], attributes: { audience: "support" } };
 const created = await playbook.createSkill({ entryKey: "late-delivery-resolution", content,
   packageBase64: (await readFile("late-delivery-resolution-v1.zip")).toString("base64") });
@@ -615,7 +745,7 @@ console.log(await playbook.listSkills(), await playbook.listSkillVersions(skillI
 import { Playbook } from "@redis-iris/agent-playbook";
 
 const playbook = new Playbook({ serverURL: "https://api.example.com",
-  playbookId: "pb_0123456789abcdef0123456789abcdef", apiKey: "<PLAYBOOK_API_KEY>" });
+  playbookId: "pb_0123456789abcdef0123456789abcdef", apiKey: "<AGENT_PLAYBOOKS_API_KEY>" });
 const filter = { eq: { name: "audience", value: "support" } };
 console.log(await playbook.searchFaqs({ query: "Where is my refund?", filter, minimumScore: 0.72, limit: 5 }));
 console.log(await playbook.searchSkills({ query: "Resolve a late delivery", filter, minimumScore: 0.72, limit: 5 }));
@@ -645,7 +775,7 @@ import { randomUUID } from "node:crypto";
 import { Playbook } from "@redis-iris/agent-playbook";
 
 const playbook = new Playbook({ serverURL: "https://api.example.com",
-  playbookId: "pb_0123456789abcdef0123456789abcdef", apiKey: "<PLAYBOOK_API_KEY>" });
+  playbookId: "pb_0123456789abcdef0123456789abcdef", apiKey: "<AGENT_PLAYBOOKS_API_KEY>" });
 const action = { add: { target: { newEntry: { entryKey: "refund-bank-delay" } },
   candidate: { content: { payload: { faq: { question: "Why hasn't my refund appeared?",
     answer: "The issuing bank controls final posting time." } } } } } };
@@ -701,7 +831,7 @@ import { createHash } from "node:crypto";
 import { Playbook } from "@redis-iris/agent-playbook";
 
 const playbook = new Playbook({ serverURL: "https://api.example.com",
-  playbookId: "pb_0123456789abcdef0123456789abcdef", apiKey: "<PLAYBOOK_API_KEY>" });
+  playbookId: "pb_0123456789abcdef0123456789abcdef", apiKey: "<AGENT_PLAYBOOKS_API_KEY>" });
 const skillId = "ent_0123456789abcdef0123456789abcdef";
 const version = await playbook.getSkillVersion(skillId, 1);
 if (!("skill" in version.content.payload)) throw new Error("Expected a Skill payload");
@@ -723,9 +853,9 @@ if (descriptor.digest !== "sha256:" + digest.toString("hex") || header !== "sha-
 
 This SDK supports the following security scheme globally:
 
-| Name     | Type | Scheme      | Environment Variable |
-| -------- | ---- | ----------- | -------------------- |
-| `apiKey` | http | HTTP Bearer | `PLAYBOOK_API_KEY`   |
+| Name     | Type | Scheme      | Environment Variable      |
+| -------- | ---- | ----------- | ------------------------- |
+| `apiKey` | http | HTTP Bearer | `AGENT_PLAYBOOKS_API_KEY` |
 
 To authenticate with the API the `apiKey` parameter must be set when initializing the SDK client instance. For example:
 ```typescript
@@ -733,7 +863,7 @@ import { Playbook } from "@redis-iris/agent-playbook";
 
 const playbook = new Playbook({
   serverURL: "https://api.example.com",
-  apiKey: "<PLAYBOOK_API_KEY>",
+  apiKey: "<AGENT_PLAYBOOKS_API_KEY>",
   playbookId: "<id>",
 });
 
@@ -888,7 +1018,7 @@ digest bytes and must not be compared as strings.
 ## Global Parameters
 
 A client is bound to one Playbook. Set `playbookId` in the constructor or set the
-`PLAYBOOK_PLAYBOOK_ID` environment variable. The constructor option takes precedence.
+`AGENT_PLAYBOOKS_PLAYBOOK_ID` environment variable. The constructor option takes precedence.
 Methods do not expose a per-operation `playbookId` override; create another client
 to use a different Playbook. Supply `serverURL` explicitly for each client.
 
@@ -898,7 +1028,7 @@ import { Playbook } from "@redis-iris/agent-playbook";
 const playbook = new Playbook({
   serverURL: "https://api.example.com",
   playbookId: "pb_0123456789abcdef0123456789abcdef",
-  apiKey: "<PLAYBOOK_API_KEY>",
+  apiKey: "<AGENT_PLAYBOOKS_API_KEY>",
 });
 const result = await playbook.getPlaybookHealth();
 console.log(result);
@@ -940,7 +1070,7 @@ import * as errors from "@redis-iris/agent-playbook/models/errors";
 const playbook = new Playbook({
   serverURL: "https://api.example.com",
   playbookId: "<id>",
-  apiKey: "<PLAYBOOK_API_KEY>",
+  apiKey: "<AGENT_PLAYBOOKS_API_KEY>",
 });
 
 async function run() {
@@ -1068,7 +1198,7 @@ httpClient.addHook("requestError", (error, request) => {
   console.groupEnd();
 });
 
-const sdk = new Playbook({ serverURL: "https://api.example.com",
+const playbook = new Playbook({ serverURL: "https://api.example.com",
   playbookId: "pb_0123456789abcdef0123456789abcdef", httpClient });
 ```
 <!-- No Custom HTTP Client [http-client] -->
@@ -1085,11 +1215,11 @@ You can pass a logger that matches `console`'s interface as an SDK option.
 ```typescript
 import { Playbook } from "@redis-iris/agent-playbook";
 
-const sdk = new Playbook({ serverURL: "https://api.example.com",
+const playbook = new Playbook({ serverURL: "https://api.example.com",
   playbookId: "pb_0123456789abcdef0123456789abcdef", debugLogger: console });
 ```
 
-You can also enable a default debug logger by setting an environment variable `PLAYBOOK_DEBUG` to true.
+You can also enable a default debug logger by setting an environment variable `AGENT_PLAYBOOKS_DEBUG` to true.
 <!-- No Debugging [debug] -->
 
 <!-- Placeholder for Future Speakeasy SDK Sections -->
@@ -1098,7 +1228,7 @@ You can also enable a default debug logger by setting an environment variable `P
 
 ## Maturity
 
-This SDK is an alpha prerelease. Pin an exact published version and upgrade intentionally.
+This SDK is a beta prerelease. Pin an exact published version and upgrade intentionally.
 
 ## Contributions
 

package/RUNTIMES.md

@@ -10,7 +10,7 @@ This SDK is intended to be used in JavaScript runtimes that support ECMAScript 2
 [web-streams]: https://developer.mozilla.org/en-US/docs/Web/API/Streams_API
 [async-iter]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols
 
-This alpha package requires **Node.js 20 or later**. CI validates Node 20, 22,
+This beta package requires **Node.js 20 or later**. CI validates Node 20, 22,
 and 24, including ESM and CommonJS imports, compiled TypeScript declarations,
 HTTP behavior, and the packed npm artifact.
 

package/dist/commonjs/controlplane/core.d.ts

@@ -0,0 +1,10 @@
+import { ClientSDK } from "./lib/sdks.js";
+/**
+ * A minimal client to use when calling standalone SDK functions. Typically, an
+ * instance of this class would be instantiated once at the start of an
+ * application and passed around through some dependency injection mechanism  to
+ * parts of an application that need to make SDK calls.
+ */
+export declare class AgentPlaybooksServiceCore extends ClientSDK {
+}
+//# sourceMappingURL=core.d.ts.map

package/dist/commonjs/controlplane/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/controlplane/core.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,SAAS;CAAG"}

package/dist/commonjs/controlplane/core.js

@@ -0,0 +1,17 @@
+"use strict";
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentPlaybooksServiceCore = void 0;
+const sdks_js_1 = require("./lib/sdks.js");
+/**
+ * A minimal client to use when calling standalone SDK functions. Typically, an
+ * instance of this class would be instantiated once at the start of an
+ * application and passed around through some dependency injection mechanism  to
+ * parts of an application that need to make SDK calls.
+ */
+class AgentPlaybooksServiceCore extends sdks_js_1.ClientSDK {
+}
+exports.AgentPlaybooksServiceCore = AgentPlaybooksServiceCore;
+//# sourceMappingURL=core.js.map

package/dist/commonjs/controlplane/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../../src/controlplane/core.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,2CAA0C;AAE1C;;;;;GAKG;AACH,+BAAuC,SAAQ,mBAAS;CAAG"}

package/dist/commonjs/controlplane/funcs/clear-playbook.d.ts

@@ -0,0 +1,15 @@
+import { AgentPlaybooksServiceCore } from "../core.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { AgentPlaybooksServiceError } from "../models/errors/agent-playbooks-service-error.js";
+import { ConnectionError, InvalidRequestError, RequestAbortedError, RequestTimeoutError, UnexpectedClientError } from "../models/errors/http-client-errors.js";
+import * as errors from "../models/errors/index.js";
+import { ResponseValidationError } from "../models/errors/response-validation-error.js";
+import { SDKValidationError } from "../models/errors/sdk-validation-error.js";
+import * as models from "../models/index.js";
+import { APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+/**
+ * Administratively clears all (default), entries, or proposals from a ready Playbook, preserving configuration and index readiness. Requires product_admin or suite_admin. Cleanup is not atomic across content: failures can leave partial progress; retry the same scope after resolving the failure. Without new writes, repeating a successful clear removes no additional entry families.
+ */
+export declare function clearPlaybook(client: AgentPlaybooksServiceCore, playbookId: string, scope?: models.ClearScope | undefined, options?: RequestOptions): APIPromise<Result<models.ClearPlaybookResponseContent, errors.BadRequestErrorResponseContent | errors.AuthenticationErrorResponseContent | errors.ExtractionForbiddenErrorResponseContent | errors.NotFoundErrorResponseContent | errors.TimeoutErrorResponseContent | errors.ResourceSuspendedErrorResponseContent | errors.FailedDependencyErrorResponseContent | errors.UnexpectedErrorResponseContent | errors.PlaybookServiceUnavailableErrorResponseContent | AgentPlaybooksServiceError | ResponseValidationError | ConnectionError | RequestAbortedError | RequestTimeoutError | InvalidRequestError | UnexpectedClientError | SDKValidationError>>;
+//# sourceMappingURL=clear-playbook.d.ts.map

package/dist/commonjs/controlplane/funcs/clear-playbook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clear-playbook.d.ts","sourceRoot":"","sources":["../../../../src/controlplane/funcs/clear-playbook.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAMvD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,EAAE,0BAA0B,EAAE,MAAM,mDAAmD,CAAC;AAC/F,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,MAAM,MAAM,2BAA2B,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,+CAA+C,CAAC;AACxF,OAAO,EAAE,kBAAkB,EAAE,MAAM,0CAA0C,CAAC;AAC9E,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAC;AAE7C,OAAO,EAAW,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC;;GAEG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,yBAAyB,EACjC,UAAU,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,EACrC,OAAO,CAAC,EAAE,cAAc,GACvB,UAAU,CACX,MAAM,CACJ,MAAM,CAAC,4BAA4B,EACjC,MAAM,CAAC,8BAA8B,GACrC,MAAM,CAAC,kCAAkC,GACzC,MAAM,CAAC,uCAAuC,GAC9C,MAAM,CAAC,4BAA4B,GACnC,MAAM,CAAC,2BAA2B,GAClC,MAAM,CAAC,qCAAqC,GAC5C,MAAM,CAAC,oCAAoC,GAC3C,MAAM,CAAC,8BAA8B,GACrC,MAAM,CAAC,8CAA8C,GACrD,0BAA0B,GAC1B,uBAAuB,GACvB,eAAe,GACf,mBAAmB,GACnB,mBAAmB,GACnB,mBAAmB,GACnB,qBAAqB,GACrB,kBAAkB,CACrB,CACF,CAOA"}