@blaxel/core 0.3.26-preview.309 → 0.3.26-preview.311

package/dist/cjs-browser/common/error-types.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBlaxelError = isBlaxelError;
+exports.getBlaxelErrorCode = getBlaxelErrorCode;
+exports.getBlaxelErrorStatus = getBlaxelErrorStatus;
+exports.getBlaxelErrorMessage = getBlaxelErrorMessage;
+exports.getBlaxelErrorRequestId = getBlaxelErrorRequestId;
+const action_js_1 = require("../sandbox/action.js");
+const sandbox_js_1 = require("../sandbox/sandbox.js");
+function readProperty(value, key) {
+    try {
+        return typeof value === "object" && value !== null
+            ? value[key]
+            : undefined;
+    }
+    catch {
+        // Catch hostile getters and revoked proxies, including in custom transports.
+        return undefined;
+    }
+}
+const isCode = (value) => (typeof value === "string" && value.length > 0) ||
+    (typeof value === "number" && Number.isFinite(value));
+const isStatus = (value) => typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599;
+/**
+ * True only for a value that carries a Blaxel error code or HTTP status in a
+ * shape the SDK throws for API failures: a `ResponseError` (including
+ * `SandboxGatewayError`), a `SandboxCreationTimeoutError`, or a raw control-plane
+ * error body (`{ error, code }`, `{ code, message, status_code }` or
+ * `{ error: { code, message, status } }`). Plain `Error`s (including network
+ * errors with a `code` such as `ECONNRESET`), strings, raw HTML/text bodies, empty
+ * bodies and a bare `{ error: string }` are false: they carry neither. Matching
+ * `ResponseError` uses `instanceof`, so an error thrown by a second copy of
+ * `@blaxel/core` does not match. Does not wrap or mutate the value. Never throws.
+ * Like `is_blaxel_error` in the Python SDK, it is false for plain exceptions and
+ * strings.
+ */
+function isBlaxelError(err) {
+    try {
+        if (err instanceof Error) {
+            return err instanceof action_js_1.ResponseError || err instanceof sandbox_js_1.SandboxCreationTimeoutError;
+        }
+        if (typeof err !== "object" || err === null || Array.isArray(err))
+            return false;
+        const error = readProperty(err, "error");
+        if (typeof error === "string")
+            return isStatus(readProperty(err, "code"));
+        if (typeof readProperty(err, "code") === "string" &&
+            typeof readProperty(err, "message") === "string" &&
+            isStatus(readProperty(err, "status_code")))
+            return true;
+        return (typeof error === "object" && error !== null && !Array.isArray(error) &&
+            typeof readProperty(error, "code") === "string" &&
+            typeof readProperty(error, "message") === "string" &&
+            isStatus(readProperty(error, "status")));
+    }
+    catch {
+        return false;
+    }
+}
+// Fixed-depth inspection: ResponseError carries `error`/`data`; gateway bodies
+// nest their fields once more in `error`. No recursion, including on cyclic input.
+function errorCandidates(err) {
+    const bodies = [err, readProperty(err, "error"), readProperty(err, "data")];
+    return bodies.flatMap((body) => [body, readProperty(body, "error")]);
+}
+function readHeader(err, name) {
+    try {
+        const headers = readProperty(readProperty(err, "response"), "headers");
+        const get = readProperty(headers, "get");
+        if (typeof get !== "function")
+            return undefined;
+        const value = Reflect.apply(get, headers, [name]);
+        return typeof value === "string" && value.length > 0 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read a code from the existing error/body, then X-Blaxel-Error-Code. Never throws. */
+function getBlaxelErrorCode(err) {
+    for (const candidate of errorCandidates(err)) {
+        const code = readProperty(candidate, "code");
+        if (isCode(code))
+            return code;
+    }
+    return readHeader(err, "x-blaxel-error-code");
+}
+/**
+ * Read HTTP status from the existing error/response, then the body (`status`,
+ * `status_code`, or a numeric `code`). Raw text and plain Error have none.
+ * Never throws.
+ */
+function getBlaxelErrorStatus(err) {
+    const status = readProperty(err, "status");
+    if (isStatus(status))
+        return status;
+    const responseStatus = readProperty(readProperty(err, "response"), "status");
+    if (isStatus(responseStatus))
+        return responseStatus;
+    for (const candidate of errorCandidates(err)) {
+        for (const key of ["status", "status_code", "code"]) {
+            const value = readProperty(candidate, key);
+            if (isStatus(value))
+                return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Read the existing Error.message, body message/error text, or raw text/HTML.
+ * Returns undefined for an empty/unrecognized body. Never throws.
+ */
+function getBlaxelErrorMessage(err) {
+    for (const candidate of errorCandidates(err)) {
+        const message = typeof candidate === "string" ? candidate : readProperty(candidate, "message");
+        if (typeof message === "string" && message.length > 0)
+            return message;
+    }
+    return undefined;
+}
+/**
+ * Read X-Cf-Request-Id, X-Amz-Cf-Id, then CF-Ray from a retained response.
+ * Raw control-plane bodies and SandboxCreationTimeoutError do not retain
+ * response headers, so their request ID is unavailable. Never throws.
+ */
+function getBlaxelErrorRequestId(err) {
+    for (const name of ["x-cf-request-id", "x-amz-cf-id", "cf-ray"]) {
+        const value = readHeader(err, name);
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}

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.309";
-const BUILD_COMMIT = "314ba709f1a271c3a30cea714a3b97c8e8efb144";
+const BUILD_VERSION = "0.3.26-preview.311";
+const BUILD_COMMIT = "a62496fa4537136926770cdd0d6e48ceb8506491";
 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/index.js

@@ -23,6 +23,7 @@ __exportStar(require("./common/env.js"), exports);
 __exportStar(require("./common/h2-runtime.js"), exports);
 __exportStar(require("./common/node.js"), exports);
 __exportStar(require("./common/errors.js"), exports);
+__exportStar(require("./common/error-types.js"), exports);
 __exportStar(require("./common/internal.js"), exports);
 __exportStar(require("./common/logger.js"), exports);
 __exportStar(require("./common/pagination.js"), exports);

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

@@ -37,6 +37,7 @@ Object.defineProperty(exports, "ResponseError", { enumerable: true, get: functio
 Object.defineProperty(exports, "SandboxGatewayError", { enumerable: true, get: function () { return action_js_1.SandboxGatewayError; } });
 Object.defineProperty(exports, "isGatewayError", { enumerable: true, get: function () { return action_js_1.isGatewayError; } });
 Object.defineProperty(exports, "isGatewayTimeout", { enumerable: true, get: function () { return action_js_1.isGatewayTimeout; } });
+__exportStar(require("../common/error-types.js"), exports);
 __exportStar(require("./filesystem/index.js"), exports);
 __exportStar(require("./codegen/index.js"), exports);
 var index_js_2 = require("./drive/index.js");

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/common/error-types.d.ts

@@ -0,0 +1,159 @@
+import { ResponseError } from "../sandbox/action.js";
+import { SandboxCreationTimeoutError } from "../sandbox/sandbox.js";
+/**
+ * Codes the edge gateway returns for sandbox, agent, function and MCP URLs,
+ * in `error.code` and the `X-Blaxel-Error-Code` header.
+ */
+export type BlaxelGatewayErrorCode = 
+/** 404: the URL does not map to a known workload. */
+"ROUTE_NOT_FOUND"
+/** 404 (401 for unauthenticated callers): the workload does not exist. */
+ | "WORKLOAD_NOT_FOUND"
+/** 404: the workspace in the URL does not exist. */
+ | "WORKSPACE_NOT_FOUND"
+/** 404, retryable: the workload exists but is not serving. */
+ | "WORKLOAD_UNAVAILABLE"
+/** The workload failed and will not serve. */
+ | "WORKLOAD_FAILED"
+/** Retryable: routing is briefly unavailable. */
+ | "ROUTING_UNAVAILABLE"
+/** 401: no credentials were sent. */
+ | "AUTHENTICATION_REQUIRED"
+/** 401: the credentials were rejected. */
+ | "AUTHENTICATION_FAILED"
+/** 401: the token was revoked; get a new one. */
+ | "TOKEN_REVOKED"
+/** 403: authenticated but not allowed on this resource. */
+ | "FORBIDDEN"
+/** 400: malformed request. */
+ | "BAD_REQUEST"
+/** 402: the workspace exceeded its plan's usage limits. */
+ | "USAGE_LIMIT_EXCEEDED"
+/** Reserved: defined by the gateway but not currently returned. */
+ | "POLICY_VIOLATION"
+/** Retryable: could not connect to the workload. */
+ | "UPSTREAM_CONNECT_FAILED"
+/** Retryable: connecting to the workload timed out. */
+ | "UPSTREAM_CONNECT_TIMEOUT"
+/** Retryable: the request to the workload failed. */
+ | "UPSTREAM_ERROR"
+/** Retryable: the workload did not answer in time. */
+ | "UPSTREAM_TIMEOUT"
+/** Retryable: the gateway itself failed. */
+ | "GATEWAY_INTERNAL_ERROR";
+/**
+ * Authentication/authorization codes from sandbox creation and fork.
+ * `TOKEN_REVOKED` is also returned by every control-plane endpoint.
+ */
+export type BlaxelAuthErrorCode = 
+/** 401: the token was revoked; get a new one. */
+"TOKEN_REVOKED"
+/** 403: the credentials were rejected. */
+ | "UNAUTHORIZED"
+/** 403: no (write) access to the requested workspace. */
+ | "UNAUTHORIZED_WORKSPACE"
+/** 503, retryable: credentials could not be verified right now. */
+ | "AUTHENTICATION_UNAVAILABLE"
+/** 400: the credentials reach several workspaces (or none); set one. */
+ | "WORKSPACE_REQUIRED";
+/** Codes the control plane returns when creating or forking a sandbox. */
+export type BlaxelSandboxCreationErrorCode = "READ_FAILED" | "PARSE_FAILED" | "VALIDATION_FAILED" | "VALIDATION_ERROR" | "INVALID_INPUT" | "INVALID_IMAGE" | "IMAGE_NOT_FOUND" | "UPLOAD_NOT_SUPPORTED" | "UNSUPPORTED_GENERATION" | "KERNEL_GENERATION_MISMATCH" | "INVALID_PORTS" | "INVALID_REGION" | "REGION_MISMATCH" | "INVALID_VOLUME" | "INVALID_VOLUME_COUNT" | "INVALID_VOLUME_REGION" | "VOLUME_ALREADY_ATTACHED" | "VOLUME_PROVIDER_MISMATCH" | "VOLUME_NOT_FOUND" | "WORKSPACE_NOT_FOUND" | "ACCOUNT_NOT_FOUND" | "SANDBOX_ALREADY_EXISTS" | "SANDBOX_DELETION_IN_PROGRESS" | "SANDBOX_DELETED" | "VOLUME_DELETED" | "CREATION_TIMEOUT" | "QUOTA_EXCEEDED" | "RATE_LIMIT_EXCEEDED" | "WORKSPACE_RATE_LIMIT_EXCEEDED" | "SERVICE_UNAVAILABLE" | "DATABASE_ERROR" | "LOCK_ACQUISITION_FAILED" | "VOLUME_LOOKUP_FAILED" | "BUILD_TRIGGER_ERROR" | "PRESIGNED_URL_ERROR" | "UPLOAD_UNAVAILABLE" | "DEPLOYMENT_FAILED" | "CLUSTER_GATEWAY_ERROR" | "LOCKDOWN_ERROR" | "PROXY_CONFIG_ERROR" | "VALIDATED_DATA_ERROR" | "WORKSPACE_DATA_MISSING" | "CALLBACK_SEND_FAILED" | "FORK_FAILED" | "HANDLER_ERROR" | "INTERNAL_ERROR" | "UNKNOWN_ERROR";
+/** Known backend codes, including the reserved POLICY_VIOLATION code. */
+export type BlaxelErrorCode = BlaxelGatewayErrorCode | BlaxelAuthErrorCode | BlaxelSandboxCreationErrorCode;
+/** Known/new string codes, or the numeric HTTP code of a generic control-plane body. */
+export type BlaxelErrorCodeValue = BlaxelErrorCode | (string & Record<never, never>) | number;
+/** Generic control-plane error body, returned by most `/v0` endpoints. */
+export type BlaxelApiErrorBody = {
+    /** Human-readable message. */
+    error: string;
+    /** HTTP status code (a number, not a string code). */
+    code: number;
+};
+/** Control-plane error body of sandbox creation and fork. */
+export type BlaxelActionErrorBody = {
+    code: BlaxelSandboxCreationErrorCode | BlaxelAuthErrorCode | (string & Record<never, never>);
+    message: string;
+    /** HTTP status code. */
+    status_code: number;
+    /** Extra discriminant, e.g. "CREATION_IN_PROGRESS" on SANDBOX_ALREADY_EXISTS. */
+    reason?: string;
+    /** Creation step that failed. */
+    step?: string;
+    workspace?: string;
+    sandbox_name?: string;
+    timestamp?: string;
+    cause?: string;
+    details?: Record<string, unknown>;
+};
+/** Edge gateway error body; also used by the control plane for TOKEN_REVOKED. */
+export type BlaxelPlatformErrorBody = {
+    error: {
+        code: BlaxelGatewayErrorCode | (string & Record<never, never>);
+        message: string;
+        /** HTTP status code. */
+        status: number;
+        /** When present, "platform": the gateway answered, not the workload. */
+        origin?: "platform";
+        /** Whether retrying the same request can succeed. */
+        retryable?: boolean;
+        /** Whether the workload may have seen the request before it failed. */
+        dispatch_state?: "not_dispatched" | "dispatched_unknown";
+        /** True only when retryable and the workload never saw the request. */
+        safe_to_retry_request?: boolean;
+        action?: string;
+        do_not?: string;
+        docs_url?: string;
+        timestamp?: string;
+    };
+};
+/**
+ * Error body of the sandbox API (`sandbox.fs`, `sandbox.process`, ...). It has no
+ * code or status of its own: callers receive it inside `ResponseError`
+ * (`err.data` or `err.error`), which carries the HTTP status.
+ */
+export type BlaxelSandboxApiErrorBody = {
+    error: string;
+};
+/**
+ * Values {@link isBlaxelError} recognizes: the error classes the SDK throws for
+ * API failures (`ResponseError`, which includes `SandboxGatewayError`, and
+ * `SandboxCreationTimeoutError`) and the raw error bodies the control-plane
+ * client throws, each with its required code and status fields. This is a union
+ * of existing values, not a new error class or normalized shape.
+ */
+export type BlaxelErrorLike = ResponseError | SandboxCreationTimeoutError | BlaxelApiErrorBody | Pick<BlaxelActionErrorBody, "code" | "message" | "status_code"> | {
+    error: Pick<BlaxelPlatformErrorBody["error"], "code" | "message" | "status">;
+};
+/**
+ * True only for a value that carries a Blaxel error code or HTTP status in a
+ * shape the SDK throws for API failures: a `ResponseError` (including
+ * `SandboxGatewayError`), a `SandboxCreationTimeoutError`, or a raw control-plane
+ * error body (`{ error, code }`, `{ code, message, status_code }` or
+ * `{ error: { code, message, status } }`). Plain `Error`s (including network
+ * errors with a `code` such as `ECONNRESET`), strings, raw HTML/text bodies, empty
+ * bodies and a bare `{ error: string }` are false: they carry neither. Matching
+ * `ResponseError` uses `instanceof`, so an error thrown by a second copy of
+ * `@blaxel/core` does not match. Does not wrap or mutate the value. Never throws.
+ * Like `is_blaxel_error` in the Python SDK, it is false for plain exceptions and
+ * strings.
+ */
+export declare function isBlaxelError(err: unknown): err is BlaxelErrorLike;
+/** Read a code from the existing error/body, then X-Blaxel-Error-Code. Never throws. */
+export declare function getBlaxelErrorCode(err: unknown): BlaxelErrorCodeValue | undefined;
+/**
+ * Read HTTP status from the existing error/response, then the body (`status`,
+ * `status_code`, or a numeric `code`). Raw text and plain Error have none.
+ * Never throws.
+ */
+export declare function getBlaxelErrorStatus(err: unknown): number | undefined;
+/**
+ * Read the existing Error.message, body message/error text, or raw text/HTML.
+ * Returns undefined for an empty/unrecognized body. Never throws.
+ */
+export declare function getBlaxelErrorMessage(err: unknown): string | undefined;
+/**
+ * Read X-Cf-Request-Id, X-Amz-Cf-Id, then CF-Ray from a retained response.
+ * Raw control-plane bodies and SandboxCreationTimeoutError do not retain
+ * response headers, so their request ID is unavailable. Never throws.
+ */
+export declare function getBlaxelErrorRequestId(err: unknown): string | undefined;

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

@@ -7,6 +7,7 @@ export * from "./common/env.js";
 export * from "./common/h2-runtime.js";
 export * from "./common/node.js";
 export * from "./common/errors.js";
+export * from "./common/error-types.js";
 export * from "./common/internal.js";
 export * from "./common/logger.js";
 export * from "./common/pagination.js";

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

@@ -1,5 +1,6 @@
 export { deleteFilesystemByPath, deleteNetworkProcessByPidMonitor, deleteProcessByIdentifier, deleteProcessByIdentifierKill, Directory, ErrorResponse, File, FileRequest, FileWithContent, getFilesystemByPath, getNetworkProcessByPidPorts, putCodegenFastapplyByPath, ApplyEditResponse, ApplyEditRequest, getCodegenRerankingByPath, RerankingResponse, getProcess, getProcessByIdentifier, getProcessByIdentifierLogs, getProcessByIdentifierLogsStream, PortMonitorRequest, postNetworkProcessByPidMonitor, postProcess, ProcessRequest, ProcessResponse, putFilesystemByPath, SuccessResponse } from "./client/index.js";
 export { ResponseError, SandboxGatewayError, isGatewayError, isGatewayTimeout } from "./action.js";
+export * from "../common/error-types.js";
 export * from "./filesystem/index.js";
 export * from "./codegen/index.js";
 export { SandboxDrive, type DriveMountRequest, type DriveMountResponse, type DriveMountInfo, type DriveUnmountResponse } from "./drive/index.js";

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;