@schemavaults/sandbox-management-sdk 0.0.0-stage → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,158 @@
+/**
+ * A command to run inside a sandbox.
+ *
+ * - A `string` is run through `sh -c`, so pipes, `&&` and variable expansion work.
+ * - An object is run as an exact argv with no implicit shell.
+ */
+export type CommandInput = string | ArgvCommand;
+export interface ArgvCommand {
+    cmd: string;
+    args?: string[];
+    /** Working directory. Relative paths resolve against the sandbox workdir. */
+    cwd?: string;
+    /** Extra environment variables, merged over the sandbox's `spec.env`. */
+    env?: Record<string, string>;
+}
+/** A command after normalization: always argv, `cwd` always absolute. */
+export interface NormalizedCommand {
+    cmd: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+}
+export interface GitSource {
+    /** Clone URL, e.g. `https://github.com/org/repo.git`. */
+    url: string;
+    /** Branch, tag or commit SHA to check out. Defaults to the remote HEAD. */
+    revision?: string;
+    /** Shallow clone depth. Omit for full history. */
+    depth?: number;
+    /** HTTP basic credentials, e.g. `{ username: "x-access-token", password: token }`. */
+    auth?: {
+        username: string;
+        password: string;
+    };
+}
+export interface SandboxResources {
+    vcpus?: number;
+    memoryMb?: number;
+}
+/**
+ * Outbound network access for a sandbox, enforced by its provider.
+ *
+ * - `"allow-all"` (the default): no restriction.
+ * - `"deny-all"`: no outbound access at all.
+ * - An allowlist: only the listed destinations are reachable.
+ *
+ * The manager refuses to create a sandbox on a provider that cannot enforce
+ * the policy, so a policy is never silently ignored.
+ */
+export type SandboxNetworkPolicy = "allow-all" | "deny-all" | SandboxNetworkAllowlist;
+/** Everything not listed is denied, so an empty allowlist means no access. */
+export interface SandboxNetworkAllowlist {
+    /**
+     * Host names the sandbox may reach, e.g. `"github.com"`. A leading `*.`
+     * matches subdomains (`"*.npmjs.org"`); `"*"` matches every domain.
+     */
+    allowDomains?: string[];
+    /** IP addresses or CIDR ranges the sandbox may reach, e.g. `"203.0.113.10"` or `"10.0.0.0/8"`. */
+    allowCidrs?: string[];
+    /** IP addresses or CIDR ranges that are always blocked, even for allowed domains. */
+    denyCidrs?: string[];
+}
+/** The kind of a `SandboxNetworkPolicy`. Providers declare which kinds they enforce. */
+export type SandboxNetworkPolicyKind = "allow-all" | "deny-all" | "allowlist";
+/**
+ * Provider-specific spec options, keyed by provider name. Each adapter
+ * augments this interface with its own typed key (`docker`, `vercel`, ...).
+ */
+export interface SandboxProviderOptions {
+    [provider: string]: unknown;
+}
+/**
+ * Everything needed to (re)create and resume a sandbox. It is persisted in the
+ * store, so any process can resume a sandbox by ID alone.
+ *
+ * Note: `env` and `git.auth` are stored as-is; treat the store as sensitive.
+ */
+export interface SandboxSpec {
+    /** Directory commands run in. Defaults to the provider's workdir. */
+    workdir?: string;
+    /** Environment variables set for every command in the sandbox. */
+    env?: Record<string, string>;
+    /** Repository cloned into `workdir` before `setup` runs. */
+    git?: GitSource;
+    /** One-shot command(s) run once after creation; stops at the first non-zero exit. */
+    setup?: CommandInput | CommandInput[];
+    /** The long-running main process, launched detached after `setup`. */
+    start?: CommandInput;
+    /**
+     * Launched detached (as the new main process) whenever a stopped sandbox is
+     * woken back up. Defaults to `start`.
+     */
+    resume?: CommandInput;
+    /** Ports to expose; see `SandboxManager.getUrl`. */
+    ports?: number[];
+    /** Maximum time a sandbox may run before it is stopped. */
+    timeoutMs?: number;
+    resources?: SandboxResources;
+    /**
+     * Outbound network access. Applies from creation, so `git` and `setup`
+     * run under it too. Default `"allow-all"`.
+     */
+    network?: SandboxNetworkPolicy;
+    providerOptions?: SandboxProviderOptions;
+}
+export type SandboxStatus = "provisioning" | "setting_up" | "starting" | "running" | "stopping" | "stopped" | "resuming" | "failed" | "destroying" | "destroyed";
+export declare const SANDBOX_STATUSES: readonly SandboxStatus[];
+/** Statuses that are mid-operation; other callers wait for them to settle. */
+export declare const TRANSITIONAL_STATUSES: readonly SandboxStatus[];
+export interface SandboxRecord {
+    /** SDK-generated ID, e.g. `sbx-3f9c...`. */
+    id: string;
+    /** Name of the provider the sandbox lives on. */
+    provider: string;
+    /** The provider's own ID (Docker container ID, Vercel sandbox name). */
+    providerRef: string | null;
+    status: SandboxStatus;
+    spec: SandboxSpec;
+    /** Your user / tenant / project ID. Indexed for listing. */
+    ownerId: string | null;
+    /** String labels; `list({ labels })` matches records containing all given pairs. */
+    labels: Record<string, string>;
+    /** Free-form JSON metadata. Not queryable. */
+    metadata: Record<string, unknown>;
+    /** Last failure message, if any. */
+    error: string | null;
+    /** Incremented on every update; used for compare-and-set. */
+    version: number;
+    createdAt: Date;
+    updatedAt: Date;
+    /** When the sandbox should be stopped (from `spec.timeoutMs`). */
+    expiresAt: Date | null;
+}
+export interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface ExecOptions {
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface SandboxFile {
+    /** Relative paths resolve against the sandbox workdir. */
+    path: string;
+    content: string | Uint8Array;
+    /** Unix permission bits, e.g. `0o755`. Defaults to `0o644`. */
+    mode?: number;
+}
+/** State of the sandbox's detached main process (the `start` / `resume` command). */
+export interface MainProcessInfo {
+    pid: number | null;
+    running: boolean;
+    /** Exit code once the process has exited, otherwise `null`. */
+    exitCode: number | null;
+}

package/dist/types.js

@@ -0,0 +1,21 @@
+export const SANDBOX_STATUSES = [
+    "provisioning",
+    "setting_up",
+    "starting",
+    "running",
+    "stopping",
+    "stopped",
+    "resuming",
+    "failed",
+    "destroying",
+    "destroyed",
+];
+/** Statuses that are mid-operation; other callers wait for them to settle. */
+export const TRANSITIONAL_STATUSES = [
+    "provisioning",
+    "setting_up",
+    "starting",
+    "stopping",
+    "resuming",
+    "destroying",
+];

package/dist/vercel/index.d.ts

@@ -0,0 +1,2 @@
+export { VERCEL_DEFAULT_WORKDIR, VercelSandboxProvider, toVercelNetworkPolicy } from "./provider.js";
+export type { VercelCredentials, VercelRunCommandParams, VercelSandboxApi, VercelSandboxInstance, VercelSandboxOptions, VercelSandboxProviderOptions, } from "./provider.js";

package/dist/vercel/index.js

@@ -0,0 +1 @@
+export { VERCEL_DEFAULT_WORKDIR, VercelSandboxProvider, toVercelNetworkPolicy } from "./provider.js";

package/dist/vercel/provider.d.ts

@@ -0,0 +1,125 @@
+import type { Writable } from "node:stream";
+import type { MainLogChunk, ProviderCreateInput, ProviderCreateResult, ProviderSandbox, ProviderSandboxStatus, ResolvedSandboxFile, SandboxProvider } from "../provider.js";
+import type { ExecOptions, ExecResult, MainProcessInfo, NormalizedCommand, SandboxNetworkPolicy } from "../types.js";
+/** Per-sandbox options, set as `spec.providerOptions.vercel`. */
+export interface VercelSandboxOptions {
+    /** Vercel Container Registry image, e.g. `"vercel/sandbox/universal"`. */
+    image?: string;
+    /** Legacy managed runtime, e.g. `"node24"`. Ignored when `image` is set. */
+    runtime?: string;
+    /** Region, e.g. `"iad1"`. */
+    region?: string;
+    /**
+     * Passed to `@vercel/sandbox` as-is, for what `spec.network` cannot express
+     * (per-domain request rules, header injection). Cannot be combined with `spec.network`.
+     */
+    networkPolicy?: unknown;
+    /** Up to 5 key/value tags. */
+    tags?: Record<string, string>;
+}
+declare module "../types.js" {
+    interface SandboxProviderOptions {
+        vercel?: VercelSandboxOptions;
+    }
+}
+export interface VercelCredentials {
+    token: string;
+    teamId: string;
+    projectId: string;
+}
+export interface VercelRunCommandParams {
+    cmd: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    detached?: boolean;
+    stdout?: Writable;
+    stderr?: Writable;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+/** The subset of a `@vercel/sandbox` `Sandbox` instance this provider uses. */
+export interface VercelSandboxInstance {
+    readonly name: string;
+    /** Status of the current session: `pending`, `running`, `stopping`, `stopped`, ... */
+    readonly status: string;
+    runCommand(params: VercelRunCommandParams): Promise<{
+        exitCode: number | null;
+    }>;
+    writeFiles(files: {
+        path: string;
+        content: Uint8Array;
+        mode?: number;
+    }[]): Promise<void>;
+    readFileToBuffer(file: {
+        path: string;
+    }): Promise<Uint8Array | null>;
+    domain(port: number): string;
+    stop(): Promise<unknown>;
+    delete(): Promise<unknown>;
+    extendTimeout(durationMs: number): Promise<void>;
+}
+/** The subset of the `@vercel/sandbox` `Sandbox` class this provider uses. */
+export interface VercelSandboxApi {
+    create(params: Record<string, unknown>): Promise<VercelSandboxInstance>;
+    get(params: {
+        name: string;
+        resume?: boolean;
+    } & Record<string, unknown>): Promise<VercelSandboxInstance>;
+}
+export interface VercelSandboxProviderOptions {
+    /** Provider name used in sandbox records. Default `"vercel"`. */
+    name?: string;
+    /** Access-token credentials. Omit to use Vercel OIDC (`VERCEL_OIDC_TOKEN`). */
+    credentials?: VercelCredentials;
+    /** Sandbox API; defaults to `Sandbox` from `@vercel/sandbox`. Inject a fake in tests. */
+    api?: VercelSandboxApi;
+    /** Image used when the spec sets neither `image` nor `runtime`. */
+    defaultImage?: string;
+    defaultRegion?: string;
+}
+export declare const VERCEL_DEFAULT_WORKDIR = "/vercel/sandbox";
+/**
+ * Runs each sandbox as a persistent Vercel Sandbox: `stop` snapshots the
+ * filesystem and `wake` restores it. `spec.timeoutMs` maps to the native
+ * sandbox timeout (Vercel stops the sandbox itself when it expires).
+ */
+export declare class VercelSandboxProvider implements SandboxProvider {
+    readonly name: string;
+    readonly defaultWorkdir = "/vercel/sandbox";
+    readonly networkPolicies: readonly ["deny-all", "allowlist"];
+    private readonly credentials;
+    private readonly defaultImage;
+    private readonly defaultRegion;
+    private apiPromise;
+    constructor(options?: VercelSandboxProviderOptions);
+    create(input: ProviderCreateInput): Promise<ProviderCreateResult>;
+    wake(sandbox: ProviderSandbox): Promise<void>;
+    stop(sandbox: ProviderSandbox): Promise<void>;
+    destroy(sandbox: ProviderSandbox): Promise<void>;
+    status(sandbox: ProviderSandbox): Promise<ProviderSandboxStatus>;
+    exec(sandbox: ProviderSandbox, command: NormalizedCommand, options?: ExecOptions): Promise<ExecResult>;
+    startMainProcess(sandbox: ProviderSandbox, command: NormalizedCommand): Promise<void>;
+    getMainProcess(sandbox: ProviderSandbox): Promise<MainProcessInfo | null>;
+    readMainLog(sandbox: ProviderSandbox, offset: number): Promise<MainLogChunk>;
+    writeFiles(sandbox: ProviderSandbox, files: ResolvedSandboxFile[]): Promise<void>;
+    readFile(sandbox: ProviderSandbox, path: string): Promise<Uint8Array | null>;
+    getUrl(sandbox: ProviderSandbox, port: number): Promise<string>;
+    extendTimeout(sandbox: ProviderSandbox, durationMs: number): Promise<void>;
+    private run;
+    private connect;
+    /** Connects without resuming, so a sandbox Vercel stopped (e.g. on timeout) is reported, not silently resumed. */
+    private connectRunning;
+    private api;
+}
+/** The `@vercel/sandbox` `NetworkPolicy` shapes `spec.network` maps onto. */
+type VercelNetworkPolicy = "allow-all" | "deny-all" | {
+    allow: string[];
+    subnets?: {
+        allow?: string[];
+        deny?: string[];
+    };
+};
+/** Maps `spec.network` onto a `@vercel/sandbox` network policy. */
+export declare function toVercelNetworkPolicy(policy: SandboxNetworkPolicy): VercelNetworkPolicy;
+export {};

package/dist/vercel/provider.js

@@ -0,0 +1,190 @@
+import { posix } from "node:path";
+import { ProviderSandboxMissingError, ProviderSandboxStoppedError, SandboxError } from "../errors.js";
+import { outputCollector } from "../internal/output.js";
+import { normalizeCidr } from "../network.js";
+import { shellGetMainProcess, shellReadMainLog, shellStartMainProcess } from "../shell-main-process.js";
+export const VERCEL_DEFAULT_WORKDIR = "/vercel/sandbox";
+const RUNNING_STATUSES = new Set(["pending", "running"]);
+/**
+ * Runs each sandbox as a persistent Vercel Sandbox: `stop` snapshots the
+ * filesystem and `wake` restores it. `spec.timeoutMs` maps to the native
+ * sandbox timeout (Vercel stops the sandbox itself when it expires).
+ */
+export class VercelSandboxProvider {
+    name;
+    defaultWorkdir = VERCEL_DEFAULT_WORKDIR;
+    networkPolicies = ["deny-all", "allowlist"];
+    credentials;
+    defaultImage;
+    defaultRegion;
+    apiPromise;
+    constructor(options = {}) {
+        this.name = options.name ?? "vercel";
+        this.credentials = options.credentials ?? {};
+        this.defaultImage = options.defaultImage;
+        this.defaultRegion = options.defaultRegion;
+        if (options.api)
+            this.apiPromise = Promise.resolve(options.api);
+    }
+    async create(input) {
+        const options = input.spec.providerOptions?.vercel ?? {};
+        if (input.spec.network !== undefined && options.networkPolicy !== undefined) {
+            throw new SandboxError("Set spec.network or spec.providerOptions.vercel.networkPolicy, not both");
+        }
+        const image = options.image ?? (options.runtime ? undefined : this.defaultImage);
+        const api = await this.api();
+        const sandbox = await api.create({
+            ...this.credentials,
+            name: input.id,
+            persistent: true,
+            ...(image ? { image } : options.runtime ? { runtime: options.runtime } : {}),
+            ports: input.spec.ports,
+            timeout: input.spec.timeoutMs,
+            resources: input.spec.resources?.vcpus ? { vcpus: input.spec.resources.vcpus } : undefined,
+            env: input.spec.env,
+            tags: options.tags,
+            region: options.region ?? this.defaultRegion,
+            networkPolicy: input.spec.network === undefined ? options.networkPolicy : toVercelNetworkPolicy(input.spec.network),
+        });
+        if (input.workdir !== VERCEL_DEFAULT_WORKDIR) {
+            const result = await sandbox.runCommand({ cmd: "mkdir", args: ["-p", input.workdir] });
+            if (result.exitCode !== 0) {
+                await sandbox.delete().catch(() => undefined);
+                throw new SandboxError(`Failed to create workdir ${input.workdir}`);
+            }
+        }
+        return { providerRef: sandbox.name };
+    }
+    async wake(sandbox) {
+        await this.connect(sandbox, { resume: true });
+    }
+    async stop(sandbox) {
+        const instance = await this.connect(sandbox);
+        if (RUNNING_STATUSES.has(instance.status))
+            await instance.stop();
+    }
+    async destroy(sandbox) {
+        try {
+            await (await this.connect(sandbox)).delete();
+        }
+        catch (error) {
+            if (!(error instanceof ProviderSandboxMissingError) && !isNotFound(error))
+                throw error;
+        }
+    }
+    async status(sandbox) {
+        try {
+            const instance = await this.connect(sandbox);
+            return RUNNING_STATUSES.has(instance.status) ? "running" : "stopped";
+        }
+        catch (error) {
+            if (error instanceof ProviderSandboxMissingError)
+                return "missing";
+            throw error;
+        }
+    }
+    async exec(sandbox, command, options = {}) {
+        const instance = await this.connectRunning(sandbox);
+        return this.run(instance, command, options);
+    }
+    async startMainProcess(sandbox, command) {
+        const instance = await this.connectRunning(sandbox);
+        await shellStartMainProcess((cmd) => this.run(instance, cmd), async (launcher) => {
+            await instance.runCommand({ cmd: launcher.cmd, args: launcher.args, cwd: launcher.cwd, detached: true });
+        }, command);
+    }
+    async getMainProcess(sandbox) {
+        const instance = await this.connectRunning(sandbox);
+        return shellGetMainProcess((cmd) => this.run(instance, cmd));
+    }
+    async readMainLog(sandbox, offset) {
+        const instance = await this.connectRunning(sandbox);
+        return shellReadMainLog((cmd) => this.run(instance, cmd), offset);
+    }
+    async writeFiles(sandbox, files) {
+        const instance = await this.connectRunning(sandbox);
+        const dirs = [...new Set(files.map((file) => posix.dirname(file.path)))];
+        const mkdir = await instance.runCommand({ cmd: "mkdir", args: ["-p", ...dirs] });
+        if (mkdir.exitCode !== 0)
+            throw new SandboxError(`Failed to create directories ${dirs.join(", ")}`);
+        await instance.writeFiles(files.map((file) => ({ path: file.path, content: file.content, mode: file.mode })));
+    }
+    async readFile(sandbox, path) {
+        const instance = await this.connectRunning(sandbox);
+        const buffer = await instance.readFileToBuffer({ path });
+        return buffer === null ? null : new Uint8Array(buffer);
+    }
+    async getUrl(sandbox, port) {
+        const instance = await this.connectRunning(sandbox);
+        return instance.domain(port);
+    }
+    async extendTimeout(sandbox, durationMs) {
+        const instance = await this.connectRunning(sandbox);
+        await instance.extendTimeout(durationMs);
+    }
+    async run(instance, command, options = {}) {
+        const stdout = outputCollector(options.onStdout);
+        const stderr = outputCollector(options.onStderr);
+        const result = await instance.runCommand({
+            cmd: command.cmd,
+            args: command.args,
+            cwd: command.cwd,
+            env: command.env,
+            stdout: stdout.writable,
+            stderr: stderr.writable,
+            signal: options.signal,
+            timeoutMs: options.timeoutMs,
+        });
+        return { exitCode: result.exitCode ?? -1, stdout: stdout.finish(), stderr: stderr.finish() };
+    }
+    async connect(sandbox, { resume = false } = {}) {
+        const api = await this.api();
+        try {
+            return await api.get({ ...this.credentials, name: sandbox.providerRef, resume });
+        }
+        catch (error) {
+            if (isNotFound(error))
+                throw new ProviderSandboxMissingError(sandbox.providerRef);
+            throw error;
+        }
+    }
+    /** Connects without resuming, so a sandbox Vercel stopped (e.g. on timeout) is reported, not silently resumed. */
+    async connectRunning(sandbox) {
+        const instance = await this.connect(sandbox);
+        if (!RUNNING_STATUSES.has(instance.status))
+            throw new ProviderSandboxStoppedError(sandbox.providerRef);
+        return instance;
+    }
+    api() {
+        this.apiPromise ??= import("@vercel/sandbox").then(({ Sandbox }) => ({
+            create: (params) => Sandbox.create(params),
+            get: (params) => Sandbox.get(params),
+        }));
+        return this.apiPromise;
+    }
+}
+/** Maps `spec.network` onto a `@vercel/sandbox` network policy. */
+export function toVercelNetworkPolicy(policy) {
+    if (typeof policy === "string")
+        return policy;
+    const allow = policy.allowDomains ?? [];
+    const allowCidrs = (policy.allowCidrs ?? []).map(normalizeCidr);
+    const denyCidrs = (policy.denyCidrs ?? []).map(normalizeCidr);
+    if (allow.length === 0 && allowCidrs.length === 0)
+        return "deny-all";
+    if (allowCidrs.length === 0 && denyCidrs.length === 0)
+        return { allow };
+    return {
+        allow,
+        subnets: {
+            ...(allowCidrs.length > 0 && { allow: allowCidrs }),
+            ...(denyCidrs.length > 0 && { deny: denyCidrs }),
+        },
+    };
+}
+function isNotFound(error) {
+    if (typeof error !== "object" || error === null)
+        return false;
+    const response = error.response;
+    return response?.status === 404;
+}

package/dist/web-storage/index.d.ts

@@ -0,0 +1,2 @@
+export { DEFAULT_WEB_STORAGE_PREFIX, WebStorageSandboxStore } from "./store.js";
+export type { WebStorageLike, WebStorageSandboxStoreOptions } from "./store.js";

package/dist/web-storage/index.js

@@ -0,0 +1 @@
+export { DEFAULT_WEB_STORAGE_PREFIX, WebStorageSandboxStore } from "./store.js";

package/dist/web-storage/store.d.ts

@@ -0,0 +1,53 @@
+import type { SandboxListFilter, SandboxRecordPatch, SandboxStore } from "../store.js";
+import type { SandboxRecord } from "../types.js";
+/**
+ * The part of the Web Storage API the store uses. `localStorage` and
+ * `sessionStorage` implement it, and so does any object with these members.
+ */
+export interface WebStorageLike {
+    readonly length: number;
+    key(index: number): string | null;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface WebStorageSandboxStoreOptions {
+    /**
+     * Where records are kept. Default: `globalThis.localStorage`. Pass
+     * `sessionStorage` to keep them for the life of the browser tab.
+     */
+    storage?: WebStorageLike;
+    /**
+     * Prefix of every key the store writes; each record is one entry under
+     * `prefix + id`. Give stores that share a storage different prefixes.
+     * Default: `"sandbox-sdk:sandboxes:"`.
+     */
+    prefix?: string;
+}
+export declare const DEFAULT_WEB_STORAGE_PREFIX = "sandbox-sdk:sandboxes:";
+/**
+ * `SandboxStore` backed by the Web Storage API (`localStorage` or
+ * `sessionStorage`), for running the SDK in a browser with no database.
+ *
+ * Every method reads and writes storage synchronously, so `update` is an
+ * atomic compare-and-set within one JavaScript context. Browsers do not make
+ * that guarantee across tabs that share a `localStorage`; give each tab its
+ * own `prefix` or `ownerId`, or use `sessionStorage`, if they write the same
+ * records. Storage quotas are small (around 5 MB per origin), and a write
+ * past the quota throws the browser's `QuotaExceededError`.
+ */
+export declare class WebStorageSandboxStore implements SandboxStore {
+    private readonly storage;
+    private readonly prefix;
+    constructor(options?: WebStorageSandboxStoreOptions);
+    insert(record: SandboxRecord): Promise<void>;
+    get(id: string): Promise<SandboxRecord | null>;
+    list(filter?: SandboxListFilter): Promise<SandboxRecord[]>;
+    update(id: string, expectedVersion: number, patch: SandboxRecordPatch): Promise<SandboxRecord | null>;
+    delete(id: string): Promise<boolean>;
+    /** Every key under the prefix, collected first so writes cannot shift the indexes. */
+    private keys;
+    private write;
+    /** `null` if the entry is missing or is not a sandbox record. */
+    private read;
+}

package/dist/web-storage/store.js

@@ -0,0 +1,118 @@
+import { SandboxError } from "../errors.js";
+import { matchesFilter } from "../store.js";
+export const DEFAULT_WEB_STORAGE_PREFIX = "sandbox-sdk:sandboxes:";
+/**
+ * `SandboxStore` backed by the Web Storage API (`localStorage` or
+ * `sessionStorage`), for running the SDK in a browser with no database.
+ *
+ * Every method reads and writes storage synchronously, so `update` is an
+ * atomic compare-and-set within one JavaScript context. Browsers do not make
+ * that guarantee across tabs that share a `localStorage`; give each tab its
+ * own `prefix` or `ownerId`, or use `sessionStorage`, if they write the same
+ * records. Storage quotas are small (around 5 MB per origin), and a write
+ * past the quota throws the browser's `QuotaExceededError`.
+ */
+export class WebStorageSandboxStore {
+    storage;
+    prefix;
+    constructor(options = {}) {
+        const storage = options.storage ?? globalThis.localStorage;
+        if (!storage) {
+            throw new SandboxError("No Web Storage is available here; pass `storage` (e.g. sessionStorage)");
+        }
+        this.storage = storage;
+        this.prefix = options.prefix ?? DEFAULT_WEB_STORAGE_PREFIX;
+    }
+    async insert(record) {
+        const key = this.prefix + record.id;
+        if (this.storage.getItem(key) !== null) {
+            throw new SandboxError(`Sandbox record "${record.id}" already exists`);
+        }
+        this.write(record);
+    }
+    async get(id) {
+        return this.read(this.prefix + id);
+    }
+    async list(filter = {}) {
+        const records = [];
+        for (const key of this.keys()) {
+            const record = this.read(key);
+            if (record && matchesFilter(record, filter))
+                records.push(record);
+        }
+        records.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime() || (a.id < b.id ? 1 : a.id > b.id ? -1 : 0));
+        const offset = filter.offset ?? 0;
+        const end = filter.limit === undefined ? undefined : offset + filter.limit;
+        return records.slice(offset, end);
+    }
+    async update(id, expectedVersion, patch) {
+        // No await between the read and the write: nothing else in this
+        // JavaScript context can write the record in between.
+        const current = this.read(this.prefix + id);
+        if (!current || current.version !== expectedVersion)
+            return null;
+        const defined = Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== undefined));
+        const next = {
+            ...current,
+            ...structuredClone(defined),
+            version: current.version + 1,
+            updatedAt: new Date(),
+        };
+        this.write(next);
+        return next;
+    }
+    async delete(id) {
+        const key = this.prefix + id;
+        if (this.storage.getItem(key) === null)
+            return false;
+        this.storage.removeItem(key);
+        return true;
+    }
+    /** Every key under the prefix, collected first so writes cannot shift the indexes. */
+    keys() {
+        const keys = [];
+        for (let i = 0; i < this.storage.length; i += 1) {
+            const key = this.storage.key(i);
+            if (key !== null && key.startsWith(this.prefix))
+                keys.push(key);
+        }
+        return keys;
+    }
+    write(record) {
+        this.storage.setItem(this.prefix + record.id, JSON.stringify(record));
+    }
+    /** `null` if the entry is missing or is not a sandbox record. */
+    read(key) {
+        const raw = this.storage.getItem(key);
+        if (raw === null)
+            return null;
+        let stored;
+        try {
+            stored = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        if (!isStoredRecord(stored))
+            return null;
+        return {
+            ...stored,
+            createdAt: new Date(stored.createdAt),
+            updatedAt: new Date(stored.updatedAt),
+            expiresAt: stored.expiresAt === null ? null : new Date(stored.expiresAt),
+        };
+    }
+}
+function isStoredRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return (typeof record.id === "string" &&
+        typeof record.provider === "string" &&
+        typeof record.status === "string" &&
+        typeof record.version === "number" &&
+        typeof record.createdAt === "string" &&
+        typeof record.updatedAt === "string" &&
+        typeof record.spec === "object" &&
+        record.spec !== null);
+}