beachside 0.0.0 → 0.9.0

package/dist/resources.d.ts

@@ -0,0 +1,361 @@
+import { z } from "zod";
+import { ResourceReference, MountSpec, SnapshotInfo, ImageInfo, VolumeInfo, RestoreRequest, VolumeCreateInput, type ArtifactDeletionResult, type OperationKind, type SnapshotCaptureValue } from "@beachside/adapter";
+import { type NetworkPolicy, type ReadOptions, type SandboxHandle, type SnapshotHandle, type ImageHandle, type PreparedImage, type VolumeHandle, type OperationHandle } from "./resource.js";
+import { AdapterSandbox, type AdapterDirectClient, type AdapterRecoveryReference } from "./adapter-direct.js";
+/** SDK restore input; native RestoreRequest remains fully resolved. */
+export type RestoreInput = Omit<RestoreRequest, "networkPolicy" | "lifetimeSeconds"> & {
+    /** Outbound network policy; omitted uses the adapter setup default. */
+    network?: NetworkPolicy;
+    /**
+     * Lifetime for the restored sandbox only, replacing the adapter setup's. Like `env` and
+     * `labels`, it rejects before any effect where the adapter cannot apply it on restore.
+     */
+    lifecycle?: {
+        lifetimeSeconds?: number;
+    };
+    /** @deprecated Use `network`. */
+    networkPolicy?: string;
+};
+export type WaitOptions = ReadOptions & {
+    pollMs?: number;
+};
+export type SnapshotResult = Omit<SnapshotCaptureValue, "snapshot"> & {
+    snapshot: SnapshotHandle;
+};
+export declare function checkedResource(client: AdapterDirectClient, ref: ResourceReference, kind: "snapshot" | "volume" | "image"): ResourceReference;
+/** Use the SnapshotHandle type for consumer annotations. This compatibility runtime class remains supported. */
+export declare class AdapterSnapshot {
+    private readonly client;
+    readonly reference: ResourceReference;
+    constructor(client: AdapterDirectClient, reference: ResourceReference);
+    get provider(): string;
+    /** Native containing-resource ID; persist the full reference for immutable build selection. */
+    get id(): string;
+    inspect(options?: WaitOptions): Promise<SnapshotInfo>;
+    /** Restore private captured state with explicitly selected current volume data. */
+    submitRestore(request?: RestoreInput, options?: WaitOptions): Promise<OperationHandle<SandboxHandle<true>, OperationKind>>;
+    /** Restore requires no recorded native mounts and confirmed mountHandling: "none". */
+    restore(input?: RestoreInput, options?: WaitOptions): Promise<SandboxHandle<true>>;
+    submitDelete(options?: WaitOptions): Promise<OperationHandle<ArtifactDeletionResult, OperationKind>>;
+    delete(options?: WaitOptions): Promise<ArtifactDeletionResult>;
+}
+/** Use the ImageHandle type for consumer annotations. */
+export declare class AdapterImage {
+    private readonly client;
+    readonly reference: ResourceReference;
+    constructor(client: AdapterDirectClient, reference: ResourceReference);
+    get provider(): string;
+    /** Native image ID; the value `Image.prepared()` selects. */
+    get id(): string;
+    /** The scoped prepared image for `Image.prepared()`. */
+    get prepared(): PreparedImage;
+    inspect(options?: WaitOptions): Promise<ImageInfo>;
+    /** Delete this image on the provider. Sandboxes and other artifacts are never deleted with it. */
+    submitDelete(options?: WaitOptions): Promise<OperationHandle<ArtifactDeletionResult, OperationKind>>;
+    delete(options?: WaitOptions): Promise<ArtifactDeletionResult>;
+}
+/** Use the VolumeHandle type for consumer annotations. This compatibility runtime class remains supported. */
+export declare class AdapterVolume {
+    private readonly client;
+    readonly reference: ResourceReference;
+    constructor(client: AdapterDirectClient, reference: ResourceReference);
+    get provider(): string;
+    get id(): string;
+    inspect(options?: WaitOptions): Promise<VolumeInfo>;
+    at(path: string, options?: {
+        access?: "read-write" | "read-only";
+        subpath?: string;
+    }): MountSpec;
+    submitDelete(options?: WaitOptions): Promise<OperationHandle<ArtifactDeletionResult, OperationKind>>;
+    delete(options?: WaitOptions): Promise<ArtifactDeletionResult>;
+}
+export declare function resourceManagers(client: AdapterDirectClient): {
+    snapshots: {
+        get(ref: ResourceReference): Promise<SnapshotHandle>;
+        list(input?: SandboxListInput): Promise<{
+            items: {
+                reference: {
+                    version: 1;
+                    kind: "volume" | "snapshot" | "sandbox" | "image" | "volume-version" | "mount" | "session";
+                    provider: string;
+                    scope: {
+                        authority: {
+                            kind: string;
+                            id: string;
+                        };
+                        partition: Record<string, string>;
+                    };
+                    nativeId: string;
+                    ownership: "unknown" | "borrowed" | "verified-created";
+                    generation?: string | undefined;
+                    history?: z.core.util.JSONType | undefined;
+                    receipt?: string | undefined;
+                };
+                preserve: "filesystem" | "filesystem+memory" | null;
+                restoreExecution: "resume" | "fresh" | null;
+                consistency: "unknown" | "crash-consistent" | "caller-quiesced";
+                source: {
+                    id: string;
+                    class: string;
+                } | null;
+                state: "unknown" | "creating" | "ready" | "deleting";
+                createdAt: string | null;
+                expiration: "unknown";
+                excludedPaths: string[] | null;
+                mounts: {
+                    volume: {
+                        version: 1;
+                        kind: "volume" | "snapshot" | "sandbox" | "image" | "volume-version" | "mount" | "session";
+                        provider: string;
+                        scope: {
+                            authority: {
+                                kind: string;
+                                id: string;
+                            };
+                            partition: Record<string, string>;
+                        };
+                        nativeId: string;
+                        ownership: "unknown" | "borrowed" | "verified-created";
+                        generation?: string | undefined;
+                        history?: z.core.util.JSONType | undefined;
+                        receipt?: string | undefined;
+                    };
+                    path: string;
+                    access: "read-write" | "read-only";
+                    subpath?: string | undefined;
+                }[];
+                mountHandling: "unknown" | "none" | "excluded";
+                restore: {
+                    networkPolicies: string[];
+                    resources: boolean;
+                    mounts: boolean;
+                    independentLifecycle: boolean;
+                };
+                dependencies: {
+                    version: 1;
+                    kind: "volume" | "snapshot" | "sandbox" | "image" | "volume-version" | "mount" | "session";
+                    provider: string;
+                    scope: {
+                        authority: {
+                            kind: string;
+                            id: string;
+                        };
+                        partition: Record<string, string>;
+                    };
+                    nativeId: string;
+                    ownership: "unknown" | "borrowed" | "verified-created";
+                    generation?: string | undefined;
+                    history?: z.core.util.JSONType | undefined;
+                    receipt?: string | undefined;
+                }[];
+                nativeDependencies: {
+                    kind: string;
+                    id: string;
+                }[] | null;
+            }[];
+            coverage: "provider-scope" | "managed";
+            nextCursor?: string | undefined;
+        }>;
+        delete(ref: ResourceReference, options?: WaitOptions): Promise<{
+            deleted: true;
+            reference: {
+                version: 1;
+                kind: "volume" | "snapshot" | "sandbox" | "image" | "volume-version" | "mount" | "session";
+                provider: string;
+                scope: {
+                    authority: {
+                        kind: string;
+                        id: string;
+                    };
+                    partition: Record<string, string>;
+                };
+                nativeId: string;
+                ownership: "unknown" | "borrowed" | "verified-created";
+                generation?: string | undefined;
+                history?: z.core.util.JSONType | undefined;
+                receipt?: string | undefined;
+            };
+        }>;
+    };
+    volumes: {
+        get(ref: ResourceReference): Promise<VolumeHandle>;
+        submitCreate(input: VolumeCreateInput, options?: WaitOptions): Promise<OperationHandle<VolumeHandle, OperationKind>>;
+        create(input: VolumeCreateInput, options?: WaitOptions): Promise<VolumeHandle>;
+        list(input?: SandboxListInput): Promise<{
+            items: {
+                reference: {
+                    version: 1;
+                    kind: "volume" | "snapshot" | "sandbox" | "image" | "volume-version" | "mount" | "session";
+                    provider: string;
+                    scope: {
+                        authority: {
+                            kind: string;
+                            id: string;
+                        };
+                        partition: Record<string, string>;
+                    };
+                    nativeId: string;
+                    ownership: "unknown" | "borrowed" | "verified-created";
+                    generation?: string | undefined;
+                    history?: z.core.util.JSONType | undefined;
+                    receipt?: string | undefined;
+                };
+                name: string;
+                state: "unknown" | "creating" | "ready" | "deleting";
+                filesystem: "object-backed" | "block-backed";
+                visibility: "unknown" | "immediate";
+                durability: "unknown";
+                locking: "unknown";
+                rename: "unknown";
+                conflicts: "unknown" | "last-writer-wins";
+            }[];
+            coverage: "provider-scope" | "managed";
+            nextCursor?: string | undefined;
+        }>;
+        delete(ref: ResourceReference, options?: WaitOptions): Promise<{
+            deleted: true;
+            reference: {
+                version: 1;
+                kind: "volume" | "snapshot" | "sandbox" | "image" | "volume-version" | "mount" | "session";
+                provider: string;
+                scope: {
+                    authority: {
+                        kind: string;
+                        id: string;
+                    };
+                    partition: Record<string, string>;
+                };
+                nativeId: string;
+                ownership: "unknown" | "borrowed" | "verified-created";
+                generation?: string | undefined;
+                history?: z.core.util.JSONType | undefined;
+                receipt?: string | undefined;
+            };
+        }>;
+    };
+    images: {
+        /** Inspect a saved image reference and return a handle bound to this connection. */
+        get(ref: ResourceReference): Promise<ImageHandle>;
+        list(input?: SandboxListInput): Promise<{
+            items: {
+                reference: {
+                    version: 1;
+                    kind: "volume" | "snapshot" | "sandbox" | "image" | "volume-version" | "mount" | "session";
+                    provider: string;
+                    scope: {
+                        authority: {
+                            kind: string;
+                            id: string;
+                        };
+                        partition: Record<string, string>;
+                    };
+                    nativeId: string;
+                    ownership: "unknown" | "borrowed" | "verified-created";
+                    generation?: string | undefined;
+                    history?: z.core.util.JSONType | undefined;
+                    receipt?: string | undefined;
+                };
+                state: "unknown" | "creating" | "ready" | "deleting";
+                createdAt: string | null;
+                source: {
+                    kind: "oci";
+                    value: string;
+                } | null;
+                visibility: "unknown" | "private" | "public";
+                nativeDependencies: {
+                    kind: string;
+                    id: string;
+                }[] | null;
+            }[];
+            coverage: "provider-scope" | "managed";
+            nextCursor?: string | undefined;
+        }>;
+        submitDelete(ref: ResourceReference, options?: WaitOptions): Promise<import("./adapter-direct.js").AdapterOperation<{
+            deleted: true;
+            reference: {
+                version: 1;
+                kind: "volume" | "snapshot" | "sandbox" | "image" | "volume-version" | "mount" | "session";
+                provider: string;
+                scope: {
+                    authority: {
+                        kind: string;
+                        id: string;
+                    };
+                    partition: Record<string, string>;
+                };
+                nativeId: string;
+                ownership: "unknown" | "borrowed" | "verified-created";
+                generation?: string | undefined;
+                history?: z.core.util.JSONType | undefined;
+                receipt?: string | undefined;
+            };
+        }, OperationKind>>;
+        delete(ref: ResourceReference, options?: WaitOptions): Promise<{
+            deleted: true;
+            reference: {
+                version: 1;
+                kind: "volume" | "snapshot" | "sandbox" | "image" | "volume-version" | "mount" | "session";
+                provider: string;
+                scope: {
+                    authority: {
+                        kind: string;
+                        id: string;
+                    };
+                    partition: Record<string, string>;
+                };
+                nativeId: string;
+                ownership: "unknown" | "borrowed" | "verified-created";
+                generation?: string | undefined;
+                history?: z.core.util.JSONType | undefined;
+                receipt?: string | undefined;
+            };
+        }>;
+    };
+};
+/** Page size used by `list()` calls when `limit` is omitted. */
+export declare const DEFAULT_SANDBOX_LIST_LIMIT = 50;
+/** Optional page selection for `list()` calls; `limit` is 1-100 and defaults to 50. */
+export type SandboxListInput = {
+    cursor?: string;
+    limit?: number;
+};
+/**
+ * One listed sandbox; `reference` is null when the adapter cannot verify a reopenable identity.
+ * `labels` holds the labels set at create (null when the provider records none) and `createdAt`
+ * the provider's creation time (null when it reports none).
+ */
+export type SandboxListEntry = {
+    id: string;
+    state: import("@beachside/adapter").SandboxState;
+    reference: import("@beachside/adapter").SandboxReference | null;
+    labels: Record<string, string> | null;
+    createdAt: string | null;
+};
+/** A bounded page of sandboxes and whether it covers the provider scope or only Beachside-created ones. */
+export type SandboxList = {
+    items: SandboxListEntry[];
+    nextCursor?: string;
+    coverage: "provider-scope" | "managed";
+};
+export declare function listSandboxes(client: AdapterDirectClient, input?: SandboxListInput): Promise<SandboxList>;
+export declare function decodeCapture(client: AdapterDirectClient, value: SnapshotCaptureValue, ref: AdapterRecoveryReference): SnapshotResult;
+export declare function decodeResourceResult(client: AdapterDirectClient, result: import("@beachside/adapter").RuntimeResult, ref: AdapterRecoveryReference): SnapshotResult | AdapterSandbox | {
+    deleted: true;
+    reference: {
+        version: 1;
+        kind: "volume" | "snapshot" | "sandbox" | "image" | "volume-version" | "mount" | "session";
+        provider: string;
+        scope: {
+            authority: {
+                kind: string;
+                id: string;
+            };
+            partition: Record<string, string>;
+        };
+        nativeId: string;
+        ownership: "unknown" | "borrowed" | "verified-created";
+        generation?: string | undefined;
+        history?: z.core.util.JSONType | undefined;
+        receipt?: string | undefined;
+    };
+} | AdapterVolume;

package/dist/scoped-sandbox.d.ts

@@ -0,0 +1,30 @@
+import { BeachsideError, type CreateInput, type SandboxHandle, type OperationHandle, type RecoveryReference } from "./resource.js";
+import type { DestroyValue, SandboxReference, OperationKind } from "@beachside/adapter";
+import type { AdapterDirectClient } from "./adapter-direct.js";
+/** Work cancellation does not cancel the separate cleanup budget. */
+export interface SandboxScopeOptions {
+    signal?: AbortSignal;
+    /** Milliseconds to submit and observe destruction. Defaults to 30,000; maximum 300,000. */
+    cleanupTimeoutMs?: number;
+    /** Overrides the connection's storage cleanup policy; never deletes retained storage. */
+    storage?: "require-durable" | "allow-unconfirmed";
+}
+export type SandboxScopeCallbackOutcome<T> = {
+    status: "completed";
+    value: T;
+} | {
+    status: "failed";
+    error: unknown;
+};
+/** Destruction failed or was not confirmed; neither work nor cleanup is replayed. */
+export declare class SandboxCleanupError<T = unknown> extends BeachsideError {
+    readonly sandbox: SandboxHandle<true>;
+    readonly callbackOutcome: SandboxScopeCallbackOutcome<T>;
+    readonly cleanupError: unknown;
+    readonly cleanupOperation?: OperationHandle<DestroyValue, OperationKind> | undefined;
+    readonly sandboxId: string;
+    readonly sandboxReference: SandboxReference | null;
+    constructor(sandbox: SandboxHandle<true>, callbackOutcome: SandboxScopeCallbackOutcome<T>, cleanupError: unknown, cleanupOperation?: OperationHandle<DestroyValue, OperationKind> | undefined);
+    get cleanupReference(): RecoveryReference | undefined;
+}
+export declare function withSandbox<T>(client: AdapterDirectClient, input: CreateInput | undefined, callback: (sandbox: SandboxHandle<true>) => T | Promise<T>, options?: SandboxScopeOptions): Promise<T>;

package/package.json

@@ -1,16 +1,46 @@
 {
   "name": "beachside",
-  "version": "0.0.0",
-  "description": "Placeholder for beachside. Install a published Beachside release instead.",
+  "version": "0.9.0",
+  "private": false,
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "check": "tsc -p tsconfig.json",
+    "build": "rm -rf dist && bun build src/index.ts --target node --format esm --splitting --outdir dist --external @beachside/adapter --external zod --external @opentelemetry/api && tsc -p tsconfig.json --noEmit false --declaration --emitDeclarationOnly --outDir dist && bun ../../scripts/rewrite-declarations.mjs"
+  },
+  "dependencies": {
+    "@beachside/adapter": "0.9.0",
+    "zod": "4.6.5",
+    "@opentelemetry/api": "1.9.1"
+  },
+  "devDependencies": {
+    "@beachside-internal/provider-fake": "0.0.0",
+    "@beachside/daytona": "0.9.0",
+    "@beachside/e2b": "0.9.0"
+  },
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pandemicsyn/beachside.git",
     "directory": "packages/sdk"
   },
+  "description": "Provider-neutral SDK for direct sandbox access.",
   "homepage": "https://beachside.run/docs/direct-quickstart/",
-  "files": [
-    "README.md",
-    "LICENSE"
-  ]
+  "bugs": {
+    "url": "https://github.com/pandemicsyn/beachside/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts"
 }