@sapiom/tools 0.4.0 → 0.6.0

package/dist/esm/content-generation/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `contentGeneration` capability — generate media (images today; video and audio
+ * to come), with an optional `storage` param that persists each output to Sapiom
+ * file storage so you get a durable `fileId` back inline.
+ *
+ *   import { contentGeneration } from "@sapiom/tools";        // ambient auth
+ *   const out = await contentGeneration.images.create({
+ *     prompt: "a red bicycle",
+ *     storage: { visibility: "private" },                     // optional — persist outputs
+ *   });
+ *   out.images[0].url;       // hosted URL of the generated image
+ *   out.images[0].fileId;    // present when `storage` was passed → use with fileStorage
+ *
+ * Or via an explicit client: `createClient({ apiKey }).contentGeneration.images.create(...)`.
+ */
+import { Transport } from "../_client/index.js";
+import { ContentGenerationHttpError } from "./errors.js";
+export { ContentGenerationHttpError };
+export interface StorageOptions {
+    /**
+     * Visibility of the persisted output.
+     * - "private" — download requires the owning tenant (default).
+     * - "public"  — download URL is reachable by any tenant.
+     */
+    visibility?: "private" | "public";
+}
+export interface ImageCreateInput {
+    /** Text prompt describing the image to generate. */
+    prompt: string;
+    /** Number of images to generate. */
+    numImages?: number;
+    /**
+     * Optional model selector. Defaults to a fast image model; most callers omit it.
+     * (Model identifiers are an advanced, evolving surface.)
+     */
+    model?: string;
+    /**
+     * Optional: persist each generated output to Sapiom file storage. When set, every
+     * item in `images` comes back annotated with `fileId` (or `storageError` if
+     * persisting that one failed).
+     */
+    storage?: StorageOptions;
+    /**
+     * Advanced: extra model-specific parameters, forwarded verbatim
+     * (e.g. `image_size`, `seed`, `guidance_scale`).
+     */
+    params?: Record<string, unknown>;
+}
+export interface GeneratedImage {
+    /** Hosted URL of the generated image. */
+    url: string;
+    /** MIME type, when reported. */
+    contentType?: string;
+    width?: number;
+    height?: number;
+    /**
+     * Present when `storage` was requested and this output was persisted — pass to
+     * `fileStorage.getDownloadUrl(fileId)` to retrieve it.
+     */
+    fileId?: string;
+    /**
+     * Present when `storage` was requested but persisting THIS output failed
+     * (best-effort: other images in the same response may still carry `fileId`).
+     */
+    storageError?: string;
+}
+export interface ImageGenerationResult {
+    /** Generated images. */
+    images?: GeneratedImage[];
+    /** Additional model-specific fields (e.g. `seed`, `timings`), returned as-is. */
+    [key: string]: unknown;
+}
+/**
+ * Generate one or more images from a prompt. Pass `storage` to persist each output
+ * (the returned images then carry `fileId`). Failed requests throw
+ * {@link ContentGenerationHttpError}.
+ */
+export declare function createImage(input: ImageCreateInput, transport?: Transport, baseUrl?: string): Promise<ImageGenerationResult>;
+/**
+ * The `images` sub-namespace, so `contentGeneration.images.create(...)` reads the
+ * same whether imported from the barrel or used on a client. Video and audio will
+ * land here as sibling sub-namespaces.
+ */
+export declare const images: {
+    create: typeof createImage;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/content-generation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/content-generation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,SAAS,EAAoB,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAY,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAUtC,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,wBAAwB;IACxB,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;IAC1B,iFAAiF;IACjF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AA2CD;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,gBAAgB,EACvB,SAAS,GAAE,SAA8B,EACzC,OAAO,SAAmB,GACzB,OAAO,CAAC,qBAAqB,CAAC,CAqBhC;AAED;;;;GAIG;AACH,eAAO,MAAM,MAAM;;CAA0B,CAAC"}

package/dist/esm/content-generation/index.js

@@ -0,0 +1,73 @@
+/**
+ * `contentGeneration` capability — generate media (images today; video and audio
+ * to come), with an optional `storage` param that persists each output to Sapiom
+ * file storage so you get a durable `fileId` back inline.
+ *
+ *   import { contentGeneration } from "@sapiom/tools";        // ambient auth
+ *   const out = await contentGeneration.images.create({
+ *     prompt: "a red bicycle",
+ *     storage: { visibility: "private" },                     // optional — persist outputs
+ *   });
+ *   out.images[0].url;       // hosted URL of the generated image
+ *   out.images[0].fileId;    // present when `storage` was passed → use with fileStorage
+ *
+ * Or via an explicit client: `createClient({ apiKey }).contentGeneration.images.create(...)`.
+ */
+import { defaultTransport } from "../_client/index.js";
+import { ensureOk, ContentGenerationHttpError } from "./errors.js";
+export { ContentGenerationHttpError };
+const DEFAULT_BASE_URL = process.env.SAPIOM_CONTENT_GENERATION_URL || "https://fal.services.sapiom.ai";
+/** Default image model when the caller doesn't pick one — a fast, low-cost model. */
+const DEFAULT_IMAGE_MODEL = "fal-ai/flux/schnell";
+function mapImage(raw) {
+    return {
+        url: raw.url,
+        ...(raw.content_type !== undefined && { contentType: raw.content_type }),
+        ...(raw.width !== undefined && { width: raw.width }),
+        ...(raw.height !== undefined && { height: raw.height }),
+        ...(raw.file_id !== undefined && { fileId: raw.file_id }),
+        ...(raw.storage_error !== undefined && { storageError: raw.storage_error }),
+    };
+}
+function mapResult(raw) {
+    const { images, ...rest } = raw;
+    return images === undefined
+        ? { ...rest }
+        : { ...rest, images: images.map(mapImage) };
+}
+// ----- Capability operations -----
+/** Encode a model id into a URL path, preserving its `/` separators. */
+function modelToPath(model) {
+    return model.split("/").filter(Boolean).map(encodeURIComponent).join("/");
+}
+/**
+ * Generate one or more images from a prompt. Pass `storage` to persist each output
+ * (the returned images then carry `fileId`). Failed requests throw
+ * {@link ContentGenerationHttpError}.
+ */
+export async function createImage(input, transport = defaultTransport(), baseUrl = DEFAULT_BASE_URL) {
+    const path = modelToPath(input.model || DEFAULT_IMAGE_MODEL);
+    const body = {
+        prompt: input.prompt,
+        ...input.params,
+    };
+    if (input.numImages !== undefined)
+        body.num_images = input.numImages;
+    // Truthy check (not `!== undefined`) so a caller passing `storage: null` is
+    // treated as "no storage" rather than sending a null field.
+    if (input.storage)
+        body.storage = input.storage;
+    const res = await ensureOk(await transport.fetch(`${baseUrl}/run/${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    }), "Failed to generate image");
+    return mapResult((await res.json()));
+}
+/**
+ * The `images` sub-namespace, so `contentGeneration.images.create(...)` reads the
+ * same whether imported from the barrel or used on a client. Video and audio will
+ * land here as sibling sub-namespaces.
+ */
+export const images = { create: createImage };
+//# sourceMappingURL=index.js.map

package/dist/esm/content-generation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/content-generation/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/file-storage/errors.d.ts

@@ -1,6 +1,6 @@
 /**
- * Error thrown by the file-storage capability when the gateway returns a non-2xx
- * response. Exposes `status` (HTTP status code) and `body` (parsed JSON body, or
+ * Error thrown by the file-storage capability when a request fails (non-2xx
+ * response). Exposes `status` (HTTP status code) and `body` (parsed JSON body, or
  * raw text when the body isn't JSON) for programmatic inspection.
  */
 export declare class FileStorageHttpError extends Error {

package/dist/esm/file-storage/errors.js

@@ -1,6 +1,6 @@
 /**
- * Error thrown by the file-storage capability when the gateway returns a non-2xx
- * response. Exposes `status` (HTTP status code) and `body` (parsed JSON body, or
+ * Error thrown by the file-storage capability when a request fails (non-2xx
+ * response). Exposes `status` (HTTP status code) and `body` (parsed JSON body, or
  * raw text when the body isn't JSON) for programmatic inspection.
  */
 export class FileStorageHttpError extends Error {

package/dist/esm/file-storage/index.d.ts

@@ -1,8 +1,8 @@
 /**
- * `fileStorage` capability — tenant-scoped object storage on presigned GCS URLs.
+ * `fileStorage` capability — tenant-scoped object storage with presigned URLs.
  *
- * The control plane only: `upload` hands back a presigned URL you PUT the bytes to
- * yourself (so you own streaming / progress / resumable uploads), and
+ * You transfer the bytes yourself: `upload` hands back a presigned URL you PUT the
+ * bytes to (so you own streaming / progress / resumable uploads), and
  * `getDownloadUrl` hands back a presigned URL you GET. `list`, `setVisibility`, and
  * `delete` round out the lifecycle.
  *
@@ -15,9 +15,8 @@
  *
  * Or via an explicit client: `createClient({ apiKey }).fileStorage.upload(...)`.
  *
- * Wire fields are snake_case; this module maps them to the camelCase SDK surface.
- * Byte counts are int64 — the gateway serializes them as strings (precision-safe),
- * so `expectedFileSize` / `actualFileSize` on returned metadata are `string | null`.
+ * Byte-size fields (`expectedFileSize` / `actualFileSize` on returned metadata) are
+ * returned as `string | null` to stay precise for large files.
  */
 import { Transport } from "../_client/index.js";
 import { FileStorageHttpError } from "./errors.js";
@@ -33,13 +32,13 @@ export interface UploadInput {
      * - "public"  — download URL is unauthenticated.
      */
     visibility?: "private" | "public";
-    /** Expected file size in bytes. Used to pre-allocate storage. */
+    /** Expected file size in bytes. */
     expectedFileSize?: number;
 }
 export interface UploadResponse {
     /** Unique file identifier. Use this in subsequent calls. */
     fileId: string;
-    /** GCS presigned upload URL. PUT the file bytes here directly. Expires at `expiresAt`. */
+    /** Presigned upload URL. PUT the file bytes here directly. Expires at `expiresAt`. */
     uploadUrl: string;
     /** ISO-8601 timestamp when the upload URL expires. */
     expiresAt: string;
@@ -47,7 +46,7 @@ export interface UploadResponse {
     requiredHeaders: Record<string, string>;
 }
 export interface DownloadUrlResponse {
-    /** Presigned GCS download URL. Expires at `expiresAt`. */
+    /** Presigned download URL. Expires at `expiresAt`. */
     downloadUrl: string;
     /** ISO-8601 timestamp when the download URL expires. */
     expiresAt: string;
@@ -63,12 +62,9 @@ export interface FileMetadata {
     visibility: "private" | "public";
     /** Upload lifecycle status (e.g. "pending_upload", "uploaded", "deleted"). */
     status: string;
-    /**
-     * Expected (client-declared) size in bytes — a string (int64, precision-safe),
-     * `null` when not declared.
-     */
+    /** Expected (client-declared) size in bytes — a string, `null` when not declared. */
     expectedFileSize?: string | null;
-    /** Actual size in bytes after upload (string; `null` until the verify sweep records it). */
+    /** Actual size in bytes after upload (string; `null` until the upload is verified). */
     actualFileSize?: string | null;
     /** ISO-8601 timestamp when the record was created. */
     createdAt: string;
@@ -96,8 +92,8 @@ export interface ListResponse {
     hasMore: boolean;
 }
 /**
- * Initiate an upload. Returns a presigned GCS URL; PUT the bytes to `uploadUrl`
- * with `requiredHeaders` yourself (this capability owns only the control plane).
+ * Initiate an upload. Returns a presigned URL; PUT the bytes to `uploadUrl` with
+ * `requiredHeaders` yourself.
  */
 export declare function upload(input: UploadInput, transport?: Transport, baseUrl?: string): Promise<UploadResponse>;
 /** Generate a presigned download URL for a file. */
@@ -107,8 +103,8 @@ export declare function list(opts?: ListOptions, transport?: Transport, baseUrl?
 /** Update a file's visibility. */
 export declare function setVisibility(fileId: string, visibility: "private" | "public", transport?: Transport, baseUrl?: string): Promise<FileMetadata>;
 /**
- * Delete a file. Idempotent on the gateway (deleting an already-deleted file is a
- * no-op success). Exported as `delete`:
+ * Delete a file. Idempotent (deleting an already-deleted file is a no-op success).
+ * Exported as `delete`:
  * `import { fileStorage } from "@sapiom/tools"; await fileStorage.delete(id)`.
  */
 declare function deleteFile(fileId: string, transport?: Transport, baseUrl?: string): Promise<void>;

package/dist/esm/file-storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/file-storage/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/file-storage/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/file-storage/index.js

@@ -1,8 +1,8 @@
 /**
- * `fileStorage` capability — tenant-scoped object storage on presigned GCS URLs.
+ * `fileStorage` capability — tenant-scoped object storage with presigned URLs.
  *
- * The control plane only: `upload` hands back a presigned URL you PUT the bytes to
- * yourself (so you own streaming / progress / resumable uploads), and
+ * You transfer the bytes yourself: `upload` hands back a presigned URL you PUT the
+ * bytes to (so you own streaming / progress / resumable uploads), and
  * `getDownloadUrl` hands back a presigned URL you GET. `list`, `setVisibility`, and
  * `delete` round out the lifecycle.
  *
@@ -15,14 +15,12 @@
  *
  * Or via an explicit client: `createClient({ apiKey }).fileStorage.upload(...)`.
  *
- * Wire fields are snake_case; this module maps them to the camelCase SDK surface.
- * Byte counts are int64 — the gateway serializes them as strings (precision-safe),
- * so `expectedFileSize` / `actualFileSize` on returned metadata are `string | null`.
+ * Byte-size fields (`expectedFileSize` / `actualFileSize` on returned metadata) are
+ * returned as `string | null` to stay precise for large files.
  */
 import { defaultTransport } from "../_client/index.js";
 import { ensureOk, FileStorageHttpError } from "./errors.js";
 export { FileStorageHttpError };
-/** Object storage service. Host routing is an internal detail — override via SAPIOM_FILE_STORAGE_URL. */
 const DEFAULT_BASE_URL = process.env.SAPIOM_FILE_STORAGE_URL ||
     "https://file-storage.services.sapiom.ai";
 function mapFileMetadata(raw) {
@@ -46,8 +44,8 @@ function mapFileMetadata(raw) {
 }
 // ----- capability operations -----
 /**
- * Initiate an upload. Returns a presigned GCS URL; PUT the bytes to `uploadUrl`
- * with `requiredHeaders` yourself (this capability owns only the control plane).
+ * Initiate an upload. Returns a presigned URL; PUT the bytes to `uploadUrl` with
+ * `requiredHeaders` yourself.
  */
 export async function upload(input, transport = defaultTransport(), baseUrl = DEFAULT_BASE_URL) {
     const body = { content_type: input.contentType };
@@ -106,8 +104,8 @@ export async function setVisibility(fileId, visibility, transport = defaultTrans
     return mapFileMetadata(raw);
 }
 /**
- * Delete a file. Idempotent on the gateway (deleting an already-deleted file is a
- * no-op success). Exported as `delete`:
+ * Delete a file. Idempotent (deleting an already-deleted file is a no-op success).
+ * Exported as `delete`:
  * `import { fileStorage } from "@sapiom/tools"; await fileStorage.delete(id)`.
  */
 async function deleteFile(fileId, transport = defaultTransport(), baseUrl = DEFAULT_BASE_URL) {

package/dist/esm/file-storage/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/file-storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAa,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAE7D,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAEhC,yGAAyG;AACzG,MAAM,gBAAgB,GACpB,OAAO,CAAC,GAAG,CAAC,uBAAuB;IACnC,yCAAyC,CAAC;AAuH5C,SAAS,eAAe,CAAC,GAAwB;IAC/C,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,GAAG,CAAC,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC;QAC/D,WAAW,EAAE,GAAG,CAAC,YAAY;QAC7B,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,GAAG,CAAC,GAAG,CAAC,kBAAkB,KAAK,SAAS,IAAI;YAC1C,gBAAgB,EAAE,GAAG,CAAC,kBAAkB;SACzC,CAAC;QACF,GAAG,CAAC,GAAG,CAAC,gBAAgB,KAAK,SAAS,IAAI;YACxC,cAAc,EAAE,GAAG,CAAC,gBAAgB;SACrC,CAAC;QACF,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,GAAG,CAAC,GAAG,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC;QACrE,GAAG,CAAC,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC;QAClE,oBAAoB,EAAE,GAAG,CAAC,sBAAsB;KACjD,CAAC;AACJ,CAAC;AAED,oCAAoC;AAEpC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,KAAkB,EAClB,YAAuB,gBAAgB,EAAE,EACzC,OAAO,GAAG,gBAAgB;IAE1B,MAAM,IAAI,GAA4B,EAAE,YAAY,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;IAC1E,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS;QAAE,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,QAAQ,CAAC;IAClE,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;QAAE,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;IACvE,IAAI,KAAK,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACzC,IAAI,CAAC,kBAAkB,GAAG,KAAK,CAAC,gBAAgB,CAAC;IACnD,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,QAAQ,CACxB,MAAM,SAAS,CAAC,KAAK,CAAC,GAAG,OAAO,SAAS,EAAE;QACzC,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KAC3B,CAAC,EACF,gCAAgC,CACjC,CAAC;IACF,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA0B,CAAC;IACxD,OAAO;QACL,MAAM,EAAE,GAAG,CAAC,OAAO;QACnB,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,eAAe,EAAE,GAAG,CAAC,gBAAgB;KACtC,CAAC;AACJ,CAAC;AAED,oDAAoD;AACpD,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAc,EACd,YAAuB,gBAAgB,EAAE,EACzC,OAAO,GAAG,gBAAgB;IAE1B,MAAM,GAAG,GAAG,MAAM,QAAQ,CACxB,MAAM,SAAS,CAAC,KAAK,CAAC,GAAG,OAAO,aAAa,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC,EAC1E,wCAAwC,MAAM,GAAG,CAClD,CAAC;IACF,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA4B,CAAC;IAC1D,OAAO,EAAE,WAAW,EAAE,GAAG,CAAC,YAAY,EAAE,SAAS,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC;AACtE,CAAC;AAED,oDAAoD;AACpD,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,IAAkB,EAClB,YAAuB,gBAAgB,EAAE,EACzC,OAAO,GAAG,gBAAgB;IAE1B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,OAAO,QAAQ,CAAC,CAAC;IACxC,IAAI,IAAI,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9B,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,IAAI,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACtD,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,QAAQ,CACxB,MAAM,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,EACrC,sBAAsB,CACvB,CAAC;IACF,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAwB,CAAC;IACtD,OAAO;QACL,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC;QACrC,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,OAAO,EAAE,GAAG,CAAC,QAAQ;KACtB,CAAC;AACJ,CAAC;AAED,kCAAkC;AAClC,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAc,EACd,UAAgC,EAChC,YAAuB,gBAAgB,EAAE,EACzC,OAAO,GAAG,gBAAgB;IAE1B,MAAM,GAAG,GAAG,MAAM,QAAQ,CACxB,MAAM,SAAS,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,kBAAkB,CAAC,MAAM,CAAC,EAAE,EAAE;QAChE,MAAM,EAAE,OAAO;QACf,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,CAAC;KACrC,CAAC,EACF,sCAAsC,MAAM,GAAG,CAChD,CAAC;IACF,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAwB,CAAC;IACtD,OAAO,eAAe,CAAC,GAAG,CAAC,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,UAAU,CACvB,MAAc,EACd,YAAuB,gBAAgB,EAAE,EACzC,OAAO,GAAG,gBAAgB;IAE1B,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,KAAK,CAC/B,GAAG,OAAO,IAAI,kBAAkB,CAAC,MAAM,CAAC,EAAE,EAC1C,EAAE,MAAM,EAAE,QAAQ,EAAE,CACrB,CAAC;IACF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;QAC9C,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;QACD,MAAM,IAAI,oBAAoB,CAC5B,0BAA0B,MAAM,MAAM,GAAG,CAAC,MAAM,IAAI,IAAI,EAAE,EAC1D,GAAG,CAAC,MAAM,EACV,MAAM,CACP,CAAC;IACJ,CAAC;IACD,qCAAqC;AACvC,CAAC;AAED,OAAO,EAAE,UAAU,IAAI,MAAM,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/file-storage/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.d.ts

@@ -23,6 +23,12 @@ export * as agent from "./agent/index.js";
 export { CODING_RESULT_SIGNAL } from "./agent/index.js";
 export type { CodingResultPayload, ExecutionEnvironmentRef, } from "./agent/index.js";
 export { codingResultSchema, CodingResultSchemaError, toResumePayload, EXECUTION_ENVIRONMENT_BLAXEL_SANDBOX, } from "./agent/index.js";
+export * as orchestrations from "./orchestrations/index.js";
+export { ORCHESTRATIONS_RESULT_SIGNAL } from "./orchestrations/index.js";
+export type { OrchestrationRunResultPayload } from "./orchestrations/index.js";
+export { orchestrationResultSchema, OrchestrationResultSchemaError } from "./orchestrations/index.js";
 export * as fileStorage from "./file-storage/index.js";
 export { FileStorageHttpError } from "./file-storage/index.js";
+export * as contentGeneration from "./content-generation/index.js";
+export { ContentGenerationHttpError } from "./content-generation/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAIvE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/C,OAAO,KAAK,YAAY,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC;AAE1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAGxD,YAAY,EACV,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,oCAAoC,GACrC,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAIvE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/C,OAAO,KAAK,YAAY,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC;AAE1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAGxD,YAAY,EACV,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,oCAAoC,GACrC,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,cAAc,MAAM,2BAA2B,CAAC;AAE5D,OAAO,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AAGzE,YAAY,EAAE,6BAA6B,EAAE,MAAM,2BAA2B,CAAC;AAE/E,OAAO,EAAE,yBAAyB,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAC;AAEtG,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,KAAK,iBAAiB,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/esm/index.js

@@ -22,6 +22,13 @@ export { CODING_RESULT_SIGNAL } from "./agent/index.js";
 // Validate / build a `CodingResultPayload`, and the env `type` whose `id` is a
 // sandbox name for `sandboxes.attach(id)`.
 export { codingResultSchema, CodingResultSchemaError, toResumePayload, EXECUTION_ENVIRONMENT_BLAXEL_SANDBOX, } from "./agent/index.js";
+export * as orchestrations from "./orchestrations/index.js";
+// Surfaced top-level for the static `pause: { signal }` decl on a workflow step.
+export { ORCHESTRATIONS_RESULT_SIGNAL } from "./orchestrations/index.js";
+// Validate an OrchestrationRunResultPayload at the resume boundary.
+export { orchestrationResultSchema, OrchestrationResultSchemaError } from "./orchestrations/index.js";
 export * as fileStorage from "./file-storage/index.js";
 export { FileStorageHttpError } from "./file-storage/index.js";
+export * as contentGeneration from "./content-generation/index.js";
+export { ContentGenerationHttpError } from "./content-generation/index.js";
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAQhE,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/C,OAAO,KAAK,YAAY,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC;AAC1C,iFAAiF;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAOxD,+EAA+E;AAC/E,2CAA2C;AAC3C,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,oCAAoC,GACrC,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAQhE,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/C,OAAO,KAAK,YAAY,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC;AAC1C,iFAAiF;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAOxD,+EAA+E;AAC/E,2CAA2C;AAC3C,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,oCAAoC,GACrC,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,cAAc,MAAM,2BAA2B,CAAC;AAC5D,iFAAiF;AACjF,OAAO,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AAIzE,oEAAoE;AACpE,OAAO,EAAE,yBAAyB,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAC;AAEtG,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,KAAK,iBAAiB,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/esm/orchestrations/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * `orchestrations` capability — run a deployed orchestration, and (the headline
+ * use) dispatch one FROM a step and pause until it finishes.
+ *
+ *   import { orchestrations } from "@sapiom/tools";
+ *   // dispatch another orchestration and pause this step on its result:
+ *   const child = await orchestrations.launch({ definition: "enrich-lead", input });
+ *   return pauseUntilSignal(child, { resumeStep: "use-result" });
+ *   // the resumed step receives an OrchestrationRunResultPayload
+ *
+ * `launch` returns a handle to pass straight to `pauseUntilSignal` (the waiting
+ * step resumes when the run finishes) or to `wait()` inline for standalone use.
+ * `run` is `launch` + `wait` — it blocks until the run reaches a terminal state, so
+ * use it for inline standalone calls, NOT to pause a step (it returns a result, not
+ * a pausable handle). An orchestration is addressed by its **slug** (its stable handle).
+ */
+import { Transport } from "../_client/index.js";
+import type { DispatchHandle } from "../dispatch.js";
+/**
+ * Signal a run fires when it reaches a terminal state (completed OR failed — the
+ * payload carries which, the resumed step branches). A step paused on an
+ * orchestration handle resumes on this; it is the value carried in the handle's
+ * `dispatch.resultSignal`.
+ */
+export declare const ORCHESTRATIONS_RESULT_SIGNAL = "orchestrations.result";
+/** Run lifecycle status. */
+export type ExecutionStatus = "running" | "paused" | "completed" | "failed" | "cancelled";
+export interface OrchestrationRunSpec {
+    /** Slug of the deployed orchestration to run (its stable handle). */
+    definition: string;
+    /** Input passed to the orchestration's entry step. */
+    input?: Record<string, unknown>;
+    /** Optional idempotency key — a repeat with the same key returns the existing run. */
+    idempotencyKey?: string;
+}
+/** A live, awaited run (the standalone `run()`/`wait()` result). */
+export interface OrchestrationRunResult {
+    executionId: string;
+    status: ExecutionStatus;
+    output: unknown;
+    error: unknown;
+}
+/**
+ * The typed result delivered to the step resumed from `pauseUntilSignal(handle, …)`
+ * — the payload that step receives as its `input`. Discriminated on `status` so a
+ * FAILURE is data the author branches on, not an exception.
+ *
+ *   const useResult = defineStep({
+ *     name: "use-result",
+ *     async run(result: OrchestrationRunResultPayload, ctx) {
+ *       if (result.status === "failed") { … }
+ *     },
+ *   });
+ */
+export type OrchestrationRunResultPayload<TOutput = unknown> = {
+    status: "completed";
+    executionId: string;
+    definition: string;
+    version: string;
+    output: TOutput;
+    startedAt: string;
+    finishedAt: string;
+} | {
+    status: "failed";
+    executionId: string;
+    definition: string;
+    version: string;
+    error: unknown;
+    startedAt: string;
+    finishedAt: string;
+};
+/** Thrown by {@link orchestrationResultSchema}.parse on a malformed resume payload. */
+export declare class OrchestrationResultSchemaError extends Error {
+}
+/**
+ * Runtime validator for {@link OrchestrationRunResultPayload}. `parse` returns the
+ * value typed on success and throws an {@link OrchestrationResultSchemaError} on any
+ * divergence. Generic in the caller's expected `output` type — the shape of
+ * `output` itself is the child orchestration's contract, not validated here.
+ */
+export declare const orchestrationResultSchema: {
+    parse<TOutput = unknown>(value: unknown): OrchestrationRunResultPayload<TOutput>;
+};
+/**
+ * A launched-but-not-awaited child run. Satisfies {@link DispatchHandle}, so it can
+ * be handed straight to `pauseUntilSignal(handle, { resumeStep })` to suspend the
+ * step until the child finishes — or `wait()`-ed inline for standalone use.
+ */
+export interface RunHandle extends DispatchHandle {
+    executionId: string;
+    /** Fetch the current status without blocking. */
+    status(): Promise<ExecutionStatus>;
+    /** Poll to a terminal state and resolve the run result. */
+    wait(opts?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<OrchestrationRunResult>;
+}
+export declare function launch(spec: OrchestrationRunSpec, transport?: Transport, baseUrl?: string): Promise<RunHandle>;
+export declare function run(spec: OrchestrationRunSpec, transport?: Transport, baseUrl?: string): Promise<OrchestrationRunResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/orchestrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/orchestrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,SAAS,EAAoB,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAKrD;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,0BAA0B,CAAC;AAEpE,4BAA4B;AAC5B,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,WAAW,CAAC;AAGhB,MAAM,WAAW,oBAAoB;IACnC,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,sFAAsF;IACtF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,6BAA6B,CAAC,OAAO,GAAG,OAAO,IACvD;IACE,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,GACD;IACE,MAAM,EAAE,QAAQ,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEN,uFAAuF;AACvF,qBAAa,8BAA+B,SAAQ,KAAK;CAAG;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;UAC9B,OAAO,mBAAmB,OAAO,GAAG,6BAA6B,CAAC,OAAO,CAAC;CAuBjF,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,SAAU,SAAQ,cAAc;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,MAAM,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IACnC,2DAA2D;IAC3D,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACvF;AA4BD,wBAAsB,MAAM,CAC1B,IAAI,EAAE,oBAAoB,EAC1B,SAAS,GAAE,SAA8B,EACzC,OAAO,SAAmB,GACzB,OAAO,CAAC,SAAS,CAAC,CAyCpB;AAED,wBAAsB,GAAG,CACvB,IAAI,EAAE,oBAAoB,EAC1B,SAAS,GAAE,SAA8B,EACzC,OAAO,SAAmB,GACzB,OAAO,CAAC,sBAAsB,CAAC,CAGjC"}

package/dist/esm/orchestrations/index.js

@@ -0,0 +1,108 @@
+/**
+ * `orchestrations` capability — run a deployed orchestration, and (the headline
+ * use) dispatch one FROM a step and pause until it finishes.
+ *
+ *   import { orchestrations } from "@sapiom/tools";
+ *   // dispatch another orchestration and pause this step on its result:
+ *   const child = await orchestrations.launch({ definition: "enrich-lead", input });
+ *   return pauseUntilSignal(child, { resumeStep: "use-result" });
+ *   // the resumed step receives an OrchestrationRunResultPayload
+ *
+ * `launch` returns a handle to pass straight to `pauseUntilSignal` (the waiting
+ * step resumes when the run finishes) or to `wait()` inline for standalone use.
+ * `run` is `launch` + `wait` — it blocks until the run reaches a terminal state, so
+ * use it for inline standalone calls, NOT to pause a step (it returns a result, not
+ * a pausable handle). An orchestration is addressed by its **slug** (its stable handle).
+ */
+import { defaultTransport } from "../_client/index.js";
+const DEFAULT_BASE_URL = process.env.SAPIOM_WORKFLOWS_URL || "https://workflows.services.sapiom.ai";
+/**
+ * Signal a run fires when it reaches a terminal state (completed OR failed — the
+ * payload carries which, the resumed step branches). A step paused on an
+ * orchestration handle resumes on this; it is the value carried in the handle's
+ * `dispatch.resultSignal`.
+ */
+export const ORCHESTRATIONS_RESULT_SIGNAL = "orchestrations.result";
+const TERMINAL = new Set(["completed", "failed", "cancelled"]);
+/** Thrown by {@link orchestrationResultSchema}.parse on a malformed resume payload. */
+export class OrchestrationResultSchemaError extends Error {
+}
+/**
+ * Runtime validator for {@link OrchestrationRunResultPayload}. `parse` returns the
+ * value typed on success and throws an {@link OrchestrationResultSchemaError} on any
+ * divergence. Generic in the caller's expected `output` type — the shape of
+ * `output` itself is the child orchestration's contract, not validated here.
+ */
+export const orchestrationResultSchema = {
+    parse(value) {
+        const fail = (msg) => {
+            throw new OrchestrationResultSchemaError(`invalid orchestration result payload: ${msg}`);
+        };
+        if (!value || typeof value !== "object")
+            fail("not an object");
+        const v = value;
+        if (v.status !== "completed" && v.status !== "failed")
+            fail("status must be 'completed' or 'failed'");
+        if (typeof v.executionId !== "string")
+            fail("executionId must be a string");
+        if (typeof v.definition !== "string")
+            fail("definition must be a string");
+        if (typeof v.version !== "string")
+            fail("version must be a string");
+        if (typeof v.startedAt !== "string")
+            fail("startedAt must be a string");
+        if (typeof v.finishedAt !== "string")
+            fail("finishedAt must be a string");
+        if (v.status === "completed" && !("output" in v))
+            fail("a completed result must carry `output`");
+        if (v.status === "failed" && !("error" in v))
+            fail("a failed result must carry `error`");
+        return value;
+    },
+};
+/**
+ * Inside a Sapiom workflow a resume token is provided via the environment;
+ * forwarding it (as a header, not a body field) lets the run resume the waiting
+ * step when it finishes. Outside a workflow there's no token, so nothing is sent.
+ */
+function workflowResumeHeaders() {
+    const token = process.env.SAPIOM_CAPABILITY_RESUME_TOKEN;
+    return token ? { "x-sapiom-workflow-token": token } : {};
+}
+export async function launch(spec, transport = defaultTransport(), baseUrl = DEFAULT_BASE_URL) {
+    const res = await transport.request(`${baseUrl}/v1/workflows/${encodeURIComponent(spec.definition)}/executions`, {
+        method: "POST",
+        body: JSON.stringify({ input: spec.input ?? {}, idempotencyKey: spec.idempotencyKey }),
+        headers: workflowResumeHeaders(),
+    });
+    const executionId = res.executionId;
+    const fetchDoc = () => transport.request(`${baseUrl}/v1/workflows/executions/${encodeURIComponent(executionId)}`);
+    return {
+        executionId,
+        // Framework plumbing for `pauseUntilSignal` — see DispatchHandle. correlationId
+        // is this run's id (the resume's correlation key).
+        dispatch: { correlationId: executionId, resultSignal: ORCHESTRATIONS_RESULT_SIGNAL },
+        async status() {
+            return (await fetchDoc()).status;
+        },
+        async wait({ timeoutMs = 60 * 60000, pollMs = 3000 } = {}) {
+            const deadline = Date.now() + timeoutMs;
+            // eslint-disable-next-line no-constant-condition
+            while (true) {
+                const d = await fetchDoc();
+                if (TERMINAL.has(d.status)) {
+                    return { executionId, status: d.status, output: d.output ?? null, error: d.error ?? null };
+                }
+                if (Date.now() > deadline) {
+                    throw new Error(`orchestration ${executionId} timed out after ${timeoutMs}ms (last status: ${d.status})`);
+                }
+                await new Promise((r) => setTimeout(r, pollMs));
+            }
+        },
+    };
+}
+export async function run(spec, transport = defaultTransport(), baseUrl = DEFAULT_BASE_URL) {
+    const handle = await launch(spec, transport, baseUrl);
+    return handle.wait();
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/orchestrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/orchestrations/index.ts"],"names":[],"mappings":"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"}