@sapiom/tools 0.1.2 → 0.2.0

package/dist/cjs/repositories/index.js

@@ -8,26 +8,15 @@ exports.attach = attach;
 exports.delete = deleteRepository;
 /**
  * `repositories` capability — in-network git repos: create, get, list, delete, and
- * the first cross-capability mesh method, `repo.pushFromSandbox(sandbox)`.
+ * `repo.pushFromSandbox(sandbox)` to commit + push a sandbox checkout.
  *
  *   import { repositories } from "@sapiom/tools";
  *   const repo = await repositories.create("my-app");
  *   // … an agent or your code writes files in a sandbox checkout of the repo …
  *   await repo.pushFromSandbox(box, { message: "build: page" });
- *
- * `pushFromSandbox` is the deterministic counterpart to a fuzzy agent step: it
- * composes the `sandboxes` capability (calls `sandbox.exec`) to commit + push the
- * repo's working tree. It references the `Sandbox` TYPE only — no module cycle.
- *
- * Note: `cloneUrl` is the unauthenticated origin. The gateway authenticates clones
- * via basic-auth (the `auth` block returned by create); inside an agent run the
- * `gitRepository` auto-clone wires that credential into the in-sandbox origin, so
- * `pushFromSandbox` doesn't need it.
  */
 const index_js_1 = require("../_client/index.js");
 const DEFAULT_BASE_URL = process.env.SAPIOM_GIT_URL || "https://git.services.sapiom.ai";
-/** Canonical in-sandbox checkout path (matches the agent's `gitRepository` auto-clone). */
-const checkoutDir = (slug) => `/workspace/${slug}`;
 /** A connected in-network repository. */
 class Repository {
     constructor(fields, transport, baseUrl) {
@@ -69,26 +58,25 @@ class Repository {
         return Repository.delete(this.slug, this.transport, this.baseUrl);
     }
     /**
-     * Deterministically stage + commit + push this repo's working tree FROM a
-     * sandbox checkout (no LLM). Assumes the repo is checked out at the canonical
-     * `/workspace/<slug>` with an authenticated `origin` (which the agent's
-     * `gitRepository` auto-clone sets up). No-op when there's nothing to commit.
+     * Commit and push this repo's working tree from a sandbox checkout. Commits any
+     * pending changes and pushes the current commit, so the agent's work is
+     * published whether it left changes uncommitted, already committed them, or
+     * both. Returns `{ pushed, sha, branch }`; throws if the push fails.
+     *
+     * `workingDirectory` defaults to the repo's checkout at `/workspace/<slug>`
+     * (where a coding agent run with `gitRepository: repo` clones it).
      */
     async pushFromSandbox(sandbox, opts = {}) {
-        const message = (opts.message ?? `update ${this.slug}`).replace(/'/g, ""); // single-quote-safe for sh -c
-        const script = `cd ${checkoutDir(this.slug)} && git add -A && ` +
-            `if git diff --cached --quiet; then echo NO_CHANGES; else ` +
-            `git -c user.email=workflow@sapiom.ai -c user.name=sapiom-workflow commit -m "${message}" >/dev/null && ` +
-            `git push origin HEAD && printf "SHA:%s\\n" "$(git rev-parse HEAD)"; fi`;
-        const { stdout, stderr, exitCode } = await sandbox.exec(`sh -c '${script}'`);
-        const out = `${stdout}\n${stderr}`;
-        if (out.includes("NO_CHANGES"))
-            return { pushed: false, sha: null };
-        const sha = out.match(/SHA:([0-9a-f]{7,40})/)?.[1] ?? null;
-        if (exitCode !== 0 || !sha) {
-            throw new Error(`pushFromSandbox(${this.slug}) failed (exit ${exitCode}): ${out.slice(-300)}`);
-        }
-        return { pushed: true, sha };
+        return this.transport.request(`${this.baseUrl}/v1/git/repositories/${encodeURIComponent(this.slug)}/push-from-sandbox`, {
+            method: "POST",
+            body: JSON.stringify({
+                executionEnvironmentId: sandbox.name,
+                ...(opts.workingDirectory
+                    ? { workingDirectory: opts.workingDirectory }
+                    : {}),
+                ...(opts.message ? { message: opts.message } : {}),
+            }),
+        });
     }
 }
 exports.Repository = Repository;

package/dist/cjs/repositories/index.js.map

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

package/dist/cjs/stub/index.d.ts

@@ -0,0 +1,19 @@
+import type { Sapiom } from '../client.js';
+/** Per-capability overrides, keyed by capability path (see module docs). */
+export type StubOverrides = Record<string, unknown | ((...args: unknown[]) => unknown)>;
+export interface StubClientOptions {
+    overrides?: StubOverrides;
+    /**
+     * When provided, any dispatch-able capability records `(correlationId →
+     * result)` here (via {@link dispatchable}). A local runner uses it to
+     * auto-resume a `pauseUntilSignal(handle, …)` with the result the handle's
+     * signal would have carried.
+     */
+    signals?: Map<string, unknown>;
+}
+/**
+ * Create a stub `Sapiom` client. Runs every capability against built-in defaults;
+ * pass `overrides` to control the results a step branches on.
+ */
+export declare function createStubClient(opts?: StubClientOptions): Sapiom;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/stub/index.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAK3C,4EAA4E;AAC5E,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC;AAExF,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAkID;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,iBAAsB,GAAG,MAAM,CAuFrE"}

package/dist/cjs/stub/index.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStubClient = createStubClient;
+/**
+ * `@sapiom/tools/stub` — a stub capability client for local development.
+ *
+ * `createStubClient()` returns a `Sapiom` of the same shape as the real client,
+ * but every capability is satisfied by a built-in default (so a workflow runs
+ * locally with zero setup) plus optional per-capability overrides (when a step's
+ * logic branches on a result). No network, no credentials.
+ *
+ * It is shape-faithful: namespace methods return the real handle types
+ * (`Repository`, `Sandbox`, `RunHandle`), and a handle's instance methods
+ * (`repo.pushFromSandbox(...)`, `sandbox.exec(...)`) work too — so a step never
+ * has to be rewritten to run locally. Method names are validated against the
+ * real handle classes, so a call to a method that doesn't exist throws.
+ *
+ * Overrides are keyed by capability path — namespace methods by their dotted
+ * path (`repositories.list`, `agent.coding.run`), handle methods by
+ * `<handle>.<method>` (`repository.pushFromSandbox`, `sandbox.exec`). A value
+ * replaces that capability's default; a function `(…args) => value` computes it
+ * from the call arguments.
+ */
+const index_js_1 = require("../agent/index.js");
+const index_js_2 = require("../repositories/index.js");
+const index_js_3 = require("../sandboxes/index.js");
+// Module-scoped so correlation ids are unique across launches within a run.
+let launchSeq = 0;
+/** A launched, pausable capability handle (the `DispatchHandle` shape). */
+function isDispatchHandle(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const h = v;
+    return typeof h.wait === 'function' && typeof h.dispatch?.correlationId === 'string';
+}
+/**
+ * Register a dispatch-able handle's eventual result so a pause on its signal can
+ * be auto-resumed, then return the handle. Capability-agnostic: any launch-style
+ * stub method wraps its returned handle in this — the result a `pauseUntilSignal`
+ * resumes with is exactly what the handle's `wait()` resolves to.
+ */
+async function dispatchable(handle, signals) {
+    if (signals && isDispatchHandle(handle)) {
+        signals.set(handle.dispatch.correlationId, await handle.wait());
+    }
+    return handle;
+}
+// Method names of each handle, reflected from the real classes so the stub stays
+// in lockstep with the SDK (a renamed/added method is picked up automatically).
+const REPOSITORY_METHODS = handleMethods(index_js_2.Repository.prototype);
+const SANDBOX_METHODS = handleMethods(index_js_3.Sandbox.prototype);
+const RUN_HANDLE_METHODS = new Set(['status', 'wait']); // RunHandle is a literal, not a class
+function handleMethods(proto) {
+    return new Set(Object.getOwnPropertyNames(proto).filter((n) => n !== 'constructor'));
+}
+function resolve(overrides, path, args, fallback) {
+    if (Object.prototype.hasOwnProperty.call(overrides, path)) {
+        const o = overrides[path];
+        return typeof o === 'function' ? o(...args) : o;
+    }
+    return fallback();
+}
+/**
+ * Build a handle proxy: data fields read from `data`; declared methods resolve an
+ * override (`<type>.<method>`) or a default; any other property is rejected as
+ * not part of the handle.
+ */
+function makeHandle(type, methods, data, overrides, defaults) {
+    return new Proxy(data, {
+        get(target, prop) {
+            if (typeof prop === 'symbol' || prop === 'then')
+                return undefined;
+            const key = String(prop);
+            if (key in target)
+                return target[key]; // data field (incl. nested handles)
+            if (methods.has(key)) {
+                return (...args) => Promise.resolve(resolve(overrides, `${type}.${key}`, args, () => defaults[key]?.(args)));
+            }
+            throw new Error(`'${type}.${key}' is not a method or field on this handle.`);
+        },
+    });
+}
+const REPO_METHOD_DEFAULTS = {
+    delete: () => undefined,
+    pushFromSandbox: () => ({ pushed: true, sha: 'stub00000000', branch: 'main' }),
+};
+const SANDBOX_METHOD_DEFAULTS = {
+    exec: () => ({ pid: 'stub-proc', exitCode: 0, stdout: '', stderr: '' }),
+    readFile: () => '',
+    writeFile: () => undefined,
+    destroy: () => undefined,
+};
+function stubRepository(data, overrides) {
+    return makeHandle('repository', REPOSITORY_METHODS, { slug: data.slug, cloneUrl: data.cloneUrl, status: data.status ?? 'active' }, overrides, REPO_METHOD_DEFAULTS);
+}
+function stubSandbox(data, overrides) {
+    return makeHandle('sandbox', SANDBOX_METHODS, { name: data.name, workspaceRoot: data.workspaceRoot ?? '/workspace' }, overrides, SANDBOX_METHOD_DEFAULTS);
+}
+function stubCodingResult(overrides) {
+    return {
+        runId: 'stub-run',
+        status: 'completed',
+        summary: '(stub) coding run completed locally',
+        result: {
+            success: true,
+            turns: 1,
+            modelUsed: 'stub-model',
+            durationMs: 0,
+            toolCallCount: 0,
+            usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreateTokens: 0, thinkingTokens: 0 },
+        },
+        error: null,
+        sandbox: stubSandbox({ name: 'stub-sandbox' }, overrides),
+    };
+}
+function stubRunHandle(overrides, correlationId, result) {
+    const handle = {
+        runId: correlationId,
+        sandbox: result.sandbox,
+        dispatch: { correlationId, resultSignal: index_js_1.CODING_RESULT_SIGNAL },
+        status: () => Promise.resolve(result.status),
+        wait: () => Promise.resolve(result),
+    };
+    return makeHandle('runHandle', RUN_HANDLE_METHODS, handle, overrides, {});
+}
+/**
+ * Create a stub `Sapiom` client. Runs every capability against built-in defaults;
+ * pass `overrides` to control the results a step branches on.
+ */
+function createStubClient(opts = {}) {
+    const overrides = opts.overrides ?? {};
+    const r = (path, args, fallback) => resolve(overrides, path, args, fallback);
+    const client = {
+        sandboxes: {
+            create: (sandboxOpts) => Promise.resolve(r('sandboxes.create', [sandboxOpts], () => stubSandbox({ name: sandboxOpts?.name ?? 'stub-sandbox' }, overrides))),
+            attach: (name, attachOpts) => r('sandboxes.attach', [name, attachOpts], () => stubSandbox({ name }, overrides)),
+        },
+        repositories: {
+            create: (slug) => Promise.resolve(r('repositories.create', [slug], () => stubRepository({ slug, cloneUrl: `https://git.local/${slug}.git` }, overrides))),
+            get: (slug) => Promise.resolve(r('repositories.get', [slug], () => stubRepository({ slug, cloneUrl: `https://git.local/${slug}.git` }, overrides))),
+            list: () => Promise.resolve(r('repositories.list', [], () => [])),
+            delete: (slug) => Promise.resolve(r('repositories.delete', [slug], () => undefined)),
+            attach: (slug, cloneUrl) => r('repositories.attach', [slug, cloneUrl], () => stubRepository({ slug, cloneUrl }, overrides)),
+        },
+        agent: {
+            coding: {
+                run: (spec) => Promise.resolve(r('agent.coding.run', [spec], () => stubCodingResult(overrides))),
+                launch: (spec) => {
+                    const correlationId = `stub-run-${++launchSeq}`;
+                    // The resume payload IS the run result, so `agent.coding.run`
+                    // overrides control both `await run()` and `launch()` + pause.
+                    const result = {
+                        ...r('agent.coding.run', [spec], () => stubCodingResult(overrides)),
+                        runId: correlationId,
+                    };
+                    // Generic: any dispatch-able handle registers itself for pause-resume.
+                    return dispatchable(stubRunHandle(overrides, correlationId, result), opts.signals);
+                },
+            },
+        },
+        fileStorage: {
+            upload: (input) => Promise.resolve(r('fileStorage.upload', [input], () => ({
+                fileId: 'stub-file',
+                uploadUrl: 'https://storage.local/upload/stub-file',
+                expiresAt: '2099-01-01T00:00:00Z',
+                requiredHeaders: {},
+            }))),
+            getDownloadUrl: (fileId) => Promise.resolve(r('fileStorage.getDownloadUrl', [fileId], () => ({
+                downloadUrl: `https://storage.local/download/${fileId}`,
+                expiresAt: '2099-01-01T00:00:00Z',
+            }))),
+            list: (listOpts) => Promise.resolve(r('fileStorage.list', [listOpts], () => ({ files: [], limit: 20, offset: 0, hasMore: false }))),
+            delete: (fileId) => Promise.resolve(r('fileStorage.delete', [fileId], () => undefined)),
+            setVisibility: (fileId, visibility) => Promise.resolve(r('fileStorage.setVisibility', [fileId, visibility], () => ({
+                fileId,
+                contentType: 'application/octet-stream',
+                visibility,
+                status: 'uploaded',
+                createdAt: '2099-01-01T00:00:00Z',
+                downloadRequestCount: 0,
+            }))),
+        },
+        withAttribution: () => client,
+    };
+    return client;
+}
+//# sourceMappingURL=index.js.map

package/dist/cjs/stub/index.js.map

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

package/dist/esm/client.d.ts

@@ -19,6 +19,7 @@ import { Sandbox } from "./sandboxes/index.js";
 import type { SandboxCreateOptions } from "./sandboxes/index.js";
 import { Repository } from "./repositories/index.js";
 import type { CodingRunSpec, CodingRunResult, RunHandle } from "./agent/index.js";
+import type { UploadInput, UploadResponse, DownloadUrlResponse, ListOptions, ListResponse, FileMetadata } from "./file-storage/index.js";
 export interface Sapiom {
     readonly sandboxes: {
         create(opts: SandboxCreateOptions): Promise<Sandbox>;
@@ -40,6 +41,13 @@ export interface Sapiom {
             launch(spec: CodingRunSpec): Promise<RunHandle>;
         };
     };
+    readonly fileStorage: {
+        upload(input: UploadInput): Promise<UploadResponse>;
+        getDownloadUrl(fileId: string): Promise<DownloadUrlResponse>;
+        list(opts?: ListOptions): Promise<ListResponse>;
+        delete(fileId: string): Promise<void>;
+        setVisibility(fileId: string, visibility: "private" | "public"): Promise<FileMetadata>;
+    };
     /**
      * Derive a client that attributes its calls to a different agent/trace. For the
      * router case (one process acting for many agents); step-authoring code doesn't

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

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,WAAW,EACjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,SAAS,EACV,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,SAAS,EAAE;QAClB,MAAM,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QACrD,MAAM,CACJ,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;YAAE,aAAa,CAAC,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,GAClD,OAAO,CAAC;KACZ,CAAC;IACF,QAAQ,CAAC,YAAY,EAAE;QACrB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;QAC1C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;QACvC,IAAI,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;QAC9B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAC;KACpD,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE;QACd,MAAM,EAAE;YACN,GAAG,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;YACnD,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;SACjD,CAAC;KACH,CAAC;IACF;;;;OAIG;IACH,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAAC;CAEnD;AA2BD,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,CAE7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,WAAW,EACjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAC/C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,SAAS,EACV,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,YAAY,EACZ,YAAY,EACb,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,SAAS,EAAE;QAClB,MAAM,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QACrD,MAAM,CACJ,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;YAAE,aAAa,CAAC,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,GAClD,OAAO,CAAC;KACZ,CAAC;IACF,QAAQ,CAAC,YAAY,EAAE;QACrB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;QAC1C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;QACvC,IAAI,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;QAC9B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAC;KACpD,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE;QACd,MAAM,EAAE;YACN,GAAG,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;YACnD,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;SACjD,CAAC;KACH,CAAC;IACF,QAAQ,CAAC,WAAW,EAAE;QACpB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;QACpD,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;QAChD,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACtC,aAAa,CACX,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,SAAS,GAAG,QAAQ,GAC/B,OAAO,CAAC,YAAY,CAAC,CAAC;KAC1B,CAAC;IACF;;;;OAIG;IACH,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAAC;CAEnD;AAmCD,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,CAE7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C"}

package/dist/esm/client.js

@@ -18,6 +18,7 @@ import { Transport, attributionFromEnv, } from "./_client/index.js";
 import { Sandbox } from "./sandboxes/index.js";
 import { Repository } from "./repositories/index.js";
 import { run as codingRun, launch as codingLaunch } from "./agent/index.js";
+import * as fileStorage from "./file-storage/index.js";
 /** Bind every capability namespace to a transport. `withAttribution` rebinds to a derived one. */
 function bind(transport) {
     return {
@@ -38,6 +39,13 @@ function bind(transport) {
                 launch: (spec) => codingLaunch(spec, transport),
             },
         },
+        fileStorage: {
+            upload: (input) => fileStorage.upload(input, transport),
+            getDownloadUrl: (fileId) => fileStorage.getDownloadUrl(fileId, transport),
+            list: (opts) => fileStorage.list(opts, transport),
+            delete: (fileId) => fileStorage.delete(fileId, transport),
+            setVisibility: (fileId, visibility) => fileStorage.setVisibility(fileId, visibility, transport),
+        },
         withAttribution: (attribution) => bind(transport.withAttribution(attribution)),
     };
 }

package/dist/esm/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EACL,SAAS,EACT,kBAAkB,GAGnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/C,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,GAAG,IAAI,SAAS,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAqC5E,kGAAkG;AAClG,SAAS,IAAI,CAAC,SAAoB;IAChC,OAAO;QACL,SAAS,EAAE;YACT,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC;YACjD,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC;SAC9D;QACD,YAAY,EAAE;YACZ,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC;YACpD,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC;YAC9C,IAAI,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC;YACtC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC;YACpD,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,CAAC;SACzE;QACD,KAAK,EAAE;YACL,MAAM,EAAE;gBACN,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC;gBACzC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC;aAChD;SACF;QACD,eAAe,EAAE,CAAC,WAAW,EAAE,EAAE,CAC/B,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAwB;IACnD,OAAO,IAAI,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,IAAI,CAAC,IAAI,SAAS,CAAC,EAAE,WAAW,EAAE,kBAAkB,EAAE,EAAE,CAAC,CAAC,CAAC;AACpE,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EACL,SAAS,EACT,kBAAkB,GAGnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/C,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,GAAG,IAAI,SAAS,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAM5E,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AAkDvD,kGAAkG;AAClG,SAAS,IAAI,CAAC,SAAoB;IAChC,OAAO;QACL,SAAS,EAAE;YACT,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC;YACjD,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,CAAC;SAC9D;QACD,YAAY,EAAE;YACZ,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC;YACpD,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC;YAC9C,IAAI,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC;YACtC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC;YACpD,MAAM,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,CAAC;SACzE;QACD,KAAK,EAAE;YACL,MAAM,EAAE;gBACN,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC;gBACzC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,SAAS,CAAC;aAChD;SACF;QACD,WAAW,EAAE;YACX,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC;YACvD,cAAc,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,WAAW,CAAC,cAAc,CAAC,MAAM,EAAE,SAAS,CAAC;YACzE,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC;YACjD,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC;YACzD,aAAa,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,CACpC,WAAW,CAAC,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,CAAC;SAC3D;QACD,eAAe,EAAE,CAAC,WAAW,EAAE,EAAE,CAC/B,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAwB;IACnD,OAAO,IAAI,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,IAAI,CAAC,IAAI,SAAS,CAAC,EAAE,WAAW,EAAE,kBAAkB,EAAE,EAAE,CAAC,CAAC,CAAC;AACpE,CAAC"}

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

@@ -0,0 +1,16 @@
+/**
+ * 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
+ * raw text when the body isn't JSON) for programmatic inspection.
+ */
+export declare class FileStorageHttpError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+/**
+ * Return the response when 2xx, otherwise throw a {@link FileStorageHttpError}.
+ * 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/file-storage/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/file-storage/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,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/file-storage/errors.js

@@ -0,0 +1,31 @@
+/**
+ * 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
+ * raw text when the body isn't JSON) for programmatic inspection.
+ */
+export class FileStorageHttpError extends Error {
+    constructor(message, status, body) {
+        super(message);
+        this.name = "FileStorageHttpError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/**
+ * Return the response when 2xx, otherwise throw a {@link FileStorageHttpError}.
+ * 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 FileStorageHttpError(`${errorPrefix}: ${response.status} ${text}`, response.status, body);
+}
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/file-storage/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAI7C,YAAY,OAAe,EAAE,MAAc,EAAE,IAAa;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,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,oBAAoB,CAC5B,GAAG,WAAW,KAAK,QAAQ,CAAC,MAAM,IAAI,IAAI,EAAE,EAC5C,QAAQ,CAAC,MAAM,EACf,IAAI,CACL,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,116 @@
+/**
+ * `fileStorage` capability — tenant-scoped object storage on presigned GCS 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
+ * `getDownloadUrl` hands back a presigned URL you GET. `list`, `setVisibility`, and
+ * `delete` round out the lifecycle.
+ *
+ *   import { fileStorage } from "@sapiom/tools";              // ambient auth
+ *   const { uploadUrl, requiredHeaders } = await fileStorage.upload({
+ *     contentType: "image/png",
+ *     fileName: "photo.png",
+ *   });
+ *   await fetch(uploadUrl, { method: "PUT", headers: requiredHeaders, body: bytes });
+ *
+ * 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`.
+ */
+import { Transport } from "../_client/index.js";
+import { FileStorageHttpError } from "./errors.js";
+export { FileStorageHttpError };
+export interface UploadInput {
+    /** MIME content type of the file (e.g. "image/png", "application/pdf"). */
+    contentType: string;
+    /** Original file name for display purposes. */
+    fileName?: string;
+    /**
+     * File visibility.
+     * - "private" — download requires authentication (default).
+     * - "public"  — download URL is unauthenticated.
+     */
+    visibility?: "private" | "public";
+    /** Expected file size in bytes. Used to pre-allocate storage. */
+    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`. */
+    uploadUrl: string;
+    /** ISO-8601 timestamp when the upload URL expires. */
+    expiresAt: string;
+    /** Headers that must be sent when PUTting bytes to `uploadUrl` (e.g. Content-Type). */
+    requiredHeaders: Record<string, string>;
+}
+export interface DownloadUrlResponse {
+    /** Presigned GCS download URL. Expires at `expiresAt`. */
+    downloadUrl: string;
+    /** ISO-8601 timestamp when the download URL expires. */
+    expiresAt: string;
+}
+export interface FileMetadata {
+    /** Unique file identifier. */
+    fileId: string;
+    /** Original file name, if provided at upload time. */
+    fileName?: string;
+    /** MIME content type. */
+    contentType: string;
+    /** File visibility ("private" or "public"). */
+    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.
+     */
+    expectedFileSize?: string | null;
+    /** Actual size in bytes after upload (string; `null` until the verify sweep records it). */
+    actualFileSize?: string | null;
+    /** ISO-8601 timestamp when the record was created. */
+    createdAt: string;
+    /** ISO-8601 timestamp when the bytes were uploaded. */
+    uploadedAt?: string;
+    /** ISO-8601 timestamp when the file was soft-deleted. */
+    deletedAt?: string;
+    /** Number of times a download URL was generated for this file. */
+    downloadRequestCount: number;
+}
+export interface ListOptions {
+    /** Maximum number of files to return. */
+    limit?: number;
+    /** Number of files to skip (pagination). */
+    offset?: number;
+}
+export interface ListResponse {
+    /** Files on the current page. */
+    files: FileMetadata[];
+    /** Page size used. */
+    limit: number;
+    /** Offset used. */
+    offset: number;
+    /** Whether more files exist beyond this page. */
+    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).
+ */
+export declare function upload(input: UploadInput, transport?: Transport, baseUrl?: string): Promise<UploadResponse>;
+/** Generate a presigned download URL for a file. */
+export declare function getDownloadUrl(fileId: string, transport?: Transport, baseUrl?: string): Promise<DownloadUrlResponse>;
+/** List files owned by the authenticated tenant. */
+export declare function list(opts?: ListOptions, transport?: Transport, baseUrl?: string): Promise<ListResponse>;
+/** 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`:
+ * `import { fileStorage } from "@sapiom/tools"; await fileStorage.delete(id)`.
+ */
+declare function deleteFile(fileId: string, transport?: Transport, baseUrl?: string): Promise<void>;
+export { deleteFile as delete };
+//# sourceMappingURL=index.d.ts.map

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

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