@sapiom/tools 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @sapiom/tools
 
+## 0.6.1
+
+### Patch Changes
+
+- 3d45ec6: Document the `orchestrations` capability: add it to the README's Capabilities table + intro, and add a per-capability `src/orchestrations/README.md` (run a deployed orchestration, or dispatch one from a step and pause on its result).
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 # @sapiom/tools
 
-A typed TypeScript client for Sapiom capabilities — sandboxes, git repositories, coding agents, file storage, and content generation — authenticated to your tenant.
+A typed TypeScript client for Sapiom capabilities — sandboxes, git repositories, coding agents, file storage, content generation, and orchestrations — authenticated to your tenant.
 
 These are the same capabilities your Sapiom agents call as tools; this package makes them callable directly from your own code.
 
@@ -72,6 +72,7 @@ Each capability is a namespace, importable from the barrel or its own subpath (e
 | `agent` | Coding agents (LLM execution) | [src/agent](./src/agent/README.md) |
 | `fileStorage` | Tenant-scoped object storage (presigned URLs) | [src/file-storage](./src/file-storage/README.md) |
 | `contentGeneration` | Media generation (images; video/audio soon), with optional `storage` | [src/content-generation](./src/content-generation/README.md) |
+| `orchestrations` | Run a deployed orchestration, or dispatch one from a step and await its result | [src/orchestrations](./src/orchestrations/README.md) |
 
 ## Composing capabilities
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sapiom/tools",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Typed client for Sapiom capabilities (sandboxes, repositories, agent, file storage, …) — the same tools your agents call over MCP, callable from your code, auth'd to your tenant.",
   "license": "MIT",
   "author": "Sapiom",

package/src/orchestrations/README.md

@@ -0,0 +1,50 @@
+# orchestrations
+
+Run a deployed orchestration and await its result — or, from inside a step, dispatch one and pause until it finishes. An orchestration is addressed by its **slug** (its stable handle).
+
+```ts
+import { orchestrations } from "@sapiom/tools";
+
+// Standalone: run a deployed orchestration and wait for its result.
+const result = await orchestrations.run({ definition: "enrich-lead", input: { id } });
+if (result.status === "completed") {
+  // result.output
+}
+```
+
+From inside a step, dispatch another orchestration and suspend until it finishes — the step you name in `resumeStep` receives the typed result as its input:
+
+```ts
+import { orchestrations } from "@sapiom/tools";
+import { defineStep, pauseUntilSignal } from "@sapiom/orchestration";
+
+const enrich = defineStep({
+  name: "enrich",
+  pause: { signal: orchestrations.ORCHESTRATIONS_RESULT_SIGNAL, resumeStep: "use-result" },
+  async run(input, ctx) {
+    const child = await orchestrations.launch({ definition: "enrich-lead", input });
+    return pauseUntilSignal(child, { resumeStep: "use-result" });
+  },
+});
+
+const useResult = defineStep({
+  name: "use-result",
+  terminal: true,
+  async run(result: orchestrations.OrchestrationRunResultPayload, ctx) {
+    if (result.status === "failed") {
+      // result.error — failure is data you branch on, not a thrown exception
+    }
+    // result.output (when completed)
+  },
+});
+```
+
+## Things to know
+
+- **`run` blocks; `launch` returns a pausable handle.** `run` polls until the run reaches a terminal state and returns its result — use it for standalone, inline calls. `launch` returns immediately with a handle you hand to `pauseUntilSignal(handle, { resumeStep })` to suspend the step until the run finishes. Don't use `run` to pause a step — it returns a result, not a handle.
+
+- **Failure is data, not an exception.** The result is discriminated on `status` (`"completed" | "failed"`). A failed run resumes your step with `status: "failed"` and an `error` to branch on — it does not throw. Validate an incoming payload with `orchestrations.orchestrationResultSchema.parse(value)` if you want a runtime check.
+
+- **Addressed by slug.** `definition` is the deployed orchestration's slug — its stable handle. `input` is passed to its entry step.
+
+- **`idempotencyKey` deduplicates.** Repeating a launch with the same key returns the existing run instead of starting a new one.