@blaxel/core 0.3.25-preview.307 → 0.3.26-preview.309

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.25-preview.307";
-const BUILD_COMMIT = "fb45a5005d56241cc56b832f6a624248e8e34f9f";
+const BUILD_VERSION = "0.3.26-preview.309";
+const BUILD_COMMIT = "314ba709f1a271c3a30cea714a3b97c8e8efb144";
 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
@@ -100,8 +100,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
@@ -196,14 +202,38 @@ class Settings {
     get apiVersion() {
         return env_js_1.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_js_1.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_js_1.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/cjs-browser/common/settings.test.js

@@ -251,3 +251,73 @@ const h2_runtime_js_1 = require("./h2-runtime.js");
         });
     });
 });
+(0, vitest_1.describe)('Settings.integration', () => {
+    const sdkUserAgent = /^blaxel\/sdk\/typescript\/\S+ \([^)]+\) blaxel\/\S+/;
+    async function authenticated() {
+        const { settings } = await Promise.resolve().then(() => __importStar(require('./settings.js')));
+        settings.credentials = new apikey_js_1.ApiKey({ apiKey: 'test-key', workspace: 'test-ws' });
+        delete settings.config.integration;
+        delete process.env.BL_INTEGRATION;
+        return settings;
+    }
+    (0, vitest_1.afterEach)(async () => {
+        const { settings } = await Promise.resolve().then(() => __importStar(require('./settings.js')));
+        delete settings.config.integration;
+        delete process.env.BL_INTEGRATION;
+    });
+    (0, vitest_1.it)('sends the plain SDK User-Agent by default', async () => {
+        const settings = await authenticated();
+        (0, vitest_1.expect)(settings.integration).toBe('');
+        (0, vitest_1.expect)(settings.headers['User-Agent']).toMatch(new RegExp(sdkUserAgent.source + '$'));
+    });
+    (0, vitest_1.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'];
+        (0, vitest_1.expect)(userAgent).toMatch(sdkUserAgent);
+        (0, vitest_1.expect)(userAgent.endsWith(' deepseek-harness-blaxel-sandbox/0.1.2')).toBe(true);
+        (0, vitest_1.expect)(userAgent.split('deepseek-harness-blaxel-sandbox').length).toBe(2);
+    });
+    (0, vitest_1.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';
+        (0, vitest_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' });
+        (0, vitest_1.expect)(settings.headers['User-Agent'].endsWith(' deepseek-harness-blaxel-sandbox/0.1.2')).toBe(true);
+    });
+    vitest_1.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;
+        (0, vitest_1.expect)(settings.integration).toBe('');
+        (0, vitest_1.expect)(settings.headers['User-Agent']).toMatch(new RegExp(sdkUserAgent.source + '$'));
+    });
+    (0, vitest_1.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'];
+        (0, vitest_1.expect)(tagged).toEqual(plain);
+    });
+});
+(0, vitest_1.describe)('Settings.integration warnings', () => {
+    (0, vitest_1.it)('warns once per invalid value, not on every request', async () => {
+        const { settings } = await Promise.resolve().then(() => __importStar(require('./settings.js')));
+        const { logger } = await Promise.resolve().then(() => __importStar(require('./logger.js')));
+        const warn = vitest_1.vi.spyOn(logger, 'warn').mockImplementation(() => { });
+        try {
+            settings.integration = 'Not-Valid';
+            for (let i = 0; i < 5; i++)
+                (0, vitest_1.expect)(settings.integration).toBe('');
+            (0, vitest_1.expect)(warn).toHaveBeenCalledTimes(1);
+            settings.integration = 'also bad';
+            (0, vitest_1.expect)(settings.integration).toBe('');
+            (0, vitest_1.expect)(warn).toHaveBeenCalledTimes(2);
+        }
+        finally {
+            warn.mockRestore();
+            delete settings.config.integration;
+        }
+    });
+});

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

@@ -11,6 +11,15 @@ export type Config = {
     proxy?: string;
     apikey?: string;
     workspace?: string;
+    /**
+     * Product token identifying the integration built on this SDK, appended to
+     * the `User-Agent` so Blaxel can attribute traffic to it. Format
+     * `<name>/<semver>` with a lowercase name, e.g.
+     * `"deepseek-harness-blaxel-sandbox/0.1.2"`. Also settable through
+     * `BL_INTEGRATION` or `settings.integration`. An invalid value is ignored
+     * with a warning.
+     */
+    integration?: string;
     /**
      * Disables the SDK-managed HTTP/2 transport. Defaults to `false` (H2 on);
      * set this to `true` (or `BL_DISABLE_H2=1`) to opt out of H2. Note that H2 is
@@ -89,6 +98,7 @@ export type Config = {
 };
 declare class Settings {
     private _credentials;
+    private _warnedIntegration;
     config: Config;
     constructor();
     get credentials(): Credentials;
@@ -104,6 +114,12 @@ declare class Settings {
     get commit(): string;
     get sentryDsn(): string;
     get apiVersion(): string;
+    /**
+     * Product token identifying the integration built on this SDK, or `""`.
+     * Resolved from `config.integration`, then `BL_INTEGRATION`. See `Config.integration`.
+     */
+    get integration(): string;
+    set integration(value: string | undefined);
     get headers(): Record<string, string>;
     get name(): string;
     get type(): string;