@blaxel/core 0.3.25 → 0.3.26-preview.310

package/dist/esm/common/error-types.js

@@ -0,0 +1,126 @@
+import { ResponseError } from "../sandbox/action.js";
+import { SandboxCreationTimeoutError } from "../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.
+ */
+export function isBlaxelError(err) {
+    try {
+        if (err instanceof Error) {
+            return err instanceof ResponseError || err instanceof 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. */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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/esm/common/settings.js

@@ -24,8 +24,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.25";
-const BUILD_COMMIT = "fb45a5005d56241cc56b832f6a624248e8e34f9f";
+const BUILD_VERSION = "0.3.26-preview.310";
+const BUILD_COMMIT = "13bd8f75d15c2c81add546bcabeee2f20a224417";
 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
@@ -94,8 +94,14 @@ function getOsArch() {
     }
     return "browser/unknown";
 }
+/**
+ * An integration built on this SDK identifies itself with one User-Agent
+ * product token: `<name>/<semver>`, lowercase name.
+ */
+const INTEGRATION_TOKEN_PATTERN = /^[a-z0-9][a-z0-9._-]*\/\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 class Settings {
     _credentials;
+    _warnedIntegration = null;
     config;
     constructor() {
         // `credentials` are resolved lazily on first access so that simply
@@ -190,14 +196,38 @@ class Settings {
     get apiVersion() {
         return env.BL_API_VERSION || BLAXEL_API_VERSION;
     }
+    /**
+     * Product token identifying the integration built on this SDK, or `""`.
+     * Resolved from `config.integration`, then `BL_INTEGRATION`. See `Config.integration`.
+     */
+    get integration() {
+        const value = this.config.integration ?? env.BL_INTEGRATION ?? "";
+        if (!value) {
+            return "";
+        }
+        if (!INTEGRATION_TOKEN_PATTERN.test(value)) {
+            // Resolved on every request, so warn once per invalid value rather than per request.
+            if (this._warnedIntegration !== value) {
+                this._warnedIntegration = value;
+                logger.warn(`Ignoring invalid Blaxel integration token ${JSON.stringify(value)}: expected <name>/<semver> with a lowercase name`);
+            }
+            return "";
+        }
+        return value;
+    }
+    set integration(value) {
+        this.config.integration = value;
+    }
     get headers() {
         this.assertCredentials();
         const osArch = getOsArch();
+        const sdkUserAgent = `blaxel/sdk/typescript/${this.version} (${osArch}) blaxel/${this.commit}`;
+        const integration = this.integration;
         return {
             "x-blaxel-authorization": this.authorization,
             "x-blaxel-workspace": this.workspace || "",
             "Blaxel-Version": this.apiVersion,
-            "User-Agent": `blaxel/sdk/typescript/${this.version} (${osArch}) blaxel/${this.commit}`,
+            "User-Agent": integration ? `${sdkUserAgent} ${integration}` : sdkUserAgent,
         };
     }
     get name() {

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

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { ApiKey } from '../authentication/apikey.js';
 import { env } from './env.js';
 import { isBrokenBunH2Runtime } from './h2-runtime.js';
@@ -216,3 +216,73 @@ describe('Settings H2 tuning knobs (config > env > default)', () => {
         });
     });
 });
+describe('Settings.integration', () => {
+    const sdkUserAgent = /^blaxel\/sdk\/typescript\/\S+ \([^)]+\) blaxel\/\S+/;
+    async function authenticated() {
+        const { settings } = await import('./settings.js');
+        settings.credentials = new ApiKey({ apiKey: 'test-key', workspace: 'test-ws' });
+        delete settings.config.integration;
+        delete process.env.BL_INTEGRATION;
+        return settings;
+    }
+    afterEach(async () => {
+        const { settings } = await import('./settings.js');
+        delete settings.config.integration;
+        delete process.env.BL_INTEGRATION;
+    });
+    it('sends the plain SDK User-Agent by default', async () => {
+        const settings = await authenticated();
+        expect(settings.integration).toBe('');
+        expect(settings.headers['User-Agent']).toMatch(new RegExp(sdkUserAgent.source + '$'));
+    });
+    it('appends the token set programmatically, once', async () => {
+        const settings = await authenticated();
+        settings.integration = 'deepseek-harness-blaxel-sandbox/0.1.2';
+        const userAgent = settings.headers['User-Agent'];
+        expect(userAgent).toMatch(sdkUserAgent);
+        expect(userAgent.endsWith(' deepseek-harness-blaxel-sandbox/0.1.2')).toBe(true);
+        expect(userAgent.split('deepseek-harness-blaxel-sandbox').length).toBe(2);
+    });
+    it('reads BL_INTEGRATION when nothing is set programmatically, and config wins', async () => {
+        const settings = await authenticated();
+        process.env.BL_INTEGRATION = 'herdr/1.4.0-rc.1';
+        expect(settings.headers['User-Agent'].endsWith(' herdr/1.4.0-rc.1')).toBe(true);
+        settings.setConfig({ ...settings.config, integration: 'deepseek-harness-blaxel-sandbox/0.1.2' });
+        expect(settings.headers['User-Agent'].endsWith(' deepseek-harness-blaxel-sandbox/0.1.2')).toBe(true);
+    });
+    it.each(['Deepseek/0.1.2', 'deepseek-harness', 'deepseek/0.1', 'a/1.0.0 b/1.0.0', 'deepseek/0.1.2 (extra)', ' x/1.0.0', 'x/1.0.0\n', 'x/1.0.0\r\n'])('ignores the invalid token %j', async (value) => {
+        const settings = await authenticated();
+        settings.integration = value;
+        expect(settings.integration).toBe('');
+        expect(settings.headers['User-Agent']).toMatch(new RegExp(sdkUserAgent.source + '$'));
+    });
+    it('changes no header other than User-Agent', async () => {
+        const settings = await authenticated();
+        const plain = { ...settings.headers };
+        settings.integration = 'deepseek-harness-blaxel-sandbox/0.1.2';
+        const tagged = { ...settings.headers };
+        delete plain['User-Agent'];
+        delete tagged['User-Agent'];
+        expect(tagged).toEqual(plain);
+    });
+});
+describe('Settings.integration warnings', () => {
+    it('warns once per invalid value, not on every request', async () => {
+        const { settings } = await import('./settings.js');
+        const { logger } = await import('./logger.js');
+        const warn = vi.spyOn(logger, 'warn').mockImplementation(() => { });
+        try {
+            settings.integration = 'Not-Valid';
+            for (let i = 0; i < 5; i++)
+                expect(settings.integration).toBe('');
+            expect(warn).toHaveBeenCalledTimes(1);
+            settings.integration = 'also bad';
+            expect(settings.integration).toBe('');
+            expect(warn).toHaveBeenCalledTimes(2);
+        }
+        finally {
+            warn.mockRestore();
+            delete settings.config.integration;
+        }
+    });
+});

package/dist/esm/index.js

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

@@ -2,6 +2,7 @@ export {
 /* Export SDK functions */
 deleteFilesystemByPath, deleteNetworkProcessByPidMonitor, deleteProcessByIdentifier, deleteProcessByIdentifierKill, getFilesystemByPath, getNetworkProcessByPidPorts, putCodegenFastapplyByPath, getCodegenRerankingByPath, getProcess, getProcessByIdentifier, getProcessByIdentifierLogs, getProcessByIdentifierLogsStream, postNetworkProcessByPidMonitor, postProcess, putFilesystemByPath } 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 } from "./drive/index.js";