@redis-iris/agent-playbook 0.0.0-stage → 0.1.0-alpha.3

package/README.md

@@ -1,3 +1,1108 @@
-# Temporary Holding Version
+# @redis-iris/agent-playbook
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript SDK for Redis Agent Playbook: 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)
+
+
+<!-- Start Summary [summary] -->
+## Summary
+
+Redis Playbook: 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] -->
+
+## Documentation
+
+- [SDK examples](#sdk-example-usage) show FAQ and Skill authoring, search,
+  discovery, and proposal review.
+- [Common workflows](#common-workflows) cover versioning, publication,
+  pagination, and exact Skill resource verification.
+- [Available methods](#available-resources-and-operations) list the client API.
+- [Redis AI documentation](https://redis.io/docs/latest/develop/ai/) provides
+  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.
+
+## 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:
+
+```bash
+npm install @redis-iris/agent-playbook@0.1.0-alpha.3
+```
+
+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,
+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 from alpha.2
+
+Alpha.3 requires a server with the updated proposal contract. Publish both SDKs
+only after the corresponding data-plane rollout is ready. Acceptance returns a
+historical `result.versionCreated` receipt (Python: `result.version_created`)
+instead of top-level entry/version objects. It does not establish current target
+existence or publication; publishing remains a separate operation.
+
+Remove evidence `schemaVersion` (Python: `schema_version`) and producer `version`.
+Producer `name` is required; optional `promptVersion`/`prompt_version` identifies
+the actual prompt set, and `commitSHA`/`commit_sha` accepts a full lowercase Git
+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.
+
+Proposal input content is distinct from normalized read content; only FAQ-add
+proposals are supported. Future response union members are retained in `raw`
+(Python: `UnknownProposalMember`; TypeScript: `isUnknown: true`). Inspect or upgrade
+before acting on an unknown response. Unknown members do not enable new writes.
+Proposal `contentDigest`/`content_digest` is optional in the general response
+contract for future actions without content.
+
+<!-- Start Table of Contents [toc] -->
+## Table of Contents
+<!-- $toc-max-depth=2 -->
+* [@redis-iris/agent-playbook](#redis-irisagent-playbook)
+  * [Documentation](#documentation)
+  * [Release status](#release-status)
+  * [Upgrading from alpha.2](#upgrading-from-alpha2)
+  * [SDK Installation](#sdk-installation)
+  * [Requirements](#requirements)
+  * [SDK Example Usage](#sdk-example-usage)
+  * [Common workflows](#common-workflows)
+  * [Authentication](#authentication)
+  * [Available Resources and Operations](#available-resources-and-operations)
+  * [Standalone functions](#standalone-functions)
+  * [Global Parameters](#global-parameters)
+  * [Retries](#retries)
+  * [Error Handling](#error-handling)
+  * [Custom HTTP Client](#custom-http-client)
+  * [Debugging](#debugging)
+* [Development](#development)
+  * [Maturity](#maturity)
+  * [Contributions](#contributions)
+
+<!-- End Table of Contents [toc] -->
+
+## SDK Installation
+
+The SDK can be installed with either [npm](https://www.npmjs.com/), [pnpm](https://pnpm.io/), [bun](https://bun.sh/) or [yarn](https://classic.yarnpkg.com/en/) package managers.
+
+### NPM
+
+```bash
+npm add @redis-iris/agent-playbook@0.1.0-alpha.3
+```
+
+### PNPM
+
+```bash
+pnpm add @redis-iris/agent-playbook@0.1.0-alpha.3
+```
+
+### Bun
+
+```bash
+bun add @redis-iris/agent-playbook@0.1.0-alpha.3
+```
+
+### Yarn
+
+```bash
+yarn add @redis-iris/agent-playbook@0.1.0-alpha.3
+```
+
+> [!NOTE]
+> This package is published with CommonJS and ES Modules (ESM) support.
+<!-- No SDK Installation [installation] -->
+
+## Requirements
+
+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.
+<!-- No Requirements [requirements] -->
+
+<!-- Start SDK Example Usage [usage] -->
+## SDK Example Usage
+
+### Create an FAQ
+
+Create the first immutable version of a customer-support FAQ. The returned entry is an unpublished draft.
+
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+
+const playbook = new Playbook({
+  serverURL: "https://api.example.com",
+  playbookId: "<id>",
+  apiKey: "<PLAYBOOK_API_KEY>",
+});
+
+async function run() {
+  const result = await playbook.createFaq({
+    content: {
+      intents: [
+        "Where is my refund?",
+        "Refund still processing",
+      ],
+      attributes: {
+        "audience": "support",
+        "locale": "en-US",
+        "topic": "refund",
+      },
+      metadata: {
+        "sourceId": "support-refund-policy-v4",
+        "status": "approved",
+      },
+      payload: {
+        faq: {
+          question: "How can support check the status of an in-flight refund?",
+          answer:
+            "Look up the refund by order ID, share its current stage and date, and do not promise a bank posting date.",
+        },
+      },
+    },
+    entryKey: "refund-status-check",
+  });
+
+  console.log(result);
+}
+
+run();
+
+```
+
+### Add an FAQ version
+
+Append an immutable version to an existing FAQ. Replace the example ID with the entry ID returned by `create_faq`.
+
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+
+const playbook = new Playbook({
+  serverURL: "https://api.example.com",
+  playbookId: "<id>",
+  apiKey: "<PLAYBOOK_API_KEY>",
+});
+
+async function run() {
+  const result = await playbook.appendFaqVersion(
+    "ent_0123456789abcdef0123456789abcdef",
+    {
+      content: {
+        intents: [
+          "Where is my refund?",
+          "Check refund progress",
+        ],
+        attributes: {
+          "audience": "support",
+          "locale": "en-US",
+          "topic": "refund",
+        },
+        metadata: {
+          "sourceId": "support-refund-policy-v5",
+          "status": "approved",
+        },
+        payload: {
+          faq: {
+            question:
+              "How can support check the status of an in-flight refund?",
+            answer:
+              "Look up the refund by order ID and share its current stage and date. Card refunds normally post 5 to 10 business days after warehouse receipt.",
+          },
+        },
+      },
+    },
+  );
+
+  console.log(result);
+}
+
+run();
+
+```
+
+### Publish an FAQ version
+
+Publish the selected immutable FAQ version so it can be returned by search and discovery.
+
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+
+const playbook = new Playbook({
+  serverURL: "https://api.example.com",
+  playbookId: "<id>",
+  apiKey: "<PLAYBOOK_API_KEY>",
+});
+
+async function run() {
+  const result = await playbook.publishFaq(
+    "ent_0123456789abcdef0123456789abcdef",
+    {
+      version: 2,
+    },
+  );
+
+  console.log(result);
+}
+
+run();
+
+```
+
+### Create a Skill
+
+Create an unpublished Skill from a base64-encoded Agent Skills ZIP. Replace the package placeholder with an encoded archive rooted at `late-delivery-resolution/` and containing `SKILL.md`.
+
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+
+const playbook = new Playbook({
+  serverURL: "https://api.example.com",
+  playbookId: "<id>",
+  apiKey: "<PLAYBOOK_API_KEY>",
+});
+
+async function run() {
+  const result = await playbook.createSkill({
+    packageBase64: "BASE64_ENCODED_AGENT_SKILL_ZIP",
+    content: {
+      intents: [
+        "Resolve a late delivery",
+        "Package has not arrived",
+      ],
+      attributes: {
+        "audience": "support",
+        "locale": "en-US",
+        "topic": "delivery",
+      },
+      metadata: {
+        "sourceId": "runbook-late-delivery-v1",
+        "status": "approved",
+      },
+    },
+    entryKey: "late-delivery-resolution",
+  });
+
+  console.log(result);
+}
+
+run();
+
+```
+
+### Search FAQs
+
+Search only published FAQs, restrict results to exact-match attributes, and override the similarity threshold for this request.
+
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+
+const playbook = new Playbook({
+  serverURL: "https://api.example.com",
+  playbookId: "<id>",
+  apiKey: "<PLAYBOOK_API_KEY>",
+});
+
+async function run() {
+  const result = await playbook.searchFaqs({
+    query: "Where is my refund?",
+    filter: {
+      and: [
+        {
+          eq: {
+            name: "audience",
+            value: "support",
+          },
+        },
+        {
+          eq: {
+            name: "locale",
+            value: "en-US",
+          },
+        },
+      ],
+    },
+    minimumScore: 0.72,
+    limit: 5,
+  });
+
+  console.log(result);
+}
+
+run();
+
+```
+
+### Search Skills
+
+Search only published Skills. Skill matches contain compact previews with canonical exact-version `SKILL.md` URIs.
+
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+
+const playbook = new Playbook({
+  serverURL: "https://api.example.com",
+  playbookId: "<id>",
+  apiKey: "<PLAYBOOK_API_KEY>",
+});
+
+async function run() {
+  const result = await playbook.searchSkills({
+    query: "How should I resolve a delayed delivery?",
+    filter: {
+      eq: {
+        name: "audience",
+        value: "support",
+      },
+    },
+    minimumScore: 0.72,
+    limit: 5,
+  });
+
+  console.log(result);
+}
+
+run();
+
+```
+
+### Discover Playbook entries
+
+Search published FAQs and Skills together while pinning a known Skill by its immutable entry key. Pins are returned separately from semantic matches.
+
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+
+const playbook = new Playbook({
+  serverURL: "https://api.example.com",
+  playbookId: "<id>",
+  apiKey: "<PLAYBOOK_API_KEY>",
+});
+
+async function run() {
+  const result = await playbook.discoverEntries({
+    query: "A customer's order is late and they want a refund",
+    filter: {
+      eq: {
+        name: "audience",
+        value: "support",
+      },
+    },
+    limit: 10,
+    pinnedEntries: [
+      {
+        entryKey: "late-delivery-resolution",
+      },
+    ],
+  });
+
+  console.log(result);
+}
+
+run();
+
+```
+
+### Create a proposal
+
+Propose a new FAQ for review. Launch proposal authoring supports new FAQ entries.
+
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+
+const playbook = new Playbook({
+  serverURL: "https://api.example.com",
+  playbookId: "<id>",
+  apiKey: "<PLAYBOOK_API_KEY>",
+});
+
+async function run() {
+  const result = await playbook.createProposal({
+    action: {
+      add: {
+        target: {
+          newEntry: {
+            entryKey: "refund-bank-delay",
+          },
+        },
+        candidate: {
+          content: {
+            intents: [
+              "My refund has not appeared",
+            ],
+            attributes: {
+              "audience": "support",
+              "locale": "en-US",
+              "topic": "refund",
+            },
+            metadata: {
+              "sourceId": "support-refund-policy-v5",
+              "status": "proposed",
+            },
+            payload: {
+              faq: {
+                question:
+                  "What should support say when a settled refund has not appeared?",
+                answer:
+                  "Confirm the settlement date and explain that the issuing bank controls final posting time.",
+              },
+            },
+          },
+        },
+      },
+    },
+  });
+
+  console.log(result);
+}
+
+run();
+
+```
+
+### Submit proposal evidence
+
+Attach immutable source context to an open proposal. Reuse the same evidence ID and payload when retrying; evidence is retained on the proposal and is not copied to the accepted FAQ.
+
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+
+const playbook = new Playbook({
+  serverURL: "https://api.example.com",
+  playbookId: "<id>",
+  apiKey: "<PLAYBOOK_API_KEY>",
+});
+
+async function run() {
+  const result = await playbook.submitProposalEvidence(
+    "prp_0123456789abcdef0123456789abcdef",
+    "evd_0123456789abcdef0123456789abcdef",
+    {
+      observedAt: new Date("2026-09-29T16:00:00Z"),
+      producer: {
+        name: "support-review",
+        promptVersion: "support-review-v1",
+      },
+      source: {
+        type: "document",
+        reference: {
+          "documentId": "support-refund-policy-v5",
+        },
+        content: {
+          "excerpt": "The issuing bank controls final refund posting time.",
+        },
+      },
+    },
+  );
+
+  console.log(result);
+}
+
+run();
+
+```
+
+### Accept a proposal
+
+Promote the reviewed revision to one canonical unpublished FAQ. Concurrent calls and retries resume or return the recorded target.
+
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+
+const playbook = new Playbook({
+  serverURL: "https://api.example.com",
+  playbookId: "<id>",
+  apiKey: "<PLAYBOOK_API_KEY>",
+});
+
+async function run() {
+  const result = await playbook.acceptProposal(
+    "prp_0123456789abcdef0123456789abcdef",
+    {
+      expectedProposalRevision: 1,
+    },
+  );
+
+  console.log(result);
+}
+
+run();
+
+```
+<!-- End SDK Example Usage [usage] -->
+
+## Common workflows
+
+One `Playbook` client is bound to one `playbookId`. Supply your deployment's
+`serverURL` and a bearer `apiKey`; there is no default deployment URL. The examples
+use fictional customer-support content. Replace the example IDs with service IDs.
+Creating or appending content produces an immutable version. Publishing chooses
+which version search and discovery can return; management reads can also retrieve
+drafts and exact historical versions.
+
+### Create, version, publish, and read an FAQ
+
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+
+const playbook = new Playbook({
+  serverURL: "https://api.example.com",
+  playbookId: "pb_0123456789abcdef0123456789abcdef",
+  apiKey: "<PLAYBOOK_API_KEY>",
+});
+const content = {
+  intents: ["Where is my refund?"],
+  attributes: { audience: "support", locale: "en-US" },
+  payload: { faq: { question: "When will my refund arrive?", answer: "Check its settlement date." } },
+};
+const created = await playbook.createFaq({ entryKey: "refund-status-check", content });
+const faqId = created.entry.entryId;
+const appended = await playbook.appendFaqVersion(faqId, {
+  content: { ...content, payload: { faq: { ...content.payload.faq, answer: "Card refunds normally post 5 to 10 business days after warehouse receipt." } } },
+});
+await playbook.publishFaq(faqId, { version: appended.version.version });
+const entry = await playbook.getFaq(faqId);
+const exact = await playbook.getFaqVersion(faqId, appended.version.version);
+const entries = await playbook.listFaqs();
+const versions = await playbook.listFaqVersions(faqId);
+if (!("faq" in exact.content.payload)) throw new Error("Expected an FAQ payload");
+console.log(entry, exact.content.payload.faq.answer, entries.faqs, versions.versions);
+```
+
+Continue list requests using `nextCursor` as the next request's `cursor` until it
+is absent. Lists are not snapshots; concurrent writes can move entries between pages.
+
+### Create and version a Skill
+
+An Agent Skills package is a ZIP rooted at its Skill name and containing
+`SKILL.md`, for example `late-delivery-resolution/SKILL.md`. Base64-encode the
+complete ZIP, not each file separately.
+
+```typescript
+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>" });
+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") });
+const skillId = created.entry.entryId;
+const appended = await playbook.appendSkillVersion(skillId, { content,
+  packageBase64: (await readFile("late-delivery-resolution-v2.zip")).toString("base64") });
+await playbook.publishSkill(skillId, { version: appended.version.version });
+console.log(await playbook.getSkill(skillId));
+console.log(await playbook.getSkillVersion(skillId, appended.version.version));
+console.log(await playbook.listSkills(), await playbook.listSkillVersions(skillId));
+```
+
+### Search and discovery
+
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+
+const playbook = new Playbook({ serverURL: "https://api.example.com",
+  playbookId: "pb_0123456789abcdef0123456789abcdef", apiKey: "<PLAYBOOK_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 }));
+const discovered = await playbook.discoverEntries({ query: "My delivery is late", filter, limit: 10,
+  pinnedEntries: [{ entryKey: "late-delivery-resolution" }] });
+console.log(discovered);
+```
+
+Null-valued equality filters return a validation error from the service.
+
+Search returns published content only. Discovery returns pins separately from
+semantic matches, and Skill previews contain exact-version `SKILL.md` URIs. Check
+`truncated` and `budgetTruncated` before assuming all matching content was returned.
+
+### Review proposals and attach evidence
+
+New proposals have zero attached evidence, including when creation `source` is supplied.
+Creation source is immutable and separate from evidence. Submit further evidence separately, and persist the
+`evidenceId` together with its complete payload before sending it. An exact replay
+returns `alreadyPresent`; reusing the ID with changed content returns
+`/errors/proposal-evidence-conflict`. Evidence is caller-supplied review context,
+not verified attribution, and is not copied to the accepted FAQ. Details expose
+`evidence` and `evidenceCount`; list/search previews expose `evidenceCount`.
+
+```typescript
+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>" });
+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." } } } } } };
+const created = await playbook.createProposal({ action,
+  source: { type: "document", reference: { documentId: "refund-policy-v5" } } });
+const proposalId = created.proposalId;
+const evidenceId = "evd_" + randomUUID().replaceAll("-", "");
+const evidence = { observedAt: new Date(), producer: { name: "support-review", promptVersion: "support-review-v1" },
+  source: { type: "document", reference: { documentId: "refund-policy-v5" },
+    content: { excerpt: "The issuing bank controls final refund posting time." } } };
+// Persist evidenceId and evidence; reuse both unchanged for every retry.
+await playbook.submitProposalEvidence(proposalId, evidenceId, evidence);
+console.log(await playbook.listProposals("inbox", "evidenceCount"));
+console.log(await playbook.searchProposals({ query: "refund", actionType: "add", entryType: "faq" }));
+const reviewed = await playbook.getProposal(proposalId);
+const replaced = await playbook.replaceProposal(proposalId, { action, expectedProposalRevision: reviewed.proposalRevision });
+await playbook.dismissProposal(proposalId, { expectedProposalRevision: replaced.proposalRevision });
+const restored = await playbook.restoreProposal(proposalId);
+const accepted = await playbook.acceptProposal(proposalId, { expectedProposalRevision: restored.proposalRevision });
+if (!("versionCreated" in accepted.result)) throw new Error("Review the unrecognized acceptance result before publishing");
+const receipt = accepted.result.versionCreated;
+await playbook.publishFaq(receipt.entryId, { version: receipt.version });
+// Permanent deletion of the proposal record; the accepted FAQ is retained.
+await playbook.purgeProposal(proposalId);
+```
+
+Replacement and acceptance use optimistic concurrency. On a revision conflict,
+fetch and review the proposal again. Acceptance records one canonical target;
+concurrent calls and retries with bounded backoff resume or return that unpublished
+FAQ. The `result.versionCreated` receipt records historical completion, independent
+of current target existence or publication. Publish its returned version separately
+when it is ready to serve.
+
+Evidence IDs use `evd_` plus 32 lowercase hexadecimal characters. Each proposal
+retains at most 100 records, subject to byte limits; capacity failures use
+`/errors/proposal-evidence-capacity`. `source.reference` and `source.content`, when
+supplied, must be JSON objects; their fields are opaque to Playbook. JavaScript
+`Date` has millisecond precision; preserve the submitted timestamp and avoid
+round-tripping another client's microsecond timestamp through `Date` for replay.
+Integers above `Number.MAX_SAFE_INTEGER` cannot be represented exactly as JavaScript
+numbers; encode exact large identifiers as strings in opaque evidence documents.
+
+### Read and verify exact Skill resources
+
+`getSkillResource` returns `{ headers, result }`. The result is a
+`ReadableStream<Uint8Array>`; consume it only when ready. Header values are lists,
+and names must be read case-insensitively. Every successful read includes
+`Content-Digest` in RFC 9530 `sha-256=:<base64>:` form. The Skill descriptor uses
+`sha256:<lowercase-hex>`; compare each to the digest of the bytes, not to each other.
+
+```typescript
+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>" });
+const skillId = "ent_0123456789abcdef0123456789abcdef";
+const version = await playbook.getSkillVersion(skillId, 1);
+if (!("skill" in version.content.payload)) throw new Error("Expected a Skill payload");
+const descriptor = version.content.payload.skill.resources[0];
+if (!descriptor) throw new Error("No resources in this Skill version");
+const response = await playbook.getSkillResource(skillId, 1, descriptor.resourceId);
+const bytes = new Uint8Array(await new Response(response.result).arrayBuffer());
+const digest = createHash("sha256").update(bytes).digest();
+const header = Object.entries(response.headers).find(([key]) => key.toLowerCase() === "content-digest")?.[1][0];
+if (descriptor.digest !== "sha256:" + digest.toString("hex") || header !== "sha-256=:" + digest.toString("base64") + ":") {
+  throw new Error("Resource digest mismatch or missing Content-Digest");
+}
+```
+
+<!-- Start Authentication [security] -->
+## Authentication
+
+### Per-Client Security Schemes
+
+This SDK supports the following security scheme globally:
+
+| Name     | Type | Scheme      | Environment Variable |
+| -------- | ---- | ----------- | -------------------- |
+| `apiKey` | http | HTTP Bearer | `PLAYBOOK_API_KEY`   |
+
+To authenticate with the API the `apiKey` parameter must be set when initializing the SDK client instance. For example:
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+
+const playbook = new Playbook({
+  serverURL: "https://api.example.com",
+  apiKey: "<PLAYBOOK_API_KEY>",
+  playbookId: "<id>",
+});
+
+async function run() {
+  const result = await playbook.discoverEntries({
+    query: "A customer's order is late and they want a refund",
+    filter: {
+      eq: {
+        name: "audience",
+        value: "support",
+      },
+    },
+    limit: 10,
+    pinnedEntries: [
+      {
+        entryKey: "late-delivery-resolution",
+      },
+    ],
+  });
+
+  console.log(result);
+}
+
+run();
+
+```
+<!-- End Authentication [security] -->
+
+<!-- Start Available Resources and Operations [operations] -->
+## Available Resources and Operations
+
+<details open>
+<summary>Available methods</summary>
+
+### Playbook SDK
+
+* discoverEntries
+* lookupEntries - Resolves bounded entry references to compact management state. Results preserve input order and report misses explicitly. Each item is authoritative when read, but the batch is not a global snapshot.
+* deleteFaqs - Deletes the requested FAQ families sequentially. Each family deletion is atomic, but the batch is not: deletions completed before an error remain applied. Retrying the same request is safe because already absent entries are ignored.
+* listFaqs
+* createFaq
+* searchFaqs
+* deleteFaq
+* getFaq
+* withdrawFaq - Withdraws the FAQ publication without changing version content. An already-unpublished entry is a no-op. Concurrent publication changes are last-write-wins in Playbook v1.
+* publishFaq - Publishes the selected immutable FAQ version. Repeating the currently published version is a no-op. Concurrent publication changes are last-write-wins in Playbook v1.
+* listFaqVersions
+* appendFaqVersion
+* getFaqVersion
+* getPlaybookHealth
+* listProposals
+* createProposal
+* searchProposals
+* purgeProposal
+* getProposal
+* replaceProposal
+* acceptProposal - Promotes the reviewed revision to one canonical unpublished FAQ.
+Concurrent calls and retries resume or return the proposal's recorded target.
+A complete target may be visible to management before the proposal reaches
+promoted, but remains absent from serving until separately published.
+* restoreProposal
+* dismissProposal
+* submitProposalEvidence
+* deleteSkills - Deletes the requested Skill families sequentially. Each family deletion is atomic, but the batch is not: deletions completed before an error remain applied. Retrying the same request is safe because already absent entries are ignored.
+* listSkills
+* createSkill
+* searchSkills
+* deleteSkill
+* getSkill
+* withdrawSkill - Withdraws the Skill publication without changing version content. An already-unpublished entry is a no-op. Concurrent publication changes are last-write-wins in Playbook v1.
+* publishSkill - Publishes the selected immutable Skill version. Repeating the currently published version is a no-op. Concurrent publication changes are last-write-wins in Playbook v1.
+* listSkillVersions
+* appendSkillVersion
+* getSkillVersion
+* getSkillResource - Returns the exact immutable Skill resource bytes as a streamed response.
+
+Every successful resource read includes a required `Content-Digest` response
+header. Header names are case-insensitive. The header uses the RFC 9530
+`sha-256=:<base64>:` representation, while the resource descriptor in the
+Skill version uses `sha256:<lowercase-hex>`. Both encode the same SHA-256
+digest bytes and must not be compared as strings.
+
+
+</details>
+<!-- End Available Resources and Operations [operations] -->
+
+<!-- Start Standalone functions [standalone-funcs] -->
+## Standalone functions
+
+All the methods listed above are available as standalone functions. These
+functions are ideal for use in applications running in the browser, serverless
+runtimes or other environments where application bundle size is a primary
+concern. When using a bundler to build your application, all unused
+functionality will be either excluded from the final bundle or tree-shaken away.
+
+To read more about standalone functions, check FUNCTIONS.md.
+
+<details>
+
+<summary>Available standalone functions</summary>
+
+- `acceptProposal` - Promotes the reviewed revision to one canonical unpublished FAQ.
+Concurrent calls and retries resume or return the proposal's recorded target.
+A complete target may be visible to management before the proposal reaches
+promoted, but remains absent from serving until separately published.
+- `appendFaqVersion`
+- `appendSkillVersion`
+- `createFaq`
+- `createProposal`
+- `createSkill`
+- `deleteFaq`
+- `deleteFaqs` - Deletes the requested FAQ families sequentially. Each family deletion is atomic, but the batch is not: deletions completed before an error remain applied. Retrying the same request is safe because already absent entries are ignored.
+- `deleteSkill`
+- `deleteSkills` - Deletes the requested Skill families sequentially. Each family deletion is atomic, but the batch is not: deletions completed before an error remain applied. Retrying the same request is safe because already absent entries are ignored.
+- `discoverEntries`
+- `dismissProposal`
+- `getFaq`
+- `getFaqVersion`
+- `getPlaybookHealth`
+- `getProposal`
+- `getSkill`
+- `getSkillResource` - Returns the exact immutable Skill resource bytes as a streamed response.
+
+Every successful resource read includes a required `Content-Digest` response
+header. Header names are case-insensitive. The header uses the RFC 9530
+`sha-256=:<base64>:` representation, while the resource descriptor in the
+Skill version uses `sha256:<lowercase-hex>`. Both encode the same SHA-256
+digest bytes and must not be compared as strings.
+
+- `getSkillVersion`
+- `listFaqs`
+- `listFaqVersions`
+- `listProposals`
+- `listSkills`
+- `listSkillVersions`
+- `lookupEntries` - Resolves bounded entry references to compact management state. Results preserve input order and report misses explicitly. Each item is authoritative when read, but the batch is not a global snapshot.
+- `publishFaq` - Publishes the selected immutable FAQ version. Repeating the currently published version is a no-op. Concurrent publication changes are last-write-wins in Playbook v1.
+- `publishSkill` - Publishes the selected immutable Skill version. Repeating the currently published version is a no-op. Concurrent publication changes are last-write-wins in Playbook v1.
+- `purgeProposal`
+- `replaceProposal`
+- `restoreProposal`
+- `searchFaqs`
+- `searchProposals`
+- `searchSkills`
+- `submitProposalEvidence`
+- `withdrawFaq` - Withdraws the FAQ publication without changing version content. An already-unpublished entry is a no-op. Concurrent publication changes are last-write-wins in Playbook v1.
+- `withdrawSkill` - Withdraws the Skill publication without changing version content. An already-unpublished entry is a no-op. Concurrent publication changes are last-write-wins in Playbook v1.
+
+</details>
+<!-- End Standalone functions [standalone-funcs] -->
+
+## 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.
+Methods do not expose a per-operation `playbookId` override; create another client
+to use a different Playbook. Supply `serverURL` explicitly for each client.
+
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+
+const playbook = new Playbook({
+  serverURL: "https://api.example.com",
+  playbookId: "pb_0123456789abcdef0123456789abcdef",
+  apiKey: "<PLAYBOOK_API_KEY>",
+});
+const result = await playbook.getPlaybookHealth();
+console.log(result);
+```
+<!-- No Global Parameters [global-parameters] -->
+
+## Retries
+
+The client makes one attempt by default (`strategy: "none"`). Configure retries
+with `retryConfig` on the client or `retries` in an operation's `RequestOptions`.
+An operation's setting takes precedence. Backoff intervals are in milliseconds;
+see RetryConfig for the full options.
+
+Use retries only when repeating the operation is safe for your workflow. For
+proposal evidence, persist the same evidence ID and payload across attempts;
+the service treats an exact replay as `alreadyPresent`.
+
+<!-- No Retries [retries] -->
+
+<!-- Start Error Handling [errors] -->
+## Error Handling
+
+`PlaybookError` is the base class for all HTTP error responses. It has the following properties:
+
+| Property            | Type       | Description                                                                             |
+| ------------------- | ---------- | --------------------------------------------------------------------------------------- |
+| `error.message`     | `string`   | Error message                                                                           |
+| `error.statusCode`  | `number`   | HTTP response status code eg `404`                                                      |
+| `error.headers`     | `Headers`  | HTTP response headers                                                                   |
+| `error.body`        | `string`   | HTTP body. Can be empty string if no body is returned.                                  |
+| `error.rawResponse` | `Response` | Raw HTTP response                                                                       |
+| `error.data$`       |            | Optional. Some errors may contain structured data. [See Error Classes](#error-classes). |
+
+### Example
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+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>",
+});
+
+async function run() {
+  try {
+    const result = await playbook.discoverEntries({
+      query: "A customer's order is late and they want a refund",
+      filter: {
+        eq: {
+          name: "audience",
+          value: "support",
+        },
+      },
+      limit: 10,
+      pinnedEntries: [
+        {
+          entryKey: "late-delivery-resolution",
+        },
+      ],
+    });
+
+    console.log(result);
+  } catch (error) {
+    // The base class for HTTP error responses
+    if (error instanceof errors.PlaybookError) {
+      console.log(error.message);
+      console.log(error.statusCode);
+      console.log(error.body);
+      console.log(error.headers);
+
+      // Depending on the method different errors may be thrown
+      if (error instanceof errors.RequestValidationErrorResponseContent) {
+        console.log(error.data$.title); // string
+        console.log(error.data$.status); // number
+        console.log(error.data$.detail); // string
+        console.log(error.data$.instance); // string
+        console.log(error.data$.type); // models.RequestValidationErrorType
+      }
+    }
+  }
+}
+
+run();
+
+```
+
+### Error Classes
+**Primary errors:**
+* `PlaybookError`: The base class for HTTP error responses.
+  * `RequestValidationErrorResponseContent`: One HTTP 400 schema preserves every validation problem type in generated clients. Status code `400`.
+  * `AuthenticationErrorResponseContent`: Authentication credentials are missing, malformed, or invalid. Status code `401`.
+  * `ForbiddenErrorResponseContent`: The caller is authenticated but not allowed to access the requested resource. Status code `403`.
+  * `NotFoundErrorResponseContent`: The requested resource does not exist. Status code `404`.
+  * `TimeoutErrorResponseContent`: The request timed out before the service could complete it. Status code `408`.
+  * `PlaybookConflictErrorResponseContent`: One schema per HTTP status preserves the complete problem catalog in generated clients, following the Iris/Agent Memory dedicated error-type enum pattern. Status code `409`.
+  * `PayloadTooLargeErrorResponseContent`: The request payload exceeds the maximum supported size. Status code `413`.
+  * `ResourceSuspendedErrorResponseContent`: The requested resource exists but is suspended by an administrator. Status code `423`.
+  * `FailedDependencyErrorResponseContent`: A dependent resource required to process the request is unavailable or unhealthy. Status code `424`.
+  * `TooManyRequestsErrorResponseContent`: The service rejected the request because rate limits were exceeded. Status code `429`.
+  * `PlaybookInternalErrorResponseContent`: Stored integrity failures require operator investigation; editing or blindly retrying the request does not repair the stored record. Status code `500`.
+  * `PlaybookServiceUnavailableErrorResponseContent`: Retry reads and proposal acceptance with bounded backoff. Acceptance resumes its recorded canonical target. An uncertain create or append response may have written another logical record or version and should not be blindly retried when the caller requires exactly one result. Status code `503`.
+
+<details><summary>Less common errors (6)</summary>
+
+<br />
+
+**Network errors:**
+* `ConnectionError`: HTTP client was unable to make a request to a server.
+* `RequestTimeoutError`: HTTP request timed out due to an AbortSignal signal.
+* `RequestAbortedError`: HTTP request was aborted by the client.
+* `InvalidRequestError`: Any input used to create a request is invalid.
+* `UnexpectedClientError`: Unrecognised or unexpected error.
+
+
+**Inherit from `PlaybookError`**:
+* `ResponseValidationError`: Type mismatch between the data returned from the server and the structure expected by the SDK. See `error.rawValue` for the raw value and `error.pretty()` for a nicely formatted multi-line string.
+
+</details>
+<!-- End Error Handling [errors] -->
+
+## Custom HTTP Client
+
+The TypeScript SDK makes API calls using an `HTTPClient` that wraps the native
+[Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). This
+client is a thin wrapper around `fetch` and provides the ability to attach hooks
+around the request lifecycle that can be used to modify the request or handle
+errors and response.
+
+The `HTTPClient` constructor takes an optional `fetcher` argument that can be
+used to integrate a third-party HTTP client or when writing tests to mock out
+the HTTP client and feed in fixtures.
+
+The following example shows how to:
+- route requests through a proxy server using [undici](https://www.npmjs.com/package/undici)'s ProxyAgent
+- use the `"beforeRequest"` hook to add a custom header and a timeout to requests
+- use the `"requestError"` hook to log errors
+
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+import { ProxyAgent } from "undici";
+import { HTTPClient } from "@redis-iris/agent-playbook/lib/http";
+
+const dispatcher = new ProxyAgent("http://proxy.example.com:8080");
+
+const httpClient = new HTTPClient({
+  // 'fetcher' takes a function that has the same signature as native 'fetch'.
+  fetcher: (input, init) =>
+    // 'dispatcher' is specific to undici and not part of the standard Fetch API.
+    fetch(input, { ...init, dispatcher } as RequestInit),
+});
+
+httpClient.addHook("beforeRequest", (request) => {
+  const nextRequest = new Request(request, {
+    signal: request.signal || AbortSignal.timeout(5000)
+  });
+
+  nextRequest.headers.set("x-custom-header", "custom value");
+
+  return nextRequest;
+});
+
+httpClient.addHook("requestError", (error, request) => {
+  console.group("Request Error");
+  console.log("Reason:", `${error}`);
+  console.log("Endpoint:", `${request.method} ${request.url}`);
+  console.groupEnd();
+});
+
+const sdk = new Playbook({ serverURL: "https://api.example.com",
+  playbookId: "pb_0123456789abcdef0123456789abcdef", httpClient });
+```
+<!-- No Custom HTTP Client [http-client] -->
+
+## Debugging
+
+You can setup your SDK to emit debug logs for SDK requests and responses.
+
+You can pass a logger that matches `console`'s interface as an SDK option.
+
+> [!WARNING]
+> Beware that debug logging will reveal secrets, like API tokens in headers, in log messages printed to a console or files. It's recommended to use this feature only during local development and not in production.
+
+```typescript
+import { Playbook } from "@redis-iris/agent-playbook";
+
+const sdk = 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.
+<!-- No Debugging [debug] -->
+
+<!-- Placeholder for Future Speakeasy SDK Sections -->
+
+# Development
+
+## Maturity
+
+This SDK is an alpha prerelease. Pin an exact published version and upgrade intentionally.
+
+## Contributions
+
+While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation.
+We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.
+
+### SDK Created by [Speakeasy](https://www.speakeasy.com/?utm_source=@redis-iris/agent-playbook&utm_campaign=typescript)