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

package/FUNCTIONS.md

@@ -0,0 +1,103 @@
+# 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
+will be tree-shaken away. This includes code for unused methods, Zod schemas,
+encoding helpers and response handlers. The result is dramatically smaller
+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
+specific category of applications.
+
+## Example
+
+```typescript
+import { PlaybookCore } from "@redis-iris/agent-playbook/core.js";
+import { discoverEntries } from "@redis-iris/agent-playbook/funcs/discover-entries.js";
+
+// Use `PlaybookCore` for best tree-shaking performance.
+// You can create one instance of it to use across an application.
+const playbook = new PlaybookCore({
+  serverURL: "https://api.example.com",
+  playbookId: "<id>",
+  apiKey: "<PLAYBOOK_API_KEY>",
+});
+
+async function run() {
+  const res = await discoverEntries(playbook, {
+    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",
+      },
+    ],
+  });
+  if (res.ok) {
+    const { value: result } = res;
+    console.log(result);
+  } else {
+    console.log("discoverEntries failed:", res.error);
+  }
+}
+
+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();
+
+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();
+```
+
+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).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Redis, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.