@sapiom/tools 0.6.2 → 0.7.0

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

@@ -1,5 +1,5 @@
 /**
- * `contentGeneration` capability — generate media (images today; video and audio
+ * `contentGeneration` capability — generate media (images and video today; audio
  * to come), with an optional `storage` param that persists each output to Sapiom
  * file storage so you get a durable `fileId` back inline.
  *
@@ -78,10 +78,62 @@ export interface ImageGenerationResult {
 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.
+ * same whether imported from the barrel or used on a client.
  */
 export declare const images: {
     create: typeof createImage;
 };
+export interface VideoCreateInput {
+    /** Text prompt describing the video to generate. */
+    prompt: string;
+    /**
+     * Optional model selector. Defaults to a standard video model; most callers omit it.
+     * (Model identifiers are an advanced, evolving surface.)
+     */
+    model?: string;
+    /**
+     * Optional: persist the generated output to Sapiom file storage. When set, the
+     * returned `video` comes back annotated with `fileId` (or `storageError` if
+     * persisting failed).
+     */
+    storage?: StorageOptions;
+    /** Advanced: extra model-specific parameters, forwarded verbatim. */
+    params?: Record<string, unknown>;
+    /** How often to poll while the video generates (default 5s). */
+    pollIntervalMs?: number;
+    /** Give up and throw if the result isn't ready within this window (default 5 min). */
+    timeoutMs?: number;
+}
+export interface GeneratedVideo {
+    /** Hosted URL of the generated video. */
+    url: string;
+    /** MIME type, when reported. */
+    contentType?: string;
+    /**
+     * Present when `storage` was requested and the output was persisted — pass to
+     * `fileStorage.getDownloadUrl(fileId)` to retrieve it.
+     */
+    fileId?: string;
+    /** Present when `storage` was requested but persisting the output failed. */
+    storageError?: string;
+}
+export interface VideoGenerationResult {
+    /** The generated video. */
+    video?: GeneratedVideo;
+    /** Additional model-specific fields (e.g. `seed`, `timings`), returned as-is. */
+    [key: string]: unknown;
+}
+/**
+ * Generate a video from a prompt. Video generation is asynchronous: this submits the
+ * job, then polls the result through Sapiom until it's ready and returns it — so you
+ * `await` it just like {@link createImage}, it just takes longer. Pass `storage` to
+ * persist the output (the returned `video` then carries `fileId`). Throws
+ * {@link ContentGenerationHttpError} on a failed submit, or an `Error` if the result
+ * isn't ready within `timeoutMs`.
+ */
+export declare function createVideo(input: VideoCreateInput, transport?: Transport, baseUrl?: string): Promise<VideoGenerationResult>;
+/** The `video` sub-namespace: `contentGeneration.video.create(...)`. Async (submit + poll). */
+export declare const video: {
+    create: typeof createVideo;
+};
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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"}
+{"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;;;GAGG;AACH,eAAO,MAAM,MAAM;;CAA0B,CAAC;AAU9C,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,2BAA2B;IAC3B,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,iFAAiF;IACjF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAwCD;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,gBAAgB,EACvB,SAAS,GAAE,SAA8B,EACzC,OAAO,SAAmB,GACzB,OAAO,CAAC,qBAAqB,CAAC,CA8ChC;AAED,+FAA+F;AAC/F,eAAO,MAAM,KAAK;;CAA0B,CAAC"}

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

@@ -1,5 +1,5 @@
 /**
- * `contentGeneration` capability — generate media (images today; video and audio
+ * `contentGeneration` capability — generate media (images and video today; audio
  * to come), with an optional `storage` param that persists each output to Sapiom
  * file storage so you get a durable `fileId` back inline.
  *
@@ -66,8 +66,79 @@ export async function createImage(input, transport = defaultTransport(), baseUrl
 }
 /**
  * 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.
+ * same whether imported from the barrel or used on a client.
  */
 export const images = { create: createImage };
+// ----- Video (async) -----
+/** Default video model when the caller doesn't pick one. */
+const DEFAULT_VIDEO_MODEL = "fal-ai/veo3/fast";
+/** How often to poll for the async result, and when to give up. Caller-overridable. */
+const DEFAULT_VIDEO_POLL_INTERVAL_MS = 5000;
+const DEFAULT_VIDEO_TIMEOUT_MS = 5 * 60000;
+function mapVideo(raw) {
+    return {
+        url: raw.url,
+        ...(raw.content_type !== undefined && { contentType: raw.content_type }),
+        ...(raw.file_id !== undefined && { fileId: raw.file_id }),
+        ...(raw.storage_error !== undefined && { storageError: raw.storage_error }),
+    };
+}
+function mapVideoResult(raw) {
+    const { video, ...rest } = raw;
+    return video === undefined ? { ...rest } : { ...rest, video: mapVideo(video) };
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Generate a video from a prompt. Video generation is asynchronous: this submits the
+ * job, then polls the result through Sapiom until it's ready and returns it — so you
+ * `await` it just like {@link createImage}, it just takes longer. Pass `storage` to
+ * persist the output (the returned `video` then carries `fileId`). Throws
+ * {@link ContentGenerationHttpError} on a failed submit, or an `Error` if the result
+ * isn't ready within `timeoutMs`.
+ */
+export async function createVideo(input, transport = defaultTransport(), baseUrl = DEFAULT_BASE_URL) {
+    const path = modelToPath(input.model || DEFAULT_VIDEO_MODEL);
+    const body = { prompt: input.prompt, ...input.params };
+    // Truthy check (not `!== undefined`) so `storage: null` is treated as "no storage".
+    if (input.storage)
+        body.storage = input.storage;
+    // Submit — for an async model Sapiom returns a queue handle, not the result.
+    const submitRes = await ensureOk(await transport.fetch(`${baseUrl}/run/${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    }), "Failed to submit video generation");
+    const handle = (await submitRes.json());
+    if (!handle.response_url) {
+        throw new Error("Video submit did not return a result URL to poll");
+    }
+    // Poll the result THROUGH Sapiom until it's ready. The poll is what persists the
+    // output when `storage` was requested, so `fileId` is filled in by the time it returns.
+    const intervalMs = input.pollIntervalMs ?? DEFAULT_VIDEO_POLL_INTERVAL_MS;
+    const timeoutMs = input.timeoutMs ?? DEFAULT_VIDEO_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const res = await transport.fetch(handle.response_url, { method: "GET" });
+        if (res.ok) {
+            const raw = (await res.json());
+            if (raw.video?.url)
+                return mapVideoResult(raw);
+        }
+        else {
+            // Still generating, or a transient error. Drain the unread body so the
+            // connection can be reused, then keep polling — `timeoutMs` is the backstop
+            // for a result that never arrives.
+            try {
+                await res.body?.cancel();
+            }
+            catch {
+                // best-effort drain
+            }
+        }
+        await sleep(intervalMs);
+    }
+    throw new Error(`Video generation did not complete within ${timeoutMs}ms (request id: ${handle.request_id ?? "unknown"})`);
+}
+/** The `video` sub-namespace: `contentGeneration.video.create(...)`. Async (submit + poll). */
+export const video = { create: createVideo };
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/content-generation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAa,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,MAAM,gBAAgB,GACpB,OAAO,CAAC,GAAG,CAAC,6BAA6B,IAAI,gCAAgC,CAAC;AAEhF,qFAAqF;AACrF,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AA8ElD,SAAS,QAAQ,CAAC,GAAa;IAC7B,OAAO;QACL,GAAG,EAAE,GAAG,CAAC,GAAG;QACZ,GAAG,CAAC,GAAG,CAAC,YAAY,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC;QACxE,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC;QACpD,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;QACvD,GAAG,CAAC,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;QACzD,GAAG,CAAC,GAAG,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,YAAY,EAAE,GAAG,CAAC,aAAa,EAAE,CAAC;KAC5E,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,GAAmB;IACpC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,GAAG,CAAC;IAChC,OAAO,MAAM,KAAK,SAAS;QACzB,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE;QACb,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;AAChD,CAAC;AAED,oCAAoC;AAEpC,wEAAwE;AACxE,SAAS,WAAW,CAAC,KAAa;IAChC,OAAO,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5E,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAuB,EACvB,YAAuB,gBAAgB,EAAE,EACzC,OAAO,GAAG,gBAAgB;IAE1B,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,KAAK,IAAI,mBAAmB,CAAC,CAAC;IAE7D,MAAM,IAAI,GAA4B;QACpC,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,GAAG,KAAK,CAAC,MAAM;KAChB,CAAC;IACF,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS;QAAE,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC;IACrE,4EAA4E;IAC5E,4DAA4D;IAC5D,IAAI,KAAK,CAAC,OAAO;QAAE,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAEhD,MAAM,GAAG,GAAG,MAAM,QAAQ,CACxB,MAAM,SAAS,CAAC,KAAK,CAAC,GAAG,OAAO,QAAQ,IAAI,EAAE,EAAE;QAC9C,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KAC3B,CAAC,EACF,0BAA0B,CAC3B,CAAC;IACF,OAAO,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAmB,CAAC,CAAC;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/content-generation/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.d.ts

@@ -26,9 +26,11 @@ export { codingResultSchema, CodingResultSchemaError, toResumePayload, EXECUTION
 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 { 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";
+export * as search from "./search/index.js";
+export { SearchHttpError } from "./search/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,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"}
+{"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,EACL,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,2BAA2B,CAAC;AAEnC,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;AAE3E,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/esm/index.js

@@ -26,9 +26,11 @@ 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 { 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";
+export * as search from "./search/index.js";
+export { SearchHttpError } from "./search/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,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"}
+{"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,EACL,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,2BAA2B,CAAC;AAEnC,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;AAE3E,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/esm/search/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Error thrown by the `search` 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 SearchHttpError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+/**
+ * Return the response when 2xx, otherwise throw a {@link SearchHttpError}.
+ * Parses the error body as JSON when possible; falls back to raw text.
+ */
+export declare function ensureOk(response: Response, errorPrefix: string): Promise<Response>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/esm/search/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/search/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAM3D;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,QAAQ,CAAC,CAcnB"}

package/dist/esm/search/errors.js

@@ -0,0 +1,31 @@
+/**
+ * Error thrown by the `search` 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 SearchHttpError extends Error {
+    constructor(message, status, body) {
+        super(message);
+        this.name = "SearchHttpError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/**
+ * Return the response when 2xx, otherwise throw a {@link SearchHttpError}.
+ * Parses the error body as JSON when possible; falls back to raw text.
+ */
+export async function ensureOk(response, errorPrefix) {
+    if (response.ok)
+        return response;
+    let body;
+    const text = await response.text().catch(() => "");
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = text;
+    }
+    throw new SearchHttpError(`${errorPrefix}: ${response.status} ${text}`, response.status, body);
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/search/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/search/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAIxC,YAAY,OAAe,EAAE,MAAc,EAAE,IAAa;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,QAAkB,EAClB,WAAmB;IAEnB,IAAI,QAAQ,CAAC,EAAE;QAAE,OAAO,QAAQ,CAAC;IACjC,IAAI,IAAa,CAAC;IAClB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IACnD,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,GAAG,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,eAAe,CACvB,GAAG,WAAW,KAAK,QAAQ,CAAC,MAAM,IAAI,IAAI,EAAE,EAC5C,QAAQ,CAAC,MAAM,EACf,IAAI,CACL,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,105 @@
+/**
+ * `search` capability — find information across the web and beyond.
+ *
+ * This is the home for Sapiom's search primitives: searching the web, reading the
+ * contents of a page, and looking up professional email addresses. Today it
+ * offers `webSearch` (search the web) and `scrape` (read a page); more operations
+ * follow.
+ *
+ *   import { search } from "@sapiom/tools";        // ambient auth
+ *   const hits = await search.webSearch({ query: "what is an LLM agent?" });
+ *   hits.answer;     // a synthesized answer
+ *   const page = await search.scrape({ url: "https://example.com" });
+ *   page.markdown;   // the page content as markdown
+ *
+ * Or via an explicit client: `createClient({ apiKey }).search.webSearch(...)`.
+ *
+ * Failed requests throw {@link SearchHttpError} (carries `status` + parsed `body`).
+ */
+import { Transport } from "../_client/index.js";
+import { SearchHttpError } from "./errors.js";
+export { SearchHttpError };
+/** Output formats `scrape` can return. Defaults to `["markdown"]`. */
+export type ScrapeFormat = "markdown" | "html" | "rawHtml" | "screenshot" | "links";
+export interface ScrapeInput {
+    /** URL of the page to read. */
+    url: string;
+    /** Which content formats to return. Defaults to `["markdown"]`. */
+    formats?: ScrapeFormat[];
+    /** Return only the main content, dropping nav/header/footer/ads. */
+    onlyMainContent?: boolean;
+    /** Milliseconds to wait before reading (for content rendered by JavaScript). */
+    waitFor?: number;
+}
+export interface ScrapeMetadata {
+    /** Page title. */
+    title?: string;
+    /** Page description. */
+    description?: string;
+    /** Detected page language. */
+    language?: string;
+    /** The URL the content was read from. */
+    sourceUrl?: string;
+    /** HTTP status code returned while reading the page. */
+    statusCode?: number;
+}
+export interface ScrapeResult {
+    /** The URL that was read (echoes the input). */
+    url: string;
+    /** Page content as markdown (present when "markdown" was requested). */
+    markdown?: string;
+    /** Cleaned HTML (present when "html" was requested). */
+    html?: string;
+    /** Raw HTML (present when "rawHtml" was requested). */
+    rawHtml?: string;
+    /** Screenshot URL (present when "screenshot" was requested). */
+    screenshot?: string;
+    /** Links found on the page (present when "links" was requested). */
+    links?: string[];
+    /** Page metadata (title, description, language, status, …). */
+    metadata: ScrapeMetadata;
+}
+/**
+ * Read a page and return its content. By default you get markdown; pass `formats`
+ * to also (or instead) get HTML, raw HTML, a screenshot, or the page's links.
+ *
+ * Works on HTML pages and common documents (PDF, DOCX, TXT). Failed requests throw
+ * {@link SearchHttpError}.
+ */
+export declare function scrape(input: ScrapeInput, transport?: Transport, baseUrl?: string): Promise<ScrapeResult>;
+export interface WebSearchInput {
+    /** What to search for. */
+    query: string;
+    /** How thoroughly to search. Defaults to `"standard"`. */
+    depth?: "standard" | "deep";
+    /**
+     * What you want back. `"answer"` (default) returns a synthesized answer plus
+     * supporting results; `"links"` returns a list of relevant results.
+     */
+    intent?: "answer" | "links";
+}
+export interface WebSearchResult {
+    /** Result title. */
+    title: string;
+    /** Result URL. */
+    url: string;
+    /** Short excerpt for the result. */
+    snippet: string;
+}
+export interface WebSearchResponse {
+    /** The query that was searched (echoes the input). */
+    query: string;
+    /** A synthesized answer, when `intent` is `"answer"`. */
+    answer?: string;
+    /** The results found for the query. */
+    results: WebSearchResult[];
+}
+/**
+ * Search the web. By default you get a synthesized answer plus supporting
+ * results; pass `intent: "links"` for a list of relevant results, and
+ * `depth: "deep"` for a more thorough search.
+ *
+ * Failed requests throw {@link SearchHttpError}.
+ */
+export declare function webSearch(input: WebSearchInput, transport?: Transport, baseUrl?: string): Promise<WebSearchResponse>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/search/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,SAAS,EAAoB,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAY,MAAM,aAAa,CAAC;AAExD,OAAO,EAAE,eAAe,EAAE,CAAC;AAU3B,sEAAsE;AACtE,MAAM,MAAM,YAAY,GACpB,UAAU,GACV,MAAM,GACN,SAAS,GACT,YAAY,GACZ,OAAO,CAAC;AAEZ,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,oEAAoE;IACpE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,kBAAkB;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,+DAA+D;IAC/D,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAkED;;;;;;GAMG;AACH,wBAAsB,MAAM,CAC1B,KAAK,EAAE,WAAW,EAClB,SAAS,GAAE,SAA8B,EACzC,OAAO,SAAmB,GACzB,OAAO,CAAC,YAAY,CAAC,CAkBvB;AAID,MAAM,WAAW,cAAc;IAC7B,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,KAAK,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAyCD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,cAAc,EACrB,SAAS,GAAE,SAA8B,EACzC,OAAO,SAA8B,GACpC,OAAO,CAAC,iBAAiB,CAAC,CAsB5B"}

package/dist/esm/search/index.js

@@ -0,0 +1,124 @@
+/**
+ * `search` capability — find information across the web and beyond.
+ *
+ * This is the home for Sapiom's search primitives: searching the web, reading the
+ * contents of a page, and looking up professional email addresses. Today it
+ * offers `webSearch` (search the web) and `scrape` (read a page); more operations
+ * follow.
+ *
+ *   import { search } from "@sapiom/tools";        // ambient auth
+ *   const hits = await search.webSearch({ query: "what is an LLM agent?" });
+ *   hits.answer;     // a synthesized answer
+ *   const page = await search.scrape({ url: "https://example.com" });
+ *   page.markdown;   // the page content as markdown
+ *
+ * Or via an explicit client: `createClient({ apiKey }).search.webSearch(...)`.
+ *
+ * Failed requests throw {@link SearchHttpError} (carries `status` + parsed `body`).
+ */
+import { defaultTransport } from "../_client/index.js";
+import { SearchHttpError, ensureOk } from "./errors.js";
+export { SearchHttpError };
+const DEFAULT_BASE_URL = process.env.SAPIOM_SCRAPE_URL || "https://firecrawl.services.sapiom.ai";
+const DEFAULT_WEB_SEARCH_BASE_URL = process.env.SAPIOM_SEARCH_URL || "https://api.sapiom.ai";
+/** Collapse a field that may be a single value or an array down to one value. */
+function firstOf(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+function mapMetadata(raw) {
+    const meta = raw ?? {};
+    const title = firstOf(meta.title);
+    const description = firstOf(meta.description);
+    // A field a caller didn't ask for comes back null — treat null as absent (`!=`)
+    // so the result only carries fields that were actually populated.
+    return {
+        ...(title != null && { title }),
+        ...(description != null && { description }),
+        ...(meta.language != null && { language: meta.language }),
+        ...(meta.sourceURL != null && { sourceUrl: meta.sourceURL }),
+        ...(meta.statusCode != null && { statusCode: meta.statusCode }),
+    };
+}
+function mapScrape(url, raw) {
+    const data = raw.data ?? {};
+    // Unrequested formats come back null; treat null as absent (`!=`) so each
+    // format field is present only when it was actually returned.
+    return {
+        url,
+        ...(data.markdown != null && { markdown: data.markdown }),
+        ...(data.html != null && { html: data.html }),
+        ...(data.rawHtml != null && { rawHtml: data.rawHtml }),
+        ...(data.screenshot != null && { screenshot: data.screenshot }),
+        ...(data.links != null && { links: data.links }),
+        metadata: mapMetadata(data.metadata),
+    };
+}
+// ----- Capability operations -----
+/**
+ * Read a page and return its content. By default you get markdown; pass `formats`
+ * to also (or instead) get HTML, raw HTML, a screenshot, or the page's links.
+ *
+ * Works on HTML pages and common documents (PDF, DOCX, TXT). Failed requests throw
+ * {@link SearchHttpError}.
+ */
+export async function scrape(input, transport = defaultTransport(), baseUrl = DEFAULT_BASE_URL) {
+    // `!= null` so an optional explicitly passed as null (a JS caller bypassing the
+    // types) is treated as absent rather than forwarded as a null field.
+    const body = { url: input.url };
+    if (input.formats != null)
+        body.formats = input.formats;
+    if (input.onlyMainContent != null)
+        body.onlyMainContent = input.onlyMainContent;
+    if (input.waitFor != null)
+        body.waitFor = input.waitFor;
+    const res = await ensureOk(await transport.fetch(`${baseUrl}/v2/scrape`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    }), "Failed to scrape");
+    return mapScrape(input.url, (await res.json()));
+}
+function mapWebSearchResult(raw) {
+    return {
+        title: raw.title ?? "",
+        url: raw.url ?? "",
+        snippet: raw.snippet ?? "",
+    };
+}
+function mapWebSearch(query, raw) {
+    // Build the result from only the public fields. A defensive measure: any
+    // extra top-level field on the wire (e.g. bookkeeping not meant for callers)
+    // is dropped by construction rather than spread through.
+    const results = Array.isArray(raw.results)
+        ? raw.results.map(mapWebSearchResult)
+        : [];
+    return {
+        query: raw.query ?? query,
+        ...(raw.answer != null && { answer: raw.answer }),
+        results,
+    };
+}
+/**
+ * Search the web. By default you get a synthesized answer plus supporting
+ * results; pass `intent: "links"` for a list of relevant results, and
+ * `depth: "deep"` for a more thorough search.
+ *
+ * Failed requests throw {@link SearchHttpError}.
+ */
+export async function webSearch(input, transport = defaultTransport(), baseUrl = DEFAULT_WEB_SEARCH_BASE_URL) {
+    // `!= null` so an optional explicitly passed as null (a JS caller bypassing the
+    // types) is treated as absent rather than forwarded as a null field.
+    const body = {
+        query: input.query,
+        intent: input.intent ?? "answer",
+    };
+    if (input.depth != null)
+        body.depth = input.depth;
+    const res = await ensureOk(await transport.fetch(`${baseUrl}/v1/capabilities/web.search`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    }, { authHeader: "x-api-key" }), "Failed to search the web");
+    return mapWebSearch(input.query, (await res.json()));
+}
+//# sourceMappingURL=index.js.map

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/stub/index.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAW3C,4EAA4E;AAC5E,MAAM,MAAM,aAAa,GAAG,MAAM,CAChC,MAAM,EACN,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAC5C,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACxB;AA0TD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,iBAAsB,GAAG,MAAM,CA2MrE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/stub/index.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAe3C,4EAA4E;AAC5E,MAAM,MAAM,aAAa,GAAG,MAAM,CAChC,MAAM,EACN,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAC5C,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACxB;AA0TD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,iBAAsB,GAAG,MAAM,CA0PrE"}

package/dist/esm/stub/index.js

@@ -315,7 +315,10 @@ export function createStubClient(opts = {}) {
                 };
                 const handle = {
                     executionId,
-                    dispatch: { correlationId: executionId, resultSignal: ORCHESTRATIONS_RESULT_SIGNAL },
+                    dispatch: {
+                        correlationId: executionId,
+                        resultSignal: ORCHESTRATIONS_RESULT_SIGNAL,
+                    },
                     status: () => Promise.resolve("completed"),
                     wait: () => Promise.resolve(result),
                 };
@@ -374,6 +377,41 @@ export function createStubClient(opts = {}) {
                     ],
                 }))),
             },
+            video: {
+                create: (input) => Promise.resolve(r("contentGeneration.video.create", [input], () => ({
+                    video: {
+                        url: "https://content.local/stub-video.mp4",
+                        contentType: "video/mp4",
+                        // mirror the real stitch: a fileId only when storage was requested.
+                        ...(input.storage ? { fileId: "stub-file" } : {}),
+                    },
+                }))),
+            },
+        },
+        search: {
+            scrape: (input) => Promise.resolve(r("search.scrape", [input], () => ({
+                url: input.url,
+                markdown: `# ${input.url}\n\n(stub) scraped content`,
+                metadata: {
+                    title: "Stub Page",
+                    sourceUrl: input.url,
+                    statusCode: 200,
+                },
+            }))),
+            webSearch: (input) => Promise.resolve(r("search.webSearch", [input], () => ({
+                query: input.query,
+                // mirror the real shape: an answer for the default intent, omitted for "links".
+                ...(input.intent === "links"
+                    ? {}
+                    : { answer: `(stub) answer for "${input.query}"` }),
+                results: [
+                    {
+                        title: "Stub Result",
+                        url: "https://example.com",
+                        snippet: `(stub) result for "${input.query}"`,
+                    },
+                ],
+            }))),
         },
         withAttribution: () => client,
     };