pmxtjs 2.26.2 → 2.27.1

package/dist/esm/pmxt/client.js

@@ -9,6 +9,7 @@ import { MarketList, } from "./models.js";
 import { ServerManager } from "./server-manager.js";
 import { buildArgsWithOptionalOptions } from "./args.js";
 import { PmxtError, fromServerError } from "./errors.js";
+import { resolvePmxtBaseUrl } from "./constants.js";
 /**
  * Resolve a MarketOutcome shorthand to a plain outcome ID string.
  * Accepts either a raw string ID or a MarketOutcome object.
@@ -18,6 +19,51 @@ function resolveOutcomeId(input) {
         return input;
     return input.outcomeId;
 }
+/**
+ * Build a URL-encoded query string from a plain record.
+ *
+ * - `undefined` / `null` values are skipped (they shouldn't appear in the URL).
+ * - Arrays are serialised as repeated `key=v1&key=v2` pairs.
+ * - Nested objects are skipped here; callers should route such queries through
+ *   POST instead (see `queryHasNestedObject`).
+ */
+function buildSidecarQueryString(query) {
+    const parts = [];
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            for (const v of value) {
+                if (v === undefined || v === null)
+                    continue;
+                parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(v))}`);
+            }
+        }
+        else if (typeof value === 'object') {
+            // Nested objects don't round-trip through query strings. Caller
+            // should have detected this and POSTed instead.
+            continue;
+        }
+        else {
+            parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+        }
+    }
+    return parts.join('&');
+}
+/**
+ * True if any top-level value in the query is a nested object (not an array).
+ * Such queries can't be safely expressed in a query string, so we fall back
+ * to POST to preserve the original argument shape.
+ */
+function queryHasNestedObject(query) {
+    for (const value of Object.values(query)) {
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value === 'object' && !Array.isArray(value))
+            return true;
+    }
+    return false;
+}
 // Converter functions
 function convertMarket(raw) {
     const outcomes = (raw.outcomes || []).map((o) => ({
@@ -183,23 +229,47 @@ export class Exchange {
     exchangeName;
     apiKey;
     privateKey;
+    pmxtApiKey;
     proxyAddress;
     signatureType;
     api;
     config;
     serverManager;
     initPromise;
+    isHosted;
+    /**
+     * Sticky flag: set to `true` the first time a GET read is rejected by
+     * the sidecar with 404/405 (i.e. an older pmxt-core that only supports
+     * POST). While false, read methods try GET first; once flipped they
+     * POST directly and skip the GET probe for the lifetime of this client.
+     */
+    _getReadsUnsupported = false;
     constructor(exchangeName, options = {}) {
         this.exchangeName = exchangeName.toLowerCase();
         this.apiKey = options.apiKey;
         this.privateKey = options.privateKey;
         this.proxyAddress = options.proxyAddress;
         this.signatureType = options.signatureType;
-        let baseUrl = options.baseUrl || "http://localhost:3847";
-        const autoStartServer = options.autoStartServer !== false;
-        // Initialize server manager
+        // Resolve base URL + hosted API key via the shared precedence
+        // rules. See constants.ts for the full resolution table.
+        const resolved = resolvePmxtBaseUrl({
+            baseUrl: options.baseUrl,
+            pmxtApiKey: options.pmxtApiKey,
+        });
+        const baseUrl = resolved.baseUrl;
+        this.pmxtApiKey = resolved.pmxtApiKey;
+        this.isHosted = resolved.isHosted;
+        // auto_start_server defaults: true for local, false for hosted.
+        // An explicit value in the options always wins.
+        const autoStartServer = options.autoStartServer !== undefined
+            ? options.autoStartServer
+            : !this.isHosted;
+        // Initialize server manager (no network calls happen here — the
+        // constructor just stores config).
         this.serverManager = new ServerManager({ baseUrl });
-        // Configure the API client with the initial base URL (will be updated if port changes)
+        // Configure the API client with the initial base URL (will be
+        // updated to the actual listen port if the local sidecar gets
+        // bumped off the default).
         this.config = new Configuration({ basePath: baseUrl });
         this.api = new DefaultApi(this.config);
         // Initialize the server connection asynchronously
@@ -249,10 +319,19 @@ export class Exchange {
     }
     getAuthHeaders() {
         const headers = { ...this.config.headers };
+        // Local sidecar access token (read from the lock file). Only
+        // meaningful when talking to a local sidecar we spawned
+        // ourselves; harmless elsewhere.
         const accessToken = this.serverManager.getAccessToken();
         if (accessToken) {
             headers['x-pmxt-access-token'] = accessToken;
         }
+        // Hosted pmxt bearer token. The hosted service requires this;
+        // the local sidecar ignores it. Safe to attach unconditionally
+        // whenever a pmxtApiKey has been resolved.
+        if (this.pmxtApiKey) {
+            headers['Authorization'] = `Bearer ${this.pmxtApiKey}`;
+        }
         return headers;
     }
     // Low-Level API Access
@@ -303,6 +382,68 @@ export class Exchange {
             throw new PmxtError(`Failed to call API '${operationId}': ${error}`);
         }
     }
+    /**
+     * Dispatch a sidecar read method, preferring GET but transparently
+     * falling back to POST for full backward compatibility.
+     *
+     * GET is used when:
+     *   - the client has no per-instance credentials (the sidecar's GET
+     *     handler intentionally drops credentials to avoid leaking them
+     *     through query strings and access logs), and
+     *   - the sidecar hasn't already returned 404/405 for a previous GET
+     *     in this client's lifetime (`_getReadsUnsupported`), and
+     *   - the query has no nested objects (query strings can't round-trip
+     *     arbitrary JSON).
+     *
+     * Otherwise (or if the GET attempt is rejected with 404/405) the call
+     * is sent as POST with the original `{args, credentials}` body so that
+     * SDK users talking to an older pmxt-core continue to work unchanged.
+     *
+     * @internal — shared transport used by every generated read method.
+     */
+    async sidecarReadRequest(methodName, query, args) {
+        const baseUrl = `${this.config.basePath}/api/${this.exchangeName}/${methodName}`;
+        const hasCredentials = this.getCredentials() !== undefined;
+        if (!hasCredentials && !this._getReadsUnsupported && !queryHasNestedObject(query)) {
+            const qs = buildSidecarQueryString(query);
+            const getUrl = qs ? `${baseUrl}?${qs}` : baseUrl;
+            const response = await fetch(getUrl, {
+                method: 'GET',
+                headers: this.getAuthHeaders(),
+            });
+            // 404 / 405 => older sidecar without GET dispatch. Remember
+            // the downgrade so future calls skip the probe, and fall
+            // through to POST below.
+            if (response.status === 404 || response.status === 405) {
+                await response.text().catch(() => undefined);
+                this._getReadsUnsupported = true;
+            }
+            else {
+                if (!response.ok) {
+                    const body = await response.json().catch(() => ({}));
+                    if (body.error && typeof body.error === "object") {
+                        throw fromServerError(body.error);
+                    }
+                    throw new PmxtError(body.error?.message || response.statusText);
+                }
+                return response.json();
+            }
+        }
+        // POST fallback — identical to the original per-method template.
+        const response = await fetch(baseUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
+            body: JSON.stringify({ args, credentials: this.getCredentials() }),
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({}));
+            if (body.error && typeof body.error === "object") {
+                throw fromServerError(body.error);
+            }
+            throw new PmxtError(body.error?.message || response.statusText);
+        }
+        return response.json();
+    }
     // BEGIN GENERATED METHODS
     async loadMarkets(reload = false) {
         await this.initPromise;
@@ -339,19 +480,8 @@ export class Exchange {
         await this.initPromise;
         try {
             const args = buildArgsWithOptionalOptions(params);
-            const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchMarkets`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-                body: JSON.stringify({ args, credentials: this.getCredentials() }),
-            });
-            if (!response.ok) {
-                const body = await response.json().catch(() => ({}));
-                if (body.error && typeof body.error === "object") {
-                    throw fromServerError(body.error);
-                }
-                throw new PmxtError(body.error?.message || response.statusText);
-            }
-            const json = await response.json();
+            const query = { ...(params || {}) };
+            const json = await this.sidecarReadRequest('fetchMarkets', query, args);
             const data = this.handleResponse(json);
             return data.map(convertMarket);
         }
@@ -365,19 +495,8 @@ export class Exchange {
         await this.initPromise;
         try {
             const args = buildArgsWithOptionalOptions(params);
-            const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchMarketsPaginated`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-                body: JSON.stringify({ args, credentials: this.getCredentials() }),
-            });
-            if (!response.ok) {
-                const body = await response.json().catch(() => ({}));
-                if (body.error && typeof body.error === "object") {
-                    throw fromServerError(body.error);
-                }
-                throw new PmxtError(body.error?.message || response.statusText);
-            }
-            const json = await response.json();
+            const query = { ...(params || {}) };
+            const json = await this.sidecarReadRequest('fetchMarketsPaginated', query, args);
             const data = this.handleResponse(json);
             return {
                 data: (data.data || []).map(convertMarket),
@@ -395,19 +514,8 @@ export class Exchange {
         await this.initPromise;
         try {
             const args = buildArgsWithOptionalOptions(params);
-            const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchEvents`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-                body: JSON.stringify({ args, credentials: this.getCredentials() }),
-            });
-            if (!response.ok) {
-                const body = await response.json().catch(() => ({}));
-                if (body.error && typeof body.error === "object") {
-                    throw fromServerError(body.error);
-                }
-                throw new PmxtError(body.error?.message || response.statusText);
-            }
-            const json = await response.json();
+            const query = { ...(params || {}) };
+            const json = await this.sidecarReadRequest('fetchEvents', query, args);
             const data = this.handleResponse(json);
             return data.map(convertEvent);
         }
@@ -421,19 +529,8 @@ export class Exchange {
         await this.initPromise;
         try {
             const args = buildArgsWithOptionalOptions(params);
-            const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchMarket`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-                body: JSON.stringify({ args, credentials: this.getCredentials() }),
-            });
-            if (!response.ok) {
-                const body = await response.json().catch(() => ({}));
-                if (body.error && typeof body.error === "object") {
-                    throw fromServerError(body.error);
-                }
-                throw new PmxtError(body.error?.message || response.statusText);
-            }
-            const json = await response.json();
+            const query = { ...(params || {}) };
+            const json = await this.sidecarReadRequest('fetchMarket', query, args);
             const data = this.handleResponse(json);
             return convertMarket(data);
         }
@@ -447,19 +544,8 @@ export class Exchange {
         await this.initPromise;
         try {
             const args = buildArgsWithOptionalOptions(params);
-            const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchEvent`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-                body: JSON.stringify({ args, credentials: this.getCredentials() }),
-            });
-            if (!response.ok) {
-                const body = await response.json().catch(() => ({}));
-                if (body.error && typeof body.error === "object") {
-                    throw fromServerError(body.error);
-                }
-                throw new PmxtError(body.error?.message || response.statusText);
-            }
-            const json = await response.json();
+            const query = { ...(params || {}) };
+            const json = await this.sidecarReadRequest('fetchEvent', query, args);
             const data = this.handleResponse(json);
             return convertEvent(data);
         }
@@ -473,21 +559,9 @@ export class Exchange {
         await this.initPromise;
         const resolvedId = resolveOutcomeId(id);
         try {
-            const args = [];
-            args.push(resolvedId);
-            const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchOrderBook`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-                body: JSON.stringify({ args, credentials: this.getCredentials() }),
-            });
-            if (!response.ok) {
-                const body = await response.json().catch(() => ({}));
-                if (body.error && typeof body.error === "object") {
-                    throw fromServerError(body.error);
-                }
-                throw new PmxtError(body.error?.message || response.statusText);
-            }
-            const json = await response.json();
+            const args = [resolvedId];
+            const query = { id: resolvedId };
+            const json = await this.sidecarReadRequest('fetchOrderBook', query, args);
             const data = this.handleResponse(json);
             return convertOrderBook(data);
         }
@@ -527,21 +601,9 @@ export class Exchange {
     async fetchOrder(orderId) {
         await this.initPromise;
         try {
-            const args = [];
-            args.push(orderId);
-            const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchOrder`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-                body: JSON.stringify({ args, credentials: this.getCredentials() }),
-            });
-            if (!response.ok) {
-                const body = await response.json().catch(() => ({}));
-                if (body.error && typeof body.error === "object") {
-                    throw fromServerError(body.error);
-                }
-                throw new PmxtError(body.error?.message || response.statusText);
-            }
-            const json = await response.json();
+            const args = [orderId];
+            const query = { orderId };
+            const json = await this.sidecarReadRequest('fetchOrder', query, args);
             const data = this.handleResponse(json);
             return convertOrder(data);
         }
@@ -555,19 +617,8 @@ export class Exchange {
         await this.initPromise;
         try {
             const args = buildArgsWithOptionalOptions(marketId);
-            const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchOpenOrders`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-                body: JSON.stringify({ args, credentials: this.getCredentials() }),
-            });
-            if (!response.ok) {
-                const body = await response.json().catch(() => ({}));
-                if (body.error && typeof body.error === "object") {
-                    throw fromServerError(body.error);
-                }
-                throw new PmxtError(body.error?.message || response.statusText);
-            }
-            const json = await response.json();
+            const query = { marketId };
+            const json = await this.sidecarReadRequest('fetchOpenOrders', query, args);
             const data = this.handleResponse(json);
             return data.map(convertOrder);
         }
@@ -581,19 +632,8 @@ export class Exchange {
         await this.initPromise;
         try {
             const args = buildArgsWithOptionalOptions(params);
-            const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchMyTrades`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-                body: JSON.stringify({ args, credentials: this.getCredentials() }),
-            });
-            if (!response.ok) {
-                const body = await response.json().catch(() => ({}));
-                if (body.error && typeof body.error === "object") {
-                    throw fromServerError(body.error);
-                }
-                throw new PmxtError(body.error?.message || response.statusText);
-            }
-            const json = await response.json();
+            const query = { ...(params || {}) };
+            const json = await this.sidecarReadRequest('fetchMyTrades', query, args);
             const data = this.handleResponse(json);
             return data.map(convertUserTrade);
         }
@@ -607,19 +647,8 @@ export class Exchange {
         await this.initPromise;
         try {
             const args = buildArgsWithOptionalOptions(params);
-            const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchClosedOrders`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-                body: JSON.stringify({ args, credentials: this.getCredentials() }),
-            });
-            if (!response.ok) {
-                const body = await response.json().catch(() => ({}));
-                if (body.error && typeof body.error === "object") {
-                    throw fromServerError(body.error);
-                }
-                throw new PmxtError(body.error?.message || response.statusText);
-            }
-            const json = await response.json();
+            const query = { ...(params || {}) };
+            const json = await this.sidecarReadRequest('fetchClosedOrders', query, args);
             const data = this.handleResponse(json);
             return data.map(convertOrder);
         }
@@ -633,19 +662,8 @@ export class Exchange {
         await this.initPromise;
         try {
             const args = buildArgsWithOptionalOptions(params);
-            const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchAllOrders`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-                body: JSON.stringify({ args, credentials: this.getCredentials() }),
-            });
-            if (!response.ok) {
-                const body = await response.json().catch(() => ({}));
-                if (body.error && typeof body.error === "object") {
-                    throw fromServerError(body.error);
-                }
-                throw new PmxtError(body.error?.message || response.statusText);
-            }
-            const json = await response.json();
+            const query = { ...(params || {}) };
+            const json = await this.sidecarReadRequest('fetchAllOrders', query, args);
             const data = this.handleResponse(json);
             return data.map(convertOrder);
         }
@@ -659,19 +677,8 @@ export class Exchange {
         await this.initPromise;
         try {
             const args = address ? [address] : [];
-            const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchPositions`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-                body: JSON.stringify({ args, credentials: this.getCredentials() }),
-            });
-            if (!response.ok) {
-                const body = await response.json().catch(() => ({}));
-                if (body.error && typeof body.error === "object") {
-                    throw fromServerError(body.error);
-                }
-                throw new PmxtError(body.error?.message || response.statusText);
-            }
-            const json = await response.json();
+            const query = { address };
+            const json = await this.sidecarReadRequest('fetchPositions', query, args);
             const data = this.handleResponse(json);
             return data.map(convertPosition);
         }
@@ -685,19 +692,8 @@ export class Exchange {
         await this.initPromise;
         try {
             const args = address ? [address] : [];
-            const response = await fetch(`${this.config.basePath}/api/${this.exchangeName}/fetchBalance`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-                body: JSON.stringify({ args, credentials: this.getCredentials() }),
-            });
-            if (!response.ok) {
-                const body = await response.json().catch(() => ({}));
-                if (body.error && typeof body.error === "object") {
-                    throw fromServerError(body.error);
-                }
-                throw new PmxtError(body.error?.message || response.statusText);
-            }
-            const json = await response.json();
+            const query = { address };
+            const json = await this.sidecarReadRequest('fetchBalance', query, args);
             const data = this.handleResponse(json);
             return data.map(convertBalance);
         }
@@ -764,15 +760,10 @@ export class Exchange {
             if (params.limit) {
                 paramsDict.limit = params.limit;
             }
-            const requestBody = {
-                args: [resolvedOutcomeId, paramsDict],
-                credentials: this.getCredentials()
-            };
-            const response = await this.api.fetchOHLCV({
-                exchange: this.exchangeName,
-                fetchOHLCVRequest: requestBody,
-            }, { headers: this.getAuthHeaders() });
-            const data = this.handleResponse(response);
+            const args = [resolvedOutcomeId, paramsDict];
+            const query = { id: resolvedOutcomeId, ...paramsDict };
+            const json = await this.sidecarReadRequest('fetchOHLCV', query, args);
+            const data = this.handleResponse(json);
             return data.map(convertCandle);
         }
         catch (error) {
@@ -798,15 +789,10 @@ export class Exchange {
             if (params.limit) {
                 paramsDict.limit = params.limit;
             }
-            const requestBody = {
-                args: [resolvedOutcomeId, paramsDict],
-                credentials: this.getCredentials()
-            };
-            const response = await this.api.fetchTrades({
-                exchange: this.exchangeName,
-                fetchTradesRequest: requestBody,
-            }, { headers: this.getAuthHeaders() });
-            const data = this.handleResponse(response);
+            const args = [resolvedOutcomeId, paramsDict];
+            const query = { id: resolvedOutcomeId, ...paramsDict };
+            const json = await this.sidecarReadRequest('fetchTrades', query, args);
+            const data = this.handleResponse(json);
             return data.map(convertTrade);
         }
         catch (error) {

package/dist/esm/pmxt/constants.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared URL and environment-variable constants for the pmxt SDK.
+ *
+ * These are deliberately plain exports (no runtime logic) so that they
+ * can be imported from any module without creating import cycles.
+ */
+/**
+ * The hosted pmxt production endpoint.
+ *
+ * Exchange classes and `Router` default to this URL whenever a hosted
+ * pmxt API key is supplied (via `pmxtApiKey` kwarg or the
+ * `PMXT_API_KEY` environment variable) AND no explicit `baseUrl` /
+ * `PMXT_BASE_URL` is configured.
+ */
+export declare const HOSTED_URL = "https://api.pmxt.dev";
+/**
+ * The local sidecar default.
+ *
+ * This is the URL the SDK uses when no hosted key and no explicit
+ * override are present. It matches the port that the pmxt-core
+ * sidecar listens on by default.
+ */
+export declare const LOCAL_URL = "http://localhost:3847";
+/**
+ * Environment variable names. Centralised so tests and docs can
+ * reference a single source of truth.
+ */
+export declare const ENV: {
+    readonly BASE_URL: "PMXT_BASE_URL";
+    readonly API_KEY: "PMXT_API_KEY";
+};
+/**
+ * Resolve the effective base URL for an SDK client, following the
+ * documented precedence rules:
+ *
+ *   1. Explicit `baseUrl` argument wins.
+ *   2. `PMXT_BASE_URL` environment variable.
+ *   3. If a hosted API key is present (argument or `PMXT_API_KEY` env),
+ *      default to {@link HOSTED_URL}.
+ *   4. Otherwise, default to {@link LOCAL_URL}.
+ *
+ * Returns both the resolved URL and an `isHosted` flag (true iff the
+ * resolved URL is anything other than the local sidecar default).
+ */
+export declare function resolvePmxtBaseUrl(args: {
+    baseUrl?: string;
+    pmxtApiKey?: string;
+    env?: NodeJS.ProcessEnv;
+}): {
+    baseUrl: string;
+    pmxtApiKey?: string;
+    isHosted: boolean;
+};

package/dist/esm/pmxt/constants.js

@@ -0,0 +1,60 @@
+/**
+ * Shared URL and environment-variable constants for the pmxt SDK.
+ *
+ * These are deliberately plain exports (no runtime logic) so that they
+ * can be imported from any module without creating import cycles.
+ */
+/**
+ * The hosted pmxt production endpoint.
+ *
+ * Exchange classes and `Router` default to this URL whenever a hosted
+ * pmxt API key is supplied (via `pmxtApiKey` kwarg or the
+ * `PMXT_API_KEY` environment variable) AND no explicit `baseUrl` /
+ * `PMXT_BASE_URL` is configured.
+ */
+export const HOSTED_URL = "https://api.pmxt.dev";
+/**
+ * The local sidecar default.
+ *
+ * This is the URL the SDK uses when no hosted key and no explicit
+ * override are present. It matches the port that the pmxt-core
+ * sidecar listens on by default.
+ */
+export const LOCAL_URL = "http://localhost:3847";
+/**
+ * Environment variable names. Centralised so tests and docs can
+ * reference a single source of truth.
+ */
+export const ENV = {
+    BASE_URL: "PMXT_BASE_URL",
+    API_KEY: "PMXT_API_KEY",
+};
+/**
+ * Resolve the effective base URL for an SDK client, following the
+ * documented precedence rules:
+ *
+ *   1. Explicit `baseUrl` argument wins.
+ *   2. `PMXT_BASE_URL` environment variable.
+ *   3. If a hosted API key is present (argument or `PMXT_API_KEY` env),
+ *      default to {@link HOSTED_URL}.
+ *   4. Otherwise, default to {@link LOCAL_URL}.
+ *
+ * Returns both the resolved URL and an `isHosted` flag (true iff the
+ * resolved URL is anything other than the local sidecar default).
+ */
+export function resolvePmxtBaseUrl(args) {
+    const env = args.env ?? (typeof process !== "undefined" ? process.env : {});
+    const pmxtApiKey = args.pmxtApiKey ?? env[ENV.API_KEY] ?? undefined;
+    const pick = (url) => ({
+        baseUrl: url,
+        pmxtApiKey,
+        isHosted: url !== LOCAL_URL,
+    });
+    if (args.baseUrl)
+        return pick(args.baseUrl);
+    if (env[ENV.BASE_URL])
+        return pick(env[ENV.BASE_URL]);
+    if (pmxtApiKey)
+        return pick(HOSTED_URL);
+    return pick(LOCAL_URL);
+}