@blaxel/core 0.3.26-preview.310 → 0.3.26-preview.312

package/dist/cjs-browser/common/settings.js

@@ -30,8 +30,8 @@ function missingCredentialsMessage() {
     return "No Blaxel credentials found. Set the BL_API_KEY and BL_WORKSPACE environment variables, or run `bl login`.";
 }
 // Build info - these placeholders are replaced at build time by build:replace-imports
-const BUILD_VERSION = "0.3.26-preview.310";
-const BUILD_COMMIT = "13bd8f75d15c2c81add546bcabeee2f20a224417";
+const BUILD_VERSION = "0.3.26-preview.312";
+const BUILD_COMMIT = "45891cd9862d690bb6532b5758e75084083d511f";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
 const BLAXEL_API_VERSION = "2026-09-22";
 // Bun < 1.3.11 never sends connection-level WINDOW_UPDATE: the pooled h2

package/dist/cjs-browser/sandbox/client/sdk.gen.js

@@ -294,7 +294,7 @@ const postFilesystemMultipartByUploadIdComplete = (options) => {
 exports.postFilesystemMultipartByUploadIdComplete = postFilesystemMultipartByUploadIdComplete;
 /**
  * Upload part
- * Upload a single part of a multipart upload
+ * Upload a single part of a multipart upload. Re-uploading a part number replaces that part. Wait for the previous request for that part to finish before retrying.
  */
 const putFilesystemMultipartByUploadIdPart = (options) => {
     return (options.client ?? client_gen_1.client).put({
@@ -354,7 +354,8 @@ const postFilesystemMultipartInitiateByPath = (options) => {
 exports.postFilesystemMultipartInitiateByPath = postFilesystemMultipartInitiateByPath;
 /**
  * Fuzzy search for files and directories
- * Performs fuzzy search on filesystem paths using fuzzy matching algorithm. Optimized alternative to find and grep commands.
+ * Ranks the files and directories under a path by how well their relative path fuzzy-matches `query` (fzf algorithm: the query's characters must appear in order, not necessarily next to each other), best match first.
+ * Fuzzy search is for "jump to file" lookups from a partial name. The `patterns` parameter is currently ignored by this endpoint; use find for exact glob filtering.
  */
 const getFilesystemSearchByPath = (options) => {
     return (options.client ?? client_gen_1.client).get({
@@ -405,7 +406,11 @@ const getFilesystemByPath = (options) => {
 exports.getFilesystemByPath = getFilesystemByPath;
 /**
  * Create or update a file or directory
- * Create or update a file or directory
+ * Create or update a file or directory.
+ *
+ * Idempotent: an existing file is overwritten (truncated, not appended to) and an existing directory is kept, so retrying the same request is safe.
+ *
+ * Send either a JSON body (FileRequest) or `multipart/form-data` for binary files. Multipart fields, in any order: `file` (required, the file content), `permissions` (optional octal mode such as `0755`, applied when the file is created, default `0644`; an existing file keeps its mode), `path` (optional, ignored: the target is always the URL path).
  */
 const putFilesystemByPath = (options) => {
     return (options.client ?? client_gen_1.client).put({
@@ -460,7 +465,7 @@ const getFilesystemTreeByPath = (options) => {
 exports.getFilesystemTreeByPath = getFilesystemTreeByPath;
 /**
  * Create or update directory tree
- * Create or update multiple files within a directory tree structure
+ * Create or update multiple files within a directory tree structure. Idempotent: existing files are overwritten, so retrying the same request is safe.
  */
 const putFilesystemTreeByPath = (options) => {
     return (options.client ?? client_gen_1.client).put({
@@ -609,7 +614,10 @@ const getProcess = (options) => {
 exports.getProcess = getProcess;
 /**
  * Execute a command
- * Execute a command and return process information. If Accept header is text/event-stream, streams logs in SSE format and returns the process response as a final event.
+ * Execute a command and return process information.
+ *
+ * Streaming: with `Accept: application/x-ndjson` (or `Accept: text/event-stream`, kept for compatibility) the response is NDJSON (`Content-Type: application/x-ndjson`), not SSE: one JSON object per line, `{"type": "...", "data": "..."}`.
+ * `type` is `stdout` or `stderr` (`data` is a raw output chunk, sent as soon as the process writes it, newlines included; if the process finished before any chunk was streamed, its output is sent instead as one event per line, without the newline), `keepalive` (every 5 seconds, no data), `error` (`data` is the message, ends the stream) or `result` (last event, `data` is the ProcessResponse as a JSON string).
  */
 const postProcess = (options) => {
     return (options.client ?? client_gen_1.client).post({
@@ -630,7 +638,7 @@ const postProcess = (options) => {
 exports.postProcess = postProcess;
 /**
  * Stop a process
- * Gracefully stop a running process
+ * Request graceful termination. Poll GET /process/{identifier} until terminal status confirms the managed process has exited.
  */
 const deleteProcessByIdentifier = (options) => {
     return (options.client ?? client_gen_1.client).delete({
@@ -664,7 +672,7 @@ const getProcessByIdentifier = (options) => {
 exports.getProcessByIdentifier = getProcessByIdentifier;
 /**
  * Kill a process
- * Forcefully kill a running process
+ * Request forceful termination. Poll GET /process/{identifier} until terminal status confirms the managed process has exited.
  */
 const deleteProcessByIdentifierKill = (options) => {
     return (options.client ?? client_gen_1.client).delete({
@@ -698,7 +706,8 @@ const getProcessByIdentifierLogs = (options) => {
 exports.getProcessByIdentifierLogs = getProcessByIdentifierLogs;
 /**
  * Stream process logs in real time
- * Streams the stdout and stderr output of a process in real time, one line per log, prefixed with 'stdout:' or 'stderr:'. Closes when the process exits or the client disconnects.
+ * Streams the stdout and stderr output of a process in real time: the output so far, then live output as the process writes it. Closes when the process exits or the client disconnects.
+ * Each output line starts with `stdout:` or `stderr:` and keeps its trailing newline. A partial line (e.g. a prompt) is sent as soon as it is written; when the process completes it, the rest follows without a new prefix. `[keepalive]` lines are sent every 30 seconds.
  */
 const getProcessByIdentifierLogsStream = (options) => {
     return (options.client ?? client_gen_1.client).get({

package/dist/cjs-browser/sandbox/filesystem/filesystem.js

@@ -266,7 +266,7 @@ class SandboxFileSystem extends action_js_1.SandboxAction {
     }
     async search(query, path = "/", options) {
         const formattedPath = this.formatPath(path);
-        const queryParams = {};
+        const queryParams = { query };
         if (options?.maxResults !== undefined) {
             queryParams.maxResults = options.maxResults;
         }

package/dist/cjs-browser/sandbox/preview.js

@@ -2,11 +2,48 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SandboxPreviews = exports.SandboxPreview = exports.SandboxPreviewTokens = exports.SandboxPreviewToken = void 0;
 const index_js_1 = require("../client/index.js");
+function isShorthand(preview) {
+    return !("metadata" in preview || "spec" in preview);
+}
+function normalizePreview(preview) {
+    if (!isShorthand(preview))
+        return preview;
+    if (!Number.isInteger(preview.port) || preview.port < 1 || preview.port > 65535) {
+        throw new RangeError("Preview port must be an integer between 1 and 65535");
+    }
+    if (preview.name !== undefined && (typeof preview.name !== "string" || preview.name.length === 0)) {
+        throw new RangeError("Preview name must be a nonempty string");
+    }
+    if (preview.public !== undefined && typeof preview.public !== "boolean") {
+        throw new RangeError("Preview public must be a boolean");
+    }
+    return {
+        metadata: { name: preview.name ?? `preview-${preview.port}` },
+        spec: { port: preview.port, public: preview.public ?? false },
+    };
+}
+// Explicit HTTP status takes precedence over a legacy numeric service code.
+function httpStatus(error) {
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    const fields = error;
+    const response = fields.response;
+    const responseStatus = typeof response === "object" && response !== null && "status" in response
+        ? response.status : undefined;
+    for (const status of [fields.status, fields.statusCode, responseStatus, fields.code]) {
+        if (typeof status === "number")
+            return status;
+    }
+    return undefined;
+}
 class SandboxPreviewToken {
     previewToken;
     constructor(previewToken) {
         this.previewToken = previewToken;
     }
+    get name() {
+        return this.previewToken.metadata?.name ?? "";
+    }
     get value() {
         return this.previewToken.spec.token ?? "";
     }
@@ -47,6 +84,49 @@ class SandboxPreviewTokens {
         });
         return new SandboxPreviewToken(data);
     }
+    /**
+     * Reuse the latest token within the requested expiry ceiling, or mint one.
+     * minValidity is in milliseconds. Concurrent callers may create separate tokens.
+     */
+    async createIfExpired(expiresAt, minValidity = 3_600_000) {
+        const now = Date.now();
+        if (!Number.isFinite(minValidity) || minValidity < 0) {
+            throw new RangeError("minValidity must be finite and non-negative");
+        }
+        const requestedExpiry = expiresAt ?? new Date(now + 86_400_000);
+        const ceiling = requestedExpiry instanceof Date ? requestedExpiry.getTime() : NaN;
+        if (!Number.isFinite(ceiling) || ceiling <= now || ceiling < now + minValidity) {
+            throw new RangeError("expiresAt must be a valid future date at least minValidity from now");
+        }
+        if (this.preview.spec?.public === true) {
+            throw new Error("Cannot create or reuse a token for a public preview");
+        }
+        const { data } = await (0, index_js_1.listSandboxPreviewTokens)({
+            path: {
+                sandboxName: this.resourceName,
+                previewName: this.previewName,
+            },
+            throwOnError: true,
+        });
+        if (!Array.isArray(data))
+            throw new Error("Failed to list preview tokens");
+        let selected;
+        let latestExpiry = -Infinity;
+        for (const token of data) {
+            const spec = token?.spec;
+            if (!spec || typeof spec.token !== "string" || spec.token.length === 0 || spec.expired === true ||
+                typeof spec.expiresAt !== "string")
+                continue;
+            const expiry = Date.parse(spec.expiresAt);
+            if (!Number.isFinite(expiry) || expiry <= now || expiry < now + minValidity || expiry > ceiling)
+                continue;
+            if (expiry > latestExpiry) {
+                selected = token;
+                latestExpiry = expiry;
+            }
+        }
+        return selected ? new SandboxPreviewToken(selected) : this.create(requestedExpiry);
+    }
     async list() {
         const { data } = await (0, index_js_1.listSandboxPreviewTokens)({
             path: {
@@ -80,6 +160,9 @@ class SandboxPreview {
     get name() {
         return this.preview.metadata.name;
     }
+    get url() {
+        return this.preview.spec?.url ?? "";
+    }
     get metadata() {
         return this.preview.metadata;
     }
@@ -106,6 +189,7 @@ class SandboxPreviews {
         return data.map((preview) => new SandboxPreview(preview));
     }
     async create(preview, force) {
+        const normalized = normalizePreview(preview);
         const query = {};
         if (force) {
             query['force'] = 'true';
@@ -115,12 +199,31 @@ class SandboxPreviews {
                 sandboxName: this.sandboxName,
             },
             query,
-            body: preview,
+            body: normalized,
             throwOnError: true,
         });
         return new SandboxPreview(data);
     }
+    /** Existing previews are returned as-is; shorthand's private default applies only on creation. */
     async createIfNotExists(preview, force) {
+        if (isShorthand(preview)) {
+            const normalized = normalizePreview(preview);
+            try {
+                return await this.get(normalized.metadata.name);
+            }
+            catch (error) {
+                if (httpStatus(error) !== 404)
+                    throw error;
+            }
+            try {
+                return await this.create(normalized, force);
+            }
+            catch (error) {
+                if (httpStatus(error) !== 409)
+                    throw error;
+                return this.get(normalized.metadata.name);
+            }
+        }
         try {
             const previewInstance = await this.get(preview.metadata.name);
             return previewInstance;

package/dist/cjs-browser/types/sandbox/client/sdk.gen.d.ts

@@ -119,7 +119,7 @@ export declare const deleteFilesystemMultipartByUploadIdAbort: <ThrowOnError ext
 export declare const postFilesystemMultipartByUploadIdComplete: <ThrowOnError extends boolean = false>(options: Options<PostFilesystemMultipartByUploadIdCompleteData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").SuccessResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
  * Upload part
- * Upload a single part of a multipart upload
+ * Upload a single part of a multipart upload. Re-uploading a part number replaces that part. Wait for the previous request for that part to finish before retrying.
  */
 export declare const putFilesystemMultipartByUploadIdPart: <ThrowOnError extends boolean = false>(options: Options<PutFilesystemMultipartByUploadIdPartData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").MultipartUploadPartResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
@@ -134,7 +134,8 @@ export declare const getFilesystemMultipartByUploadIdParts: <ThrowOnError extend
 export declare const postFilesystemMultipartInitiateByPath: <ThrowOnError extends boolean = false>(options: Options<PostFilesystemMultipartInitiateByPathData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").MultipartInitiateResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
  * Fuzzy search for files and directories
- * Performs fuzzy search on filesystem paths using fuzzy matching algorithm. Optimized alternative to find and grep commands.
+ * Ranks the files and directories under a path by how well their relative path fuzzy-matches `query` (fzf algorithm: the query's characters must appear in order, not necessarily next to each other), best match first.
+ * Fuzzy search is for "jump to file" lookups from a partial name. The `patterns` parameter is currently ignored by this endpoint; use find for exact glob filtering.
  */
 export declare const getFilesystemSearchByPath: <ThrowOnError extends boolean = false>(options: Options<GetFilesystemSearchByPathData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").FuzzySearchResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
@@ -149,7 +150,11 @@ export declare const deleteFilesystemByPath: <ThrowOnError extends boolean = fal
 export declare const getFilesystemByPath: <ThrowOnError extends boolean = false>(options: Options<GetFilesystemByPathData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").File | import("./types.gen").Directory | import("./types.gen").FileWithContent | Blob, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
  * Create or update a file or directory
- * Create or update a file or directory
+ * Create or update a file or directory.
+ *
+ * Idempotent: an existing file is overwritten (truncated, not appended to) and an existing directory is kept, so retrying the same request is safe.
+ *
+ * Send either a JSON body (FileRequest) or `multipart/form-data` for binary files. Multipart fields, in any order: `file` (required, the file content), `permissions` (optional octal mode such as `0755`, applied when the file is created, default `0644`; an existing file keeps its mode), `path` (optional, ignored: the target is always the URL path).
  */
 export declare const putFilesystemByPath: <ThrowOnError extends boolean = false>(options: Options<PutFilesystemByPathData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").SuccessResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
@@ -164,7 +169,7 @@ export declare const deleteFilesystemTreeByPath: <ThrowOnError extends boolean =
 export declare const getFilesystemTreeByPath: <ThrowOnError extends boolean = false>(options: Options<GetFilesystemTreeByPathData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").File | import("./types.gen").Directory | import("./types.gen").FileWithContent | Blob, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
  * Create or update directory tree
- * Create or update multiple files within a directory tree structure
+ * Create or update multiple files within a directory tree structure. Idempotent: existing files are overwritten, so retrying the same request is safe.
  */
 export declare const putFilesystemTreeByPath: <ThrowOnError extends boolean = false>(options: Options<PutFilesystemTreeByPathData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").File | import("./types.gen").Directory | import("./types.gen").FileWithContent | Blob, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
@@ -211,12 +216,15 @@ export declare const putNetworkTunnelConfig: <ThrowOnError extends boolean = fal
 export declare const getProcess: <ThrowOnError extends boolean = false>(options?: Options<GetProcessData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").ProcessResponse[], unknown, ThrowOnError>;
 /**
  * Execute a command
- * Execute a command and return process information. If Accept header is text/event-stream, streams logs in SSE format and returns the process response as a final event.
+ * Execute a command and return process information.
+ *
+ * Streaming: with `Accept: application/x-ndjson` (or `Accept: text/event-stream`, kept for compatibility) the response is NDJSON (`Content-Type: application/x-ndjson`), not SSE: one JSON object per line, `{"type": "...", "data": "..."}`.
+ * `type` is `stdout` or `stderr` (`data` is a raw output chunk, sent as soon as the process writes it, newlines included; if the process finished before any chunk was streamed, its output is sent instead as one event per line, without the newline), `keepalive` (every 5 seconds, no data), `error` (`data` is the message, ends the stream) or `result` (last event, `data` is the ProcessResponse as a JSON string).
  */
 export declare const postProcess: <ThrowOnError extends boolean = false>(options: Options<PostProcessData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").ProcessResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
  * Stop a process
- * Gracefully stop a running process
+ * Request graceful termination. Poll GET /process/{identifier} until terminal status confirms the managed process has exited.
  */
 export declare const deleteProcessByIdentifier: <ThrowOnError extends boolean = false>(options: Options<DeleteProcessByIdentifierData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").SuccessResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
@@ -226,7 +234,7 @@ export declare const deleteProcessByIdentifier: <ThrowOnError extends boolean =
 export declare const getProcessByIdentifier: <ThrowOnError extends boolean = false>(options: Options<GetProcessByIdentifierData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").ProcessResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
  * Kill a process
- * Forcefully kill a running process
+ * Request forceful termination. Poll GET /process/{identifier} until terminal status confirms the managed process has exited.
  */
 export declare const deleteProcessByIdentifierKill: <ThrowOnError extends boolean = false>(options: Options<DeleteProcessByIdentifierKillData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").SuccessResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
@@ -236,7 +244,8 @@ export declare const deleteProcessByIdentifierKill: <ThrowOnError extends boolea
 export declare const getProcessByIdentifierLogs: <ThrowOnError extends boolean = false>(options: Options<GetProcessByIdentifierLogsData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").ProcessLogs, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
  * Stream process logs in real time
- * Streams the stdout and stderr output of a process in real time, one line per log, prefixed with 'stdout:' or 'stderr:'. Closes when the process exits or the client disconnects.
+ * Streams the stdout and stderr output of a process in real time: the output so far, then live output as the process writes it. Closes when the process exits or the client disconnects.
+ * Each output line starts with `stdout:` or `stderr:` and keeps its trailing newline. A partial line (e.g. a prompt) is sent as soon as it is written; when the process completes it, the rest follows without a new prefix. `[keepalive]` lines are sent every 30 seconds.
  */
 export declare const getProcessByIdentifierLogsStream: <ThrowOnError extends boolean = false>(options: Options<GetProcessByIdentifierLogsStreamData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<string, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**

package/dist/cjs-browser/types/sandbox/client/types.gen.d.ts

@@ -278,11 +278,17 @@ export type FuzzySearchResponse = {
 };
 export type HealthResponse = {
     arch: string;
+    /**
+     * Build time in RFC 3339 (UTC), or "unknown" for builds without it
+     */
     buildTime: string;
     gitCommit: string;
     goVersion: string;
     lastUpgrade: UpgradeStatus;
     os: string;
+    /**
+     * API start time in RFC 3339
+     */
     startedAt: string;
     status: string;
     upgradeCount: number;
@@ -377,6 +383,9 @@ export type ProcessRequest = {
 };
 export type ProcessResponse = {
     command: string;
+    /**
+     * Completion time, same format as startedAt. Empty string while the process runs
+     */
     completedAt: string;
     exitCode: number;
     /**
@@ -389,6 +398,9 @@ export type ProcessResponse = {
     pid: string;
     restartCount?: number;
     restartOnFailure?: boolean;
+    /**
+     * Start time as an HTTP date (RFC 1123, e.g. Wed, 01 Jan 2023 12:00:00 GMT)
+     */
     startedAt: string;
     status: 'failed' | 'killed' | 'stopped' | 'running' | 'completed';
     stderr: string;
@@ -1143,12 +1155,16 @@ export type GetFilesystemSearchByPathData = {
         path: string;
     };
     query?: {
+        /**
+         * Fuzzy pattern matched against each relative path (e.g., mngo for src/main.go). When omitted, the search path itself is used as the pattern.
+         */
+        query?: string;
         /**
          * Maximum number of results to return (default: 20)
          */
         maxResults?: number;
         /**
-         * Comma-separated file patterns to include (e.g., *.go,*.js)
+         * Accepted for compatibility but currently ignored; use filesystem-find for glob filtering
          */
         patterns?: string;
         /**
@@ -1226,7 +1242,7 @@ export type GetFilesystemByPathData = {
     body?: never;
     path: {
         /**
-         * File or directory path
+         * File or directory path. Relative paths are resolved against the filesystem working directory. For example, with a working directory of /app, GET /filesystem/workspace resolves to /app/workspace. To access the absolute path /workspace over HTTP, encode its leading slash as %2F: GET /filesystem/%2Fworkspace. The double-slash form GET /filesystem//workspace also addresses /workspace.
          */
         path: string;
     };
@@ -1651,7 +1667,7 @@ export type DeleteProcessByIdentifierErrors = {
 export type DeleteProcessByIdentifierError = DeleteProcessByIdentifierErrors[keyof DeleteProcessByIdentifierErrors];
 export type DeleteProcessByIdentifierResponses = {
     /**
-     * Process stopped
+     * Process stop requested
      */
     200: SuccessResponse;
 };
@@ -1709,7 +1725,7 @@ export type DeleteProcessByIdentifierKillErrors = {
 export type DeleteProcessByIdentifierKillError = DeleteProcessByIdentifierKillErrors[keyof DeleteProcessByIdentifierKillErrors];
 export type DeleteProcessByIdentifierKillResponses = {
     /**
-     * Process killed
+     * Process kill requested
      */
     200: SuccessResponse;
 };
@@ -1775,7 +1791,7 @@ export type GetProcessByIdentifierLogsStreamErrors = {
 export type GetProcessByIdentifierLogsStreamError = GetProcessByIdentifierLogsStreamErrors[keyof GetProcessByIdentifierLogsStreamErrors];
 export type GetProcessByIdentifierLogsStreamResponses = {
     /**
-     * Stream of process logs, one line per log (prefixed with stdout:/stderr:)
+     * Process output, each line prefixed with stdout: or stderr:
      */
     200: string;
 };

package/dist/cjs-browser/types/sandbox/preview.d.ts

@@ -1,7 +1,9 @@
-import { Preview, PreviewToken, Sandbox } from "../client/index.js";
+import type { Preview, PreviewToken, Sandbox } from "../client/index.js";
+import type { SandboxPreviewCreateConfiguration } from "./types.js";
 export declare class SandboxPreviewToken {
     private previewToken;
     constructor(previewToken: PreviewToken);
+    get name(): string;
     get value(): string;
     get expiresAt(): string | Date;
     get expired(): boolean;
@@ -12,6 +14,11 @@ export declare class SandboxPreviewTokens {
     get previewName(): string;
     get resourceName(): string;
     create(expiresAt: Date): Promise<SandboxPreviewToken>;
+    /**
+     * Reuse the latest token within the requested expiry ceiling, or mint one.
+     * minValidity is in milliseconds. Concurrent callers may create separate tokens.
+     */
+    createIfExpired(expiresAt?: Date, minValidity?: number): Promise<SandboxPreviewToken>;
     list(): Promise<SandboxPreviewToken[]>;
     delete(tokenName: string): Promise<{
         message?: string;
@@ -22,6 +29,7 @@ export declare class SandboxPreview {
     tokens: SandboxPreviewTokens;
     constructor(preview: Preview);
     get name(): string;
+    get url(): string;
     get metadata(): import("../client/types.gen.js").PreviewMetadata;
     get spec(): import("../client/types.gen.js").PreviewSpec;
 }
@@ -30,8 +38,9 @@ export declare class SandboxPreviews {
     constructor(sandbox: Sandbox);
     get sandboxName(): string;
     list(): Promise<SandboxPreview[]>;
-    create(preview: Preview, force?: boolean): Promise<SandboxPreview>;
-    createIfNotExists(preview: Preview, force?: boolean): Promise<SandboxPreview>;
+    create(preview: Preview | SandboxPreviewCreateConfiguration, force?: boolean): Promise<SandboxPreview>;
+    /** Existing previews are returned as-is; shorthand's private default applies only on creation. */
+    createIfNotExists(preview: Preview | SandboxPreviewCreateConfiguration, force?: boolean): Promise<SandboxPreview>;
     get(previewName: string): Promise<SandboxPreview>;
     delete(previewName: string): Promise<Preview>;
     private waitForDeletion;

package/dist/cjs-browser/types/sandbox/types.d.ts

@@ -38,6 +38,13 @@ export type SandboxUpdateMetadata = {
 export type SandboxUpdateNetwork = {
     network?: SandboxNetwork;
 };
+export type SandboxPreviewCreateConfiguration = {
+    port: number;
+    /** Defaults to preview-<port> within this sandbox. */
+    name?: string;
+    /** Defaults to false on creation; existing previews are not changed. */
+    public?: boolean;
+};
 export type SandboxCreateConfiguration = {
     name?: string;
     image?: string;