@ar.io/sdk 3.21.1-alpha.1 → 3.22.0-alpha.2

package/lib/cjs/cli/cli.js

@@ -448,11 +448,7 @@ const utils_js_1 = require("./utils.js");
 (0, utils_js_1.makeCommand)({
     name: 'get-ants-for-address',
     description: 'Get the list of ANTs owned by an address according to the ANT registry',
-    options: [
-        options_js_1.optionMap.address,
-        options_js_1.optionMap.antRegistryProcessId,
-        options_js_1.optionMap.hyperbeamUrl,
-    ],
+    options: [options_js_1.optionMap.address, options_js_1.optionMap.antRegistryProcessId],
     action: readCommands_js_1.listAntsForAddress,
 });
 // # ANTS

package/lib/cjs/cli/options.js

@@ -140,6 +140,10 @@ exports.optionMap = {
         description: 'The allowed delegates for the gateway. By default this is empty, meaning all are allowed delegate stake unless delegating is explicitly disallowed by the gateway',
         type: 'array',
     },
+    services: {
+        alias: '--services <services>',
+        description: 'JSON string of gateway services configuration (e.g., \'{"bundlers":[{"fqdn":"bundler.example.com","port":443,"protocol":"https","path":"/bundler"}]}\')',
+    },
     skipConfirmation: {
         alias: '--skip-confirmation',
         description: 'Skip confirmation prompts',
@@ -335,6 +339,7 @@ exports.globalOptions = [
     exports.optionMap.debug,
     exports.optionMap.arioProcessId,
     exports.optionMap.cuUrl,
+    exports.optionMap.hyperbeamUrl,
 ];
 exports.writeActionOptions = [exports.optionMap.skipConfirmation, exports.optionMap.tags];
 exports.arnsPurchaseOptions = [
@@ -406,6 +411,7 @@ exports.updateGatewaySettingsOptions = [
     exports.optionMap.fqdn,
     exports.optionMap.port,
     exports.optionMap.protocol,
+    exports.optionMap.services,
 ];
 exports.joinNetworkOptions = [
     ...exports.updateGatewaySettingsOptions,

package/lib/cjs/cli/utils.js

@@ -27,6 +27,7 @@ exports.paginationParamsFromOptions = paginationParamsFromOptions;
 exports.epochInputFromOptions = epochInputFromOptions;
 exports.requiredInitiatorFromOptions = requiredInitiatorFromOptions;
 exports.customTagsFromOptions = customTagsFromOptions;
+exports.servicesFromOptions = servicesFromOptions;
 exports.gatewaySettingsFromOptions = gatewaySettingsFromOptions;
 exports.requiredTargetAndQuantityFromOptions = requiredTargetAndQuantityFromOptions;
 exports.redelegateParamsFromOptions = redelegateParamsFromOptions;
@@ -180,6 +181,7 @@ function aoProcessFromOptions(options) {
 function readARIOFromOptions(options) {
     setLoggerIfDebug(options);
     return index_js_1.ARIO.init({
+        hyperbeamUrl: options.hyperbeamUrl,
         process: aoProcessFromOptions({
             cuUrl: 'https://cu.ardrive.io', // default to ardrive cu for ARIO process
             ...options,
@@ -226,6 +228,7 @@ function writeARIOFromOptions(options) {
             process: aoProcessFromOptions(options),
             signer,
             paymentUrl: options.paymentUrl,
+            hyperbeamUrl: options.hyperbeamUrl,
         }),
         signerAddress,
     };
@@ -333,7 +336,44 @@ function customTagsFromOptions(options) {
         tags,
     };
 }
-function gatewaySettingsFromOptions({ allowDelegatedStaking, autoStake, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, observerAddress, port, properties, allowedDelegates, }) {
+function servicesFromOptions(services) {
+    if (services === undefined || services === null || services === '') {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(services);
+        // Validate structure
+        if (!parsed.bundlers || !Array.isArray(parsed.bundlers)) {
+            throw new Error('Services must have a "bundlers" array');
+        }
+        if (parsed.bundlers.length > 20) {
+            throw new Error('Maximum 20 bundlers allowed');
+        }
+        // Validate each bundler
+        for (const bundler of parsed.bundlers) {
+            if (!bundler.fqdn || typeof bundler.fqdn !== 'string') {
+                throw new Error('Each bundler must have a valid "fqdn" string');
+            }
+            if (typeof bundler.port !== 'number' ||
+                bundler.port < 0 ||
+                bundler.port > 65535) {
+                throw new Error('Each bundler must have a valid "port" (0-65535)');
+            }
+            if (bundler.protocol !== 'https') {
+                throw new Error('Each bundler protocol must be "https"');
+            }
+            if (!bundler.path || typeof bundler.path !== 'string') {
+                throw new Error('Each bundler must have a valid "path" string');
+            }
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new Error(`Invalid services JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function gatewaySettingsFromOptions(options) {
+    const { allowDelegatedStaking, autoStake, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, observerAddress, port, properties, allowedDelegates, services, } = options;
     return {
         observerAddress,
         allowDelegatedStaking,
@@ -348,6 +388,7 @@ function gatewaySettingsFromOptions({ allowDelegatedStaking, autoStake, delegate
         note,
         port: port !== undefined ? +port : undefined,
         properties,
+        services: servicesFromOptions(services),
     };
 }
 function requiredTargetAndQuantityFromOptions(options) {

package/lib/cjs/common/hyperbeam/hb.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HB = void 0;
+const logger_js_1 = require("../logger.js");
+class HB {
+    url;
+    processId;
+    isHyperBeamCompatible;
+    checkHyperBeamPromise;
+    logger;
+    hbTimeoutMs;
+    constructor(config) {
+        this.url = config.url;
+        this.processId = config.processId;
+        this.logger = config.logger ?? logger_js_1.Logger.default;
+        this.hbTimeoutMs = config.hbTimeoutMs ?? 5000;
+        this.isHyperBeamCompatible = undefined;
+        this.checkHyperBeamPromise = this.checkHyperBeamCompatibility();
+    }
+    /**
+     * fetches the meta data for the process
+     *
+     * @returns The meta data for the process
+     *
+     * @example
+     * const hyperbeam = new Hyperbeam({ url: 'https://hyperbeam.ario.permaweb.services', processId: 'qNvAoz0TgcH7DMg8BCVn8jF32QH5L6T29VjHxhHqqGE' });
+     * const meta = await hyperbeam.meta();
+     * console.log(meta);
+     */
+    async meta() {
+        const url = new URL(`${this.url}/${this.processId}~process@1.0/meta`);
+        return this.fetchHyperbeamPath({
+            path: url.toString(),
+        });
+    }
+    /**
+     * calls the process device /now function, which evaluates the current process state pulling new messages
+     * to get the latest state
+     *
+     * @param path - The path to the hb state
+     * @param json - Whether to return the result as JSON, defaults to true
+     * @returns The result of the compute operation
+     *
+     * @example
+     * const hyperbeam = new Hyperbeam({ url: 'https://hyperbeam.ario.permaweb.services', processId: 'qNvAoz0TgcH7DMg8BCVn8jF32QH5L6T29VjHxhHqqGE' });
+     * const result = await hyperbeam.now({ path: 'balances/QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ' });
+     * console.log(result);
+     */
+    async now({ path, json = false, }) {
+        return this.fetchHyperbeamPath({
+            path: `${this.url}/${this.processId}~process@1.0/now/${path}`,
+            json,
+        });
+    }
+    /**
+     * calls the process device /compute function, which uses the currently evaluated state in the node
+     *
+     * @param path - The path to the compute resource
+     * @param json - Whether to return the result as JSON, defaults to true
+     * @returns The result of the compute operation
+     *
+     * @example
+     * const hyperbeam = new Hyperbeam({ url: 'https://hyperbeam.ario.permaweb.services', processId: 'qNvAoz0TgcH7DMg8BCVn8jF32QH5L6T29VjHxhHqqGE' });
+     * const result = await hyperbeam.compute({ path: 'balances/QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ' });
+     * console.log(result);
+     */
+    async compute({ path, json = false, }) {
+        return this.fetchHyperbeamPath({
+            path: `${this.url}/${this.processId}~process@1.0/compute/${path}`,
+            json,
+        });
+    }
+    /**
+     * Checks if the process is HyperBeam compatible and caches the result.
+     *
+     * @returns {Promise<boolean>} True if the process is HyperBeam compatible, false otherwise.
+     */
+    async checkHyperBeamCompatibility({ minSlot, } = {}) {
+        // refetch if min slot is provided
+        if (minSlot !== undefined) {
+            this.isHyperBeamCompatible = undefined;
+            this.checkHyperBeamPromise = undefined;
+        }
+        if (this.checkHyperBeamPromise !== undefined) {
+            return this.checkHyperBeamPromise;
+        }
+        if (this.isHyperBeamCompatible !== undefined) {
+            return Promise.resolve(this.isHyperBeamCompatible);
+        }
+        const result = fetch(
+        // use /now to force a refresh of the cache state, then compute when calling it for keys
+        `${this.url.toString()}/${this.processId}~process@1.0/now`, {
+            method: 'HEAD',
+            signal: AbortSignal.timeout(this.hbTimeoutMs),
+        })
+            .then(async (res) => {
+            if (res.ok) {
+                if (minSlot !== undefined) {
+                    const slotRes = await this.compute({
+                        path: 'at-slot',
+                        json: false,
+                    });
+                    const slot = Number(slotRes);
+                    if (slot < minSlot) {
+                        return false;
+                    }
+                }
+                this.isHyperBeamCompatible = true;
+                return true;
+            }
+            this.isHyperBeamCompatible = false;
+            return false;
+        })
+            .catch((error) => {
+            this.logger.debug('Failed to check HyperBeam compatibility', {
+                cause: error,
+            });
+            this.isHyperBeamCompatible = false;
+            return false;
+        });
+        this.checkHyperBeamPromise = result;
+        return result;
+    }
+    async fetchHyperbeamPath({ path, json = true, }) {
+        try {
+            const url = new URL(path);
+            if (json) {
+                this.logger.debug('Fetching path as JSON', { path });
+                /**
+                 * This is the (current) way to access data as json
+                 * the old way is /~json@1.0/serialize path
+                 */
+                url.searchParams.set('require-codec', 'application/json');
+                url.searchParams.set('accept-bundle', 'true');
+                const res = await fetch(url);
+                if (!res.ok) {
+                    throw new Error(`Failed to fetch path as JSON: ${res.statusText}`);
+                }
+                const jsonResult = await res
+                    .json()
+                    .then((json) => json)
+                    .catch((error) => {
+                    this.logger.error('Failed to parse JSON', {
+                        cause: error,
+                    });
+                    throw new Error(`Received response but failed to parse JSON: ${error.message}`);
+                });
+                if (typeof jsonResult !== 'object' ||
+                    jsonResult === null ||
+                    !('body' in jsonResult)) {
+                    throw new Error('Response body missing in JSON response');
+                }
+                return jsonResult.body;
+            }
+            else {
+                this.logger.debug('Fetching path as text', { path });
+                const res = await fetch(url);
+                if (!res.ok) {
+                    throw new Error(`Failed to fetch path: ${res.statusText}`);
+                }
+                const body = await res.text();
+                return body;
+            }
+        }
+        catch (error) {
+            this.logger.error('Failed to fetch path as JSON', {
+                cause: error,
+            });
+            throw error;
+        }
+    }
+}
+exports.HB = HB;

package/lib/cjs/common/io.js

@@ -27,6 +27,7 @@ const arweave_js_2 = require("./arweave.js");
 const ao_process_js_1 = require("./contracts/ao-process.js");
 const error_js_1 = require("./error.js");
 const faucet_js_1 = require("./faucet.js");
+const hb_js_1 = require("./hyperbeam/hb.js");
 const logger_js_1 = require("./logger.js");
 const turbo_js_1 = require("./turbo.js");
 class ARIO {
@@ -104,9 +105,9 @@ class ARIOReadable {
     hyperbeamUrl;
     paymentProvider; // TODO: this could be an array/map of payment providers
     logger = logger_js_1.Logger.default;
+    hb;
     constructor(config) {
         this.arweave = config?.arweave ?? arweave_js_2.defaultArweave;
-        this.hyperbeamUrl = config?.hyperbeamUrl;
         if (config === undefined || Object.keys(config).length === 0) {
             this.process = new ao_process_js_1.AOProcess({
                 processId: constants_js_1.ARIO_MAINNET_PROCESS_ID,
@@ -123,6 +124,19 @@ class ARIOReadable {
         else {
             throw new error_js_1.InvalidContractConfigurationError();
         }
+        // only use hyperbeam if the client has provided a hyperbeamUrl
+        // this will avoid overwhelming the HyperBeam node with requests
+        // as we shift using HyperBEAM for all ANT operations
+        if (config?.hyperbeamUrl !== undefined) {
+            this.hyperbeamUrl = config.hyperbeamUrl;
+            this.hb = new hb_js_1.HB({
+                url: this.hyperbeamUrl,
+                processId: this.process.processId,
+            });
+            this.logger.debug(`Using HyperBEAM node for process ${this.process.processId}`, {
+                hyperbeamUrl: this.hyperbeamUrl,
+            });
+        }
         this.paymentProvider = turbo_js_1.TurboArNSPaymentFactory.init({
             paymentUrl: config?.paymentUrl,
         });
@@ -222,6 +236,24 @@ class ARIOReadable {
         });
     }
     async getBalance({ address }) {
+        if (this.hb && (await this.hb.checkHyperBeamCompatibility())) {
+            this.logger.debug('Getting balance from HyperBEAM', { address });
+            const res = await this.hb
+                .compute({
+                path: `balances/${address}`,
+            })
+                .then((res) => Number(res))
+                .catch((error) => {
+                this.logger.error('Failed to get balance from HyperBEAM', {
+                    cause: error,
+                });
+                return null;
+            });
+            if (res !== null)
+                return res;
+            // else fall through to CU read
+            this.logger.info('Failed to get balance from HyperBEAM, failing over to to CU read', { address });
+        }
         return this.process.read({
             tags: [
                 { name: 'Action', value: 'Balance' },
@@ -821,7 +853,7 @@ class ARIOWriteable extends ARIOReadable {
             signer: this.signer,
         });
     }
-    async joinNetwork({ operatorStake, allowDelegatedStaking, allowedDelegates, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, port, properties, protocol, autoStake, observerAddress, }, options) {
+    async joinNetwork({ operatorStake, allowDelegatedStaking, allowedDelegates, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, port, properties, protocol, autoStake, observerAddress, services, }, options) {
         const { tags = [] } = options || {};
         const allTags = [
             ...tags,
@@ -878,6 +910,10 @@ class ARIOWriteable extends ARIOReadable {
                 name: 'Observer-Address',
                 value: observerAddress,
             },
+            {
+                name: 'Services',
+                value: services ? JSON.stringify(services) : undefined,
+            },
         ];
         return this.process.send({
             signer: this.signer,
@@ -891,7 +927,7 @@ class ARIOWriteable extends ARIOReadable {
             tags: [...tags, { name: 'Action', value: 'Leave-Network' }],
         });
     }
-    async updateGatewaySettings({ allowDelegatedStaking, allowedDelegates, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, port, properties, protocol, autoStake, observerAddress, }, options) {
+    async updateGatewaySettings({ allowDelegatedStaking, allowedDelegates, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, port, properties, protocol, autoStake, observerAddress, services, }, options) {
         const { tags = [] } = options || {};
         const allTags = [
             ...tags,
@@ -920,6 +956,10 @@ class ARIOWriteable extends ARIOReadable {
                 value: minDelegatedStake?.valueOf().toString(),
             },
             { name: 'Auto-Stake', value: autoStake?.toString() },
+            {
+                name: 'Services',
+                value: services ? JSON.stringify(services) : undefined,
+            },
         ];
         return this.process.send({
             signer: this.signer,

package/lib/cjs/version.js

@@ -17,4 +17,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.version = void 0;
 // AUTOMATICALLY GENERATED FILE - DO NOT TOUCH
-exports.version = '3.21.1-alpha.1';
+exports.version = '3.22.0-alpha.2';

package/lib/esm/cli/cli.js

@@ -446,11 +446,7 @@ makeCommand({
 makeCommand({
     name: 'get-ants-for-address',
     description: 'Get the list of ANTs owned by an address according to the ANT registry',
-    options: [
-        optionMap.address,
-        optionMap.antRegistryProcessId,
-        optionMap.hyperbeamUrl,
-    ],
+    options: [optionMap.address, optionMap.antRegistryProcessId],
     action: listAntsForAddress,
 });
 // # ANTS

package/lib/esm/cli/options.js

@@ -137,6 +137,10 @@ export const optionMap = {
         description: 'The allowed delegates for the gateway. By default this is empty, meaning all are allowed delegate stake unless delegating is explicitly disallowed by the gateway',
         type: 'array',
     },
+    services: {
+        alias: '--services <services>',
+        description: 'JSON string of gateway services configuration (e.g., \'{"bundlers":[{"fqdn":"bundler.example.com","port":443,"protocol":"https","path":"/bundler"}]}\')',
+    },
     skipConfirmation: {
         alias: '--skip-confirmation',
         description: 'Skip confirmation prompts',
@@ -332,6 +336,7 @@ export const globalOptions = [
     optionMap.debug,
     optionMap.arioProcessId,
     optionMap.cuUrl,
+    optionMap.hyperbeamUrl,
 ];
 export const writeActionOptions = [optionMap.skipConfirmation, optionMap.tags];
 export const arnsPurchaseOptions = [
@@ -403,6 +408,7 @@ export const updateGatewaySettingsOptions = [
     optionMap.fqdn,
     optionMap.port,
     optionMap.protocol,
+    optionMap.services,
 ];
 export const joinNetworkOptions = [
     ...updateGatewaySettingsOptions,

package/lib/esm/cli/utils.js

@@ -127,6 +127,7 @@ function aoProcessFromOptions(options) {
 export function readARIOFromOptions(options) {
     setLoggerIfDebug(options);
     return ARIO.init({
+        hyperbeamUrl: options.hyperbeamUrl,
         process: aoProcessFromOptions({
             cuUrl: 'https://cu.ardrive.io', // default to ardrive cu for ARIO process
             ...options,
@@ -173,6 +174,7 @@ export function writeARIOFromOptions(options) {
             process: aoProcessFromOptions(options),
             signer,
             paymentUrl: options.paymentUrl,
+            hyperbeamUrl: options.hyperbeamUrl,
         }),
         signerAddress,
     };
@@ -280,7 +282,44 @@ export function customTagsFromOptions(options) {
         tags,
     };
 }
-export function gatewaySettingsFromOptions({ allowDelegatedStaking, autoStake, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, observerAddress, port, properties, allowedDelegates, }) {
+export function servicesFromOptions(services) {
+    if (services === undefined || services === null || services === '') {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(services);
+        // Validate structure
+        if (!parsed.bundlers || !Array.isArray(parsed.bundlers)) {
+            throw new Error('Services must have a "bundlers" array');
+        }
+        if (parsed.bundlers.length > 20) {
+            throw new Error('Maximum 20 bundlers allowed');
+        }
+        // Validate each bundler
+        for (const bundler of parsed.bundlers) {
+            if (!bundler.fqdn || typeof bundler.fqdn !== 'string') {
+                throw new Error('Each bundler must have a valid "fqdn" string');
+            }
+            if (typeof bundler.port !== 'number' ||
+                bundler.port < 0 ||
+                bundler.port > 65535) {
+                throw new Error('Each bundler must have a valid "port" (0-65535)');
+            }
+            if (bundler.protocol !== 'https') {
+                throw new Error('Each bundler protocol must be "https"');
+            }
+            if (!bundler.path || typeof bundler.path !== 'string') {
+                throw new Error('Each bundler must have a valid "path" string');
+            }
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new Error(`Invalid services JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function gatewaySettingsFromOptions(options) {
+    const { allowDelegatedStaking, autoStake, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, observerAddress, port, properties, allowedDelegates, services, } = options;
     return {
         observerAddress,
         allowDelegatedStaking,
@@ -295,6 +334,7 @@ export function gatewaySettingsFromOptions({ allowDelegatedStaking, autoStake, d
         note,
         port: port !== undefined ? +port : undefined,
         properties,
+        services: servicesFromOptions(services),
     };
 }
 export function requiredTargetAndQuantityFromOptions(options) {

package/lib/esm/common/hyperbeam/hb.js

@@ -0,0 +1,169 @@
+import { Logger } from '../logger.js';
+export class HB {
+    url;
+    processId;
+    isHyperBeamCompatible;
+    checkHyperBeamPromise;
+    logger;
+    hbTimeoutMs;
+    constructor(config) {
+        this.url = config.url;
+        this.processId = config.processId;
+        this.logger = config.logger ?? Logger.default;
+        this.hbTimeoutMs = config.hbTimeoutMs ?? 5000;
+        this.isHyperBeamCompatible = undefined;
+        this.checkHyperBeamPromise = this.checkHyperBeamCompatibility();
+    }
+    /**
+     * fetches the meta data for the process
+     *
+     * @returns The meta data for the process
+     *
+     * @example
+     * const hyperbeam = new Hyperbeam({ url: 'https://hyperbeam.ario.permaweb.services', processId: 'qNvAoz0TgcH7DMg8BCVn8jF32QH5L6T29VjHxhHqqGE' });
+     * const meta = await hyperbeam.meta();
+     * console.log(meta);
+     */
+    async meta() {
+        const url = new URL(`${this.url}/${this.processId}~process@1.0/meta`);
+        return this.fetchHyperbeamPath({
+            path: url.toString(),
+        });
+    }
+    /**
+     * calls the process device /now function, which evaluates the current process state pulling new messages
+     * to get the latest state
+     *
+     * @param path - The path to the hb state
+     * @param json - Whether to return the result as JSON, defaults to true
+     * @returns The result of the compute operation
+     *
+     * @example
+     * const hyperbeam = new Hyperbeam({ url: 'https://hyperbeam.ario.permaweb.services', processId: 'qNvAoz0TgcH7DMg8BCVn8jF32QH5L6T29VjHxhHqqGE' });
+     * const result = await hyperbeam.now({ path: 'balances/QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ' });
+     * console.log(result);
+     */
+    async now({ path, json = false, }) {
+        return this.fetchHyperbeamPath({
+            path: `${this.url}/${this.processId}~process@1.0/now/${path}`,
+            json,
+        });
+    }
+    /**
+     * calls the process device /compute function, which uses the currently evaluated state in the node
+     *
+     * @param path - The path to the compute resource
+     * @param json - Whether to return the result as JSON, defaults to true
+     * @returns The result of the compute operation
+     *
+     * @example
+     * const hyperbeam = new Hyperbeam({ url: 'https://hyperbeam.ario.permaweb.services', processId: 'qNvAoz0TgcH7DMg8BCVn8jF32QH5L6T29VjHxhHqqGE' });
+     * const result = await hyperbeam.compute({ path: 'balances/QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ' });
+     * console.log(result);
+     */
+    async compute({ path, json = false, }) {
+        return this.fetchHyperbeamPath({
+            path: `${this.url}/${this.processId}~process@1.0/compute/${path}`,
+            json,
+        });
+    }
+    /**
+     * Checks if the process is HyperBeam compatible and caches the result.
+     *
+     * @returns {Promise<boolean>} True if the process is HyperBeam compatible, false otherwise.
+     */
+    async checkHyperBeamCompatibility({ minSlot, } = {}) {
+        // refetch if min slot is provided
+        if (minSlot !== undefined) {
+            this.isHyperBeamCompatible = undefined;
+            this.checkHyperBeamPromise = undefined;
+        }
+        if (this.checkHyperBeamPromise !== undefined) {
+            return this.checkHyperBeamPromise;
+        }
+        if (this.isHyperBeamCompatible !== undefined) {
+            return Promise.resolve(this.isHyperBeamCompatible);
+        }
+        const result = fetch(
+        // use /now to force a refresh of the cache state, then compute when calling it for keys
+        `${this.url.toString()}/${this.processId}~process@1.0/now`, {
+            method: 'HEAD',
+            signal: AbortSignal.timeout(this.hbTimeoutMs),
+        })
+            .then(async (res) => {
+            if (res.ok) {
+                if (minSlot !== undefined) {
+                    const slotRes = await this.compute({
+                        path: 'at-slot',
+                        json: false,
+                    });
+                    const slot = Number(slotRes);
+                    if (slot < minSlot) {
+                        return false;
+                    }
+                }
+                this.isHyperBeamCompatible = true;
+                return true;
+            }
+            this.isHyperBeamCompatible = false;
+            return false;
+        })
+            .catch((error) => {
+            this.logger.debug('Failed to check HyperBeam compatibility', {
+                cause: error,
+            });
+            this.isHyperBeamCompatible = false;
+            return false;
+        });
+        this.checkHyperBeamPromise = result;
+        return result;
+    }
+    async fetchHyperbeamPath({ path, json = true, }) {
+        try {
+            const url = new URL(path);
+            if (json) {
+                this.logger.debug('Fetching path as JSON', { path });
+                /**
+                 * This is the (current) way to access data as json
+                 * the old way is /~json@1.0/serialize path
+                 */
+                url.searchParams.set('require-codec', 'application/json');
+                url.searchParams.set('accept-bundle', 'true');
+                const res = await fetch(url);
+                if (!res.ok) {
+                    throw new Error(`Failed to fetch path as JSON: ${res.statusText}`);
+                }
+                const jsonResult = await res
+                    .json()
+                    .then((json) => json)
+                    .catch((error) => {
+                    this.logger.error('Failed to parse JSON', {
+                        cause: error,
+                    });
+                    throw new Error(`Received response but failed to parse JSON: ${error.message}`);
+                });
+                if (typeof jsonResult !== 'object' ||
+                    jsonResult === null ||
+                    !('body' in jsonResult)) {
+                    throw new Error('Response body missing in JSON response');
+                }
+                return jsonResult.body;
+            }
+            else {
+                this.logger.debug('Fetching path as text', { path });
+                const res = await fetch(url);
+                if (!res.ok) {
+                    throw new Error(`Failed to fetch path: ${res.statusText}`);
+                }
+                const body = await res.text();
+                return body;
+            }
+        }
+        catch (error) {
+            this.logger.error('Failed to fetch path as JSON', {
+                cause: error,
+            });
+            throw error;
+        }
+    }
+}