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

package/dist/esm/common/settings.js

@@ -1,14 +1,31 @@
 import yaml from 'yaml';
 import { ApiKey } from "../authentication/apikey.js";
 import { ClientCredentials } from "../authentication/clientcredentials.js";
+import { MissingCredentials } from "../authentication/credentials.js";
 import { authentication } from "../authentication/index.js";
 import { env } from "../common/env.js";
+import { CredentialsError } from "../common/errors.js";
 import { fs, os, path } from "../common/node.js";
+/**
+ * Build an actionable "credentials missing" message naming exactly which piece
+ * is absent, based on the env vars currently set.
+ */
+function missingCredentialsMessage() {
+    const hasWorkspace = !!env.BL_WORKSPACE;
+    const hasApiKey = !!env.BL_API_KEY;
+    if (hasWorkspace && !hasApiKey) {
+        return "Blaxel API key is missing. Set the BL_API_KEY environment variable, or run `bl login`, to authenticate (BL_WORKSPACE is already set).";
+    }
+    if (hasApiKey && !hasWorkspace) {
+        return "Blaxel workspace is missing. Set the BL_WORKSPACE environment variable, or run `bl login`, to authenticate (BL_API_KEY is already set).";
+    }
+    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.2.86-preview.165";
-const BUILD_COMMIT = "e53a861ff9a1ab4392f576a45a9ab18a3bdf47fe";
+const BUILD_VERSION = "0.2.87-dev.173";
+const BUILD_COMMIT = "43df206258fd8138bafddefa56333aadab2be731";
 const BUILD_SENTRY_DSN = "https://fd5e60e1c9820e1eef5ccebb84a07127@o4508714045276160.ingest.us.sentry.io/4510465864564736";
-const BLAXEL_API_VERSION = "2026-04-16";
+const BLAXEL_API_VERSION = "2026-04-28";
 // Cache for config.yaml tracking value
 let configTrackingValue = null;
 let configTrackingLoaded = false;
@@ -167,6 +184,7 @@ class Settings {
         return env.BL_API_VERSION || BLAXEL_API_VERSION;
     }
     get headers() {
+        this.assertCredentials();
         const osArch = getOsArch();
         return {
             "x-blaxel-authorization": this.authorization,
@@ -252,7 +270,27 @@ class Settings {
         }
         return 0;
     }
+    /**
+     * 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.
+     */
+    assertCredentials() {
+        const hasConfigCredentials = !!(this.config.apikey ||
+            this.config.apiKey ||
+            this.config.clientCredentials);
+        if (!hasConfigCredentials && this.credentials instanceof MissingCredentials) {
+            throw new CredentialsError(missingCredentialsMessage());
+        }
+        if (!this.workspace) {
+            throw new CredentialsError("Blaxel workspace is missing. Set the BL_WORKSPACE environment variable, or run `bl login`, to authenticate your requests.");
+        }
+    }
     async authenticate() {
+        this.assertCredentials();
         await this.credentials.authenticate();
     }
 }

package/dist/esm/common/settings.test.js

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ApiKey } from '../authentication/apikey.js';
 import { env } from './env.js';
 describe('Settings.apiVersion', () => {
     beforeEach(() => {
@@ -7,14 +8,22 @@ describe('Settings.apiVersion', () => {
     afterEach(() => {
         delete env.BL_API_VERSION;
     });
-    it('defaults to 2026-04-16 when BL_API_VERSION is not set', async () => {
+    it('defaults to 2026-04-28 when BL_API_VERSION is not set', async () => {
         delete env.BL_API_VERSION;
         const { settings } = await import('./settings.js');
-        expect(settings.apiVersion).toBe('2026-04-16');
+        expect(settings.apiVersion).toBe('2026-04-28');
     });
     it('headers include Blaxel-Version set to the default', async () => {
         delete env.BL_API_VERSION;
         const { settings } = await import('./settings.js');
-        expect(settings.headers['Blaxel-Version']).toBe('2026-04-16');
+        // headers now requires resolvable credentials; run in an authenticated context
+        const previous = settings.credentials;
+        settings.credentials = new ApiKey({ apiKey: 'test-key', workspace: 'test-ws' });
+        try {
+            expect(settings.headers['Blaxel-Version']).toBe('2026-04-28');
+        }
+        finally {
+            settings.credentials = previous;
+        }
     });
 });

package/dist/esm/drive/index.js

@@ -1,5 +1,6 @@
 import { v4 as uuidv4 } from "uuid";
 import { createDrive, deleteDrive, getDrive, listDrives, updateDrive } from "../client/index.js";
+import { createPaginatedList } from "../common/pagination.js";
 import { settings } from "../common/settings.js";
 export class DriveInstance {
     drive;
@@ -83,9 +84,44 @@ export class DriveInstance {
         });
         return new DriveInstance(data);
     }
-    static async list() {
-        const { data } = await listDrives({ throwOnError: true });
-        return data.map((drive) => new DriveInstance(drive));
+    /**
+     * 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 async list(query) {
+        const fetchPage = async (pageQuery) => {
+            const { data } = await listDrives({
+                query: pageQuery,
+                throwOnError: true,
+            });
+            return data;
+        };
+        return createPaginatedList({
+            response: await fetchPage(query),
+            fetchPage,
+            mapItem: (drive) => new DriveInstance(drive),
+            query,
+        });
     }
     static async delete(driveName) {
         const { data } = await deleteDrive({

package/dist/esm/index.js

@@ -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/esm/jobs/jobs.js

@@ -1,5 +1,6 @@
 import { createJobExecution, deleteJobExecution, getJobExecution, listJobExecutions, } from "../client/index.js";
 import { logger } from "../common/logger.js";
+import { createPaginatedList } from "../common/pagination.js";
 import { settings } from "../common/settings.js";
 import { startSpan } from "../telemetry/telemetry.js";
 class BlJob {
@@ -75,18 +76,50 @@ class BlJob {
         return data;
     }
     /**
-     * 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,
+     * });
+     * ```
      */
-    async listExecutions() {
+    async listExecutions(query) {
         logger.debug(`Listing executions for job: ${this.jobName}`);
-        const { data } = await listJobExecutions({
-            path: {
-                jobId: this.jobName,
-            },
-            headers: settings.headers,
-            throwOnError: true,
+        const fetchPage = async (pageQuery) => {
+            const { data } = await listJobExecutions({
+                path: {
+                    jobId: this.jobName,
+                },
+                query: pageQuery,
+                headers: settings.headers,
+                throwOnError: true,
+            });
+            return data;
+        };
+        return createPaginatedList({
+            response: await fetchPage(query),
+            fetchPage,
+            mapItem: (execution) => execution,
+            query,
         });
-        return data ?? [];
     }
     /**
      * Get the status of a specific execution

package/dist/esm/sandbox/client/sdk.gen.js

@@ -86,7 +86,7 @@ export const getDrivesMount = (options) => {
 };
 /**
  * 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 const postDrivesMount = (options) => {
     return (options.client ?? _heyApiClient).post({

package/dist/esm/sandbox/preview.js

@@ -99,24 +99,29 @@ export class SandboxPreviews {
         });
         return data.map((preview) => new SandboxPreview(preview));
     }
-    async create(preview) {
+    async create(preview, force) {
+        const query = {};
+        if (force) {
+            query['force'] = 'true';
+        }
         const { data } = await createSandboxPreview({
             path: {
                 sandboxName: this.sandboxName,
             },
+            query,
             body: preview,
             throwOnError: true,
         });
         return new SandboxPreview(data);
     }
-    async createIfNotExists(preview) {
+    async createIfNotExists(preview, force) {
         try {
             const previewInstance = await this.get(preview.metadata.name);
             return previewInstance;
         }
         catch (e) {
             if (typeof e === "object" && e !== null && "code" in e && e.code === 404) {
-                return this.create(preview);
+                return this.create(preview, force);
             }
             throw e;
         }

package/dist/esm/sandbox/sandbox.js

@@ -1,6 +1,7 @@
 import { v4 as uuidv4 } from "uuid";
 import { createSandbox, deleteSandbox, getSandbox, listSandboxes, updateSandbox } from "../client/index.js";
 import { logger } from "../common/logger.js";
+import { createPaginatedList } from "../common/pagination.js";
 import { settings } from "../common/settings.js";
 import { SandboxCodegen } from "./codegen/index.js";
 import { SandboxDrive } from "./drive/index.js";
@@ -219,10 +220,46 @@ export class SandboxInstance {
         const instance = new SandboxInstance(data);
         return SandboxInstance.attachH2Session(instance);
     }
-    static async list() {
-        const { data } = await listSandboxes({ throwOnError: true });
-        const instances = data.map((sandbox) => new SandboxInstance(sandbox));
-        return Promise.all(instances.map((instance) => SandboxInstance.attachH2Session(instance)));
+    /**
+     * 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 async list(query) {
+        const fetchPage = async (pageQuery) => {
+            const { data } = await listSandboxes({
+                query: pageQuery,
+                throwOnError: true,
+            });
+            return data;
+        };
+        return createPaginatedList({
+            response: await fetchPage(query),
+            fetchPage,
+            mapItem: (sandbox) => SandboxInstance.attachH2Session(new SandboxInstance(sandbox)),
+            query,
+        });
     }
     static async delete(sandboxName) {
         const { data } = await deleteSandbox({

package/dist/esm/volume/index.js

@@ -1,5 +1,6 @@
 import { v4 as uuidv4 } from "uuid";
 import { createVolume, deleteVolume, getVolume, listVolumes, updateVolume } from "../client/index.js";
+import { createPaginatedList } from "../common/pagination.js";
 import { settings } from "../common/settings.js";
 export class VolumeInstance {
     volume;
@@ -85,9 +86,46 @@ export class VolumeInstance {
         });
         return new VolumeInstance(data);
     }
-    static async list() {
-        const { data } = await 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 listVolumes({
+                query: pageQuery,
+                throwOnError: true,
+            });
+            return data;
+        };
+        return createPaginatedList({
+            response: await fetchPage(query),
+            fetchPage,
+            mapItem: (volume) => new VolumeInstance(volume),
+            query,
+        });
     }
     static async delete(volumeName) {
         const { data } = await deleteVolume({