@blaxel/core 0.2.86-preview.165 → 0.2.87-dev.173

package/dist/cjs/types/common/credentials.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/types/common/errors.d.ts

@@ -1 +1,11 @@
+/**
+ * Thrown when Blaxel credentials are missing or incomplete.
+ *
+ * Surfaced eagerly with an actionable message (which env var / login step is
+ * missing) instead of silently sending empty workspace/authorization headers
+ * and letting the user hit a misleading server-side "workspace is required".
+ */
+export declare class CredentialsError extends Error {
+    constructor(message: string);
+}
 export declare function handleDynamicImportError(err: any): void;

package/dist/cjs/types/common/h2fetch.d.ts

@@ -10,13 +10,18 @@ import type { H2Pool } from "./h2pool.js";
  */
 export declare function createH2Fetch(session: http2.ClientHttp2Session): (input: Request) => Promise<Response>;
 /**
- * Creates a fetch()-compatible function backed by the H2 session pool.
+ * Creates a fetch()-compatible function backed by the H2 session pool, routed
+ * through the single gateway. Used as the generated client's `fetch`.
  *
- * The pool validates idle sessions before reuse. If no usable H2 session is
- * available, the request falls back to regular fetch before any H2 frames
- * are sent.
+ * If no usable H2 session is available, the request falls back to regular fetch
+ * before any H2 frames are sent.
  */
 export declare function createPoolBackedH2Fetch(pool: H2Pool, domain: string): (input: Request) => Promise<Response>;
+/**
+ * Pool-backed H2 request taking raw url + init (skips Request allocation),
+ * routed through the same single gateway. Used by `SandboxAction.h2Fetch` and
+ * the code interpreter.
+ */
 export declare function h2RequestDirectFromPool(pool: H2Pool, domain: string, url: string, init?: RequestInit): Promise<Response>;
 /**
  * Low-level H2 request that takes raw URL + init, skipping Request construction.

package/dist/cjs/types/common/pagination.d.ts

@@ -0,0 +1,35 @@
+export type PaginatedListMeta = {
+    hasMore?: boolean;
+    nextCursor?: string;
+    total?: number;
+};
+export type CursorPaginationQuery = {
+    cursor?: string;
+};
+export type ListResponse<T> = T[] | {
+    data?: T[] | null;
+    meta?: PaginatedListMeta | null;
+} | null | undefined;
+export type AutoPagingEachCallback<T> = (item: T) => boolean | void | Promise<boolean | void>;
+export type AutoPagingToArrayOptions = {
+    limit: number;
+};
+export type PaginatedList<T, TQuery extends CursorPaginationQuery = CursorPaginationQuery> = AsyncIterable<T> & {
+    data: T[];
+    meta: PaginatedListMeta;
+    hasMore: boolean;
+    nextCursor?: string;
+    nextPage(): Promise<PaginatedList<T, TQuery> | null>;
+    autoPagingEach(onItem: AutoPagingEachCallback<T>): Promise<void>;
+    autoPagingToArray(options: AutoPagingToArrayOptions): Promise<T[]>;
+};
+type CreatePaginatedListOptions<TRaw, TItem, TQuery extends CursorPaginationQuery> = {
+    response: ListResponse<TRaw>;
+    fetchPage: (query?: TQuery) => Promise<ListResponse<TRaw>>;
+    mapItem: (item: TRaw) => TItem | Promise<TItem>;
+    query?: TQuery;
+    seenCursors?: Set<string>;
+};
+export declare function unwrapListData<T>(response: ListResponse<T>): T[];
+export declare function createPaginatedList<TRaw, TItem, TQuery extends CursorPaginationQuery = CursorPaginationQuery>({ response, fetchPage, mapItem, query, seenCursors, }: CreatePaginatedListOptions<TRaw, TItem, TQuery>): Promise<PaginatedList<TItem, TQuery>>;
+export {};

package/dist/cjs/types/common/pagination.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/types/common/settings.d.ts

@@ -63,6 +63,15 @@ declare class Settings {
     get disableH2(): boolean;
     get maxConcurrentH2Requests(): number;
     get fsPartRetries(): number;
+    /**
+     * Fail fast with a clear, actionable error when credentials are missing or
+     * incomplete, instead of sending empty workspace/authorization headers and
+     * surfacing a misleading server-side "workspace is required". Skipped for
+     * `forceUrl` sandbox sessions, which carry their own headers and never read
+     * `settings.headers`. Leaves `workspace` itself non-throwing so telemetry
+     * tagging stays safe.
+     */
+    private assertCredentials;
     authenticate(): Promise<void>;
 }
 export declare const settings: Settings;

package/dist/cjs/types/drive/index.d.ts

@@ -1,11 +1,12 @@
-import { Drive } from "../client/index.js";
-export interface DriveCreateConfiguration {
+import { type Drive, type ListDrivesData } from "../client/index.js";
+export type DriveListQuery = NonNullable<ListDrivesData["query"]>;
+export type DriveCreateConfiguration = {
     name?: string;
     displayName?: string;
     labels?: Record<string, string>;
     size?: number;
     region?: string;
-}
+};
 export declare class DriveInstance {
     private drive;
     constructor(drive: Drive);
@@ -19,7 +20,37 @@ export declare class DriveInstance {
     get region(): string | undefined;
     static create(config: DriveCreateConfiguration | Drive): Promise<DriveInstance>;
     static get(driveName: string): Promise<DriveInstance>;
-    static list(): Promise<DriveInstance[]>;
+    /**
+     * List one page of drives.
+     *
+     * The returned page exposes `data` for the current page, `meta` for cursor
+     * metadata, and helpers to fetch more pages only when you need them.
+     *
+     * @example
+     * ```ts
+     * const page = await DriveInstance.list({ limit: 50 });
+     *
+     * for (const drive of page.data) {
+     *   console.log(drive.name);
+     * }
+     *
+     * const nextPage = await page.nextPage();
+     * ```
+     *
+     * @example
+     * ```ts
+     * const allDrives = await (await DriveInstance.list()).autoPagingToArray({
+     *   limit: 1000,
+     * });
+     * ```
+     */
+    static list(query?: DriveListQuery): Promise<import("../common/pagination.js").PaginatedList<DriveInstance, {
+        cursor?: string;
+        limit?: number;
+        sort?: "createdAt:desc" | "createdAt:asc" | "name:asc" | "name:desc";
+        q?: string;
+        anchor?: "end";
+    }>>;
     static delete(driveName: string): Promise<{
         message?: string;
         name?: string;

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

@@ -7,6 +7,7 @@ export * from "./common/node.js";
 export * from "./common/errors.js";
 export * from "./common/internal.js";
 export * from "./common/logger.js";
+export * from "./common/pagination.js";
 export * from "./common/settings.js";
 export * from "./common/webhook.js";
 export * from "./drive/index.js";

package/dist/cjs/types/jobs/jobs.d.ts

@@ -1,4 +1,5 @@
-import { CreateJobExecutionRequest, JobExecution } from "../client/index.js";
+import { type CreateJobExecutionRequest, type JobExecution, type ListJobExecutionsData } from "../client/index.js";
+export type JobExecutionListQuery = NonNullable<ListJobExecutionsData["query"]>;
 declare class BlJob {
     jobName: string;
     constructor(jobName: string);
@@ -16,9 +17,38 @@ declare class BlJob {
      */
     getExecution(executionId: string): Promise<JobExecution>;
     /**
-     * List all executions for this job
+     * List one page of executions for this job.
+     *
+     * The returned page exposes `data` for the current page, `meta` for cursor
+     * metadata, and helpers to fetch more pages only when you need them.
+     *
+     * @example
+     * ```ts
+     * const job = blJob("daily-import");
+     * const page = await job.listExecutions({ limit: 50 });
+     *
+     * for (const execution of page.data) {
+     *   console.log(execution.status);
+     * }
+     *
+     * const nextPage = await page.nextPage();
+     * ```
+     *
+     * @example
+     * ```ts
+     * const job = blJob("daily-import");
+     * const executions = await (await job.listExecutions()).autoPagingToArray({
+     *   limit: 1000,
+     * });
+     * ```
      */
-    listExecutions(): Promise<JobExecution[]>;
+    listExecutions(query?: JobExecutionListQuery): Promise<import("../common/pagination.js").PaginatedList<JobExecution, {
+        limit?: number;
+        offset?: number;
+        cursor?: string;
+        sort?: "createdAt:desc" | "createdAt:asc" | "name:asc" | "name:desc";
+        q?: string;
+    }>>;
     /**
      * Get the status of a specific execution
      */

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

@@ -61,7 +61,7 @@ export declare const getCodegenRerankingByPath: <ThrowOnError extends boolean =
 export declare const getDrivesMount: <ThrowOnError extends boolean = false>(options?: Options<GetDrivesMountData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").DriveListResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
  * Attach a drive to a local path
- * Mounts an agent drive using the blfs binary to a local path, optionally mounting a subpath within the drive
+ * Mounts an agent drive using the blfs binary to a local path, optionally mounting a subpath within the drive. Supports optional UID/GID mapping to remap file ownership between the local sandbox and the filer (always mapped to filer UID/GID 0). Mapping values can be set per-request via uidMap/gidMap fields, or globally via BLFS_UID_MAP/BLFS_GID_MAP environment variables (request values take precedence).
  */
 export declare const postDrivesMount: <ThrowOnError extends boolean = false>(options: Options<PostDrivesMountData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").DriveMountResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**

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

@@ -37,8 +37,16 @@ export type DriveListResponse = {
 export type DriveMountInfo = {
     driveName?: string;
     drivePath?: string;
+    /**
+     * The local GID used for this mount
+     */
+    gidMap?: string;
     mountPath?: string;
     readOnly?: boolean;
+    /**
+     * The local UID used for this mount
+     */
+    uidMap?: string;
 };
 export type DriveMountRequest = {
     driveName: string;
@@ -46,19 +54,35 @@ export type DriveMountRequest = {
      * Optional, defaults to "/"
      */
     drivePath?: string;
+    /**
+     * Optional, local GID to map (filer GID is always 0)
+     */
+    gidMap?: string;
     mountPath: string;
     /**
      * Optional, defaults to false
      */
     readOnly?: boolean;
+    /**
+     * Optional, local UID to map (filer UID is always 0)
+     */
+    uidMap?: string;
 };
 export type DriveMountResponse = {
     driveName?: string;
     drivePath?: string;
+    /**
+     * The local GID used for this mount
+     */
+    gidMap?: string;
     message?: string;
     mountPath?: string;
     readOnly?: boolean;
     success?: boolean;
+    /**
+     * The local UID used for this mount
+     */
+    uidMap?: string;
 };
 export type DriveUnmountResponse = {
     message?: string;

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

@@ -30,8 +30,8 @@ export declare class SandboxPreviews {
     constructor(sandbox: Sandbox);
     get sandboxName(): string;
     list(): Promise<SandboxPreview[]>;
-    create(preview: Preview): Promise<SandboxPreview>;
-    createIfNotExists(preview: Preview): Promise<SandboxPreview>;
+    create(preview: Preview, force?: boolean): Promise<SandboxPreview>;
+    createIfNotExists(preview: Preview, force?: boolean): Promise<SandboxPreview>;
     get(previewName: string): Promise<SandboxPreview>;
     delete(previewName: string): Promise<Preview>;
     private waitForDeletion;

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

@@ -1,5 +1,5 @@
 import type http2 from "http2";
-import { SandboxLifecycle, Sandbox as SandboxModel } from "../client/index.js";
+import { type ListSandboxesData, type SandboxLifecycle, type Sandbox as SandboxModel } from "../client/index.js";
 import { SandboxCodegen } from "./codegen/index.js";
 import { SandboxDrive } from "./drive/index.js";
 import { SandboxFileSystem } from "./filesystem/index.js";
@@ -9,6 +9,7 @@ import { SandboxProcess } from "./process/index.js";
 import { SandboxSessions } from "./session.js";
 import { SandboxSystem } from "./system.js";
 import { SandboxConfiguration, SandboxCreateConfiguration, SandboxUpdateMetadata, SandboxUpdateNetwork, SessionWithToken } from "./types.js";
+export type SandboxListQuery = NonNullable<ListSandboxesData["query"]>;
 export declare class SandboxInstance {
     private sandbox;
     fs: SandboxFileSystem;
@@ -51,7 +52,40 @@ export declare class SandboxInstance {
         createIfNotExist?: boolean;
     }): Promise<SandboxInstance>;
     static get(sandboxName: string): Promise<SandboxInstance>;
-    static list(): Promise<SandboxInstance[]>;
+    /**
+     * List one page of sandboxes.
+     *
+     * The returned page exposes `data` for the current page, `meta` for cursor
+     * metadata, and helpers to fetch more pages only when you need them.
+     *
+     * @example
+     * ```ts
+     * const page = await SandboxInstance.list({ limit: 50 });
+     *
+     * for (const sandbox of page.data) {
+     *   console.log(sandbox.metadata.name);
+     * }
+     *
+     * const nextPage = await page.nextPage();
+     * ```
+     *
+     * @example
+     * ```ts
+     * const page = await SandboxInstance.list({ limit: 100 });
+     *
+     * for await (const sandbox of page) {
+     *   console.log(sandbox.metadata.name);
+     * }
+     * ```
+     */
+    static list(query?: SandboxListQuery): Promise<import("../common/pagination.js").PaginatedList<SandboxInstance, {
+        showTerminated?: boolean;
+        cursor?: string;
+        limit?: number;
+        sort?: "createdAt:desc" | "createdAt:asc" | "name:asc" | "name:desc";
+        q?: string;
+        anchor?: "end";
+    }>>;
     static delete(sandboxName: string): Promise<SandboxModel>;
     delete(): Promise<SandboxModel>;
     static updateMetadata(sandboxName: string, metadata: SandboxUpdateMetadata): Promise<SandboxInstance>;

package/dist/cjs/types/volume/index.d.ts

@@ -1,12 +1,13 @@
-import { Volume } from "../client/index.js";
-export interface VolumeCreateConfiguration {
+import { type ListVolumesData, type Volume } from "../client/index.js";
+export type VolumeListQuery = NonNullable<ListVolumesData["query"]>;
+export type VolumeCreateConfiguration = {
     name?: string;
     displayName?: string;
     labels?: Record<string, string>;
     size?: number;
     region?: string;
     template?: string;
-}
+};
 export declare class VolumeInstance {
     private volume;
     constructor(volume: Volume);
@@ -19,7 +20,39 @@ export declare class VolumeInstance {
     get region(): string | undefined;
     static create(config: VolumeCreateConfiguration | Volume): Promise<VolumeInstance>;
     static get(volumeName: string): Promise<VolumeInstance>;
-    static list(): Promise<VolumeInstance[]>;
+    /**
+     * List one page of volumes.
+     *
+     * The returned page exposes `data` for the current page, `meta` for cursor
+     * metadata, and helpers to fetch more pages only when you need them.
+     *
+     * @example
+     * ```ts
+     * const page = await VolumeInstance.list({ limit: 50 });
+     *
+     * for (const volume of page.data) {
+     *   console.log(volume.name);
+     * }
+     *
+     * const nextPage = await page.nextPage();
+     * ```
+     *
+     * @example
+     * ```ts
+     * const page = await VolumeInstance.list({ limit: 100 });
+     *
+     * for await (const volume of page) {
+     *   console.log(volume.name);
+     * }
+     * ```
+     */
+    static list(query?: VolumeListQuery): Promise<import("../common/pagination.js").PaginatedList<VolumeInstance, {
+        cursor?: string;
+        limit?: number;
+        sort?: "createdAt:desc" | "createdAt:asc" | "name:asc" | "name:desc";
+        q?: string;
+        anchor?: "end";
+    }>>;
     static delete(volumeName: string): Promise<Volume>;
     delete(): Promise<Volume>;
     static update(volumeName: string, updates: VolumeCreateConfiguration | Volume): Promise<VolumeInstance>;

package/dist/cjs/volume/index.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VolumeInstance = void 0;
 const uuid_1 = require("uuid");
 const index_js_1 = require("../client/index.js");
+const pagination_js_1 = require("../common/pagination.js");
 const settings_js_1 = require("../common/settings.js");
 class VolumeInstance {
     volume;
@@ -88,9 +89,46 @@ class VolumeInstance {
         });
         return new VolumeInstance(data);
     }
-    static async list() {
-        const { data } = await (0, index_js_1.listVolumes)({ throwOnError: true });
-        return data.map((volume) => new VolumeInstance(volume));
+    /**
+     * List one page of volumes.
+     *
+     * The returned page exposes `data` for the current page, `meta` for cursor
+     * metadata, and helpers to fetch more pages only when you need them.
+     *
+     * @example
+     * ```ts
+     * const page = await VolumeInstance.list({ limit: 50 });
+     *
+     * for (const volume of page.data) {
+     *   console.log(volume.name);
+     * }
+     *
+     * const nextPage = await page.nextPage();
+     * ```
+     *
+     * @example
+     * ```ts
+     * const page = await VolumeInstance.list({ limit: 100 });
+     *
+     * for await (const volume of page) {
+     *   console.log(volume.name);
+     * }
+     * ```
+     */
+    static async list(query) {
+        const fetchPage = async (pageQuery) => {
+            const { data } = await (0, index_js_1.listVolumes)({
+                query: pageQuery,
+                throwOnError: true,
+            });
+            return data;
+        };
+        return (0, pagination_js_1.createPaginatedList)({
+            response: await fetchPage(query),
+            fetchPage,
+            mapItem: (volume) => new VolumeInstance(volume),
+            query,
+        });
     }
     static async delete(volumeName) {
         const { data } = await (0, index_js_1.deleteVolume)({