@ariestools/sdk 7.0.3

package/dist/_pkg/events/neutral/index.mjs

@@ -0,0 +1,415 @@
+// src/BaseEmitter.ts
+import { Base as Base2 } from "../../base/neutral/index.mjs";
+
+// src/Events/Events.ts
+import { assertEx } from "../../assert/neutral/index.mjs";
+import { Base } from "../../base/neutral/index.mjs";
+import { handleError } from "../../error/neutral/index.mjs";
+import { forget } from "../../forget/neutral/index.mjs";
+import { isDefined } from "../../typeof/neutral/index.mjs";
+var NO_META_EVENT_ERROR_MESSAGE = "`eventName` cannot be meta event `listenerAdded` or `listenerRemoved`";
+var processGlobal = globalThis;
+var resolvedPromise = Promise.resolve();
+var isMetaEvent = (eventName) => eventName === "listenerAdded" || eventName === "listenerRemoved";
+var Events = class _Events extends Base {
+  static anyMap = /* @__PURE__ */ new WeakMap();
+  static eventsMap = /* @__PURE__ */ new WeakMap();
+  static isGlobalDebugEnabled = false;
+  // this is here to be able to query the type, not use
+  eventData = {};
+  _canEmitMetaEvents = false;
+  constructor(params = {}) {
+    const mutatedParams = { ...params };
+    if (mutatedParams.debug) {
+      mutatedParams.debug.logger ??= (type, debugName, eventName, eventData) => {
+        let eventDataString;
+        try {
+          eventDataString = JSON.stringify(eventData);
+        } catch {
+          eventDataString = `Object with the following keys failed to stringify: ${Object.keys(eventData ?? {}).join(",")}`;
+        }
+        const eventNameString = typeof eventName === "symbol" || typeof eventName === "number" ? eventName.toString() : eventName;
+        const currentTime = /* @__PURE__ */ new Date();
+        const logTime = `${currentTime.getHours()}:${currentTime.getMinutes()}:${currentTime.getSeconds()}.${currentTime.getMilliseconds()}`;
+        this.logger?.log(`[${logTime}][events:${type}][${debugName}] Event Name: ${eventNameString}
+	data: ${eventDataString}`);
+      };
+    }
+    super(mutatedParams);
+    _Events.anyMap.set(this, /* @__PURE__ */ new Set());
+    _Events.eventsMap.set(this, /* @__PURE__ */ new Map());
+  }
+  /** Whether debug mode is enabled globally or via the DEBUG environment variable. */
+  static get isDebugEnabled() {
+    if (typeof processGlobal.process?.env !== "object") {
+      return this.isGlobalDebugEnabled;
+    }
+    const env = processGlobal.process?.env;
+    return env?.DEBUG === "events" || env?.DEBUG === "*" || this.isGlobalDebugEnabled;
+  }
+  static set isDebugEnabled(newValue) {
+    this.isGlobalDebugEnabled = newValue;
+  }
+  /** The debug configuration for this instance, if provided. */
+  get debug() {
+    return this.params.debug;
+  }
+  /**
+   * Removes all listeners for the specified event name(s).
+   * @param eventNames - One or more event names to clear listeners for.
+   */
+  clearListeners(eventNames) {
+    const eventNamesArray = Array.isArray(eventNames) ? eventNames : [eventNames];
+    for (const eventName of eventNamesArray) {
+      this.logIfDebugEnabled("clear", eventName);
+      if (typeof eventName === "string" || typeof eventName === "symbol" || typeof eventName === "number") {
+        const set = this.getListeners(eventName);
+        if (set) {
+          set.clear();
+        }
+      } else {
+        _Events.anyMap.get(this)?.clear();
+        const eventEntries = assertEx(_Events.eventsMap.get(this));
+        for (const [eventName2, listeners] of eventEntries) {
+          listeners.clear();
+          _Events.eventsMap.get(this)?.delete(eventName2);
+        }
+      }
+    }
+  }
+  /**
+   * Emits an event, invoking all registered listeners concurrently.
+   * @param eventName - The event to emit.
+   * @param eventArgs - The data to pass to listeners.
+   */
+  async emit(eventName, eventArgs) {
+    return await this.emitInternal(eventName, eventArgs);
+  }
+  /**
+   * Emits an internal meta event (listenerAdded or listenerRemoved).
+   * @param eventName - The meta event name.
+   * @param eventArgs - The meta event data containing listener and event information.
+   * @returns True if the meta event was emitted successfully.
+   */
+  async emitMetaEvent(eventName, eventArgs) {
+    if (isMetaEvent(eventName)) {
+      try {
+        this._canEmitMetaEvents = true;
+        await this.emitMetaEventInternal(eventName, eventArgs);
+        return true;
+      } finally {
+        this._canEmitMetaEvents = false;
+      }
+    }
+  }
+  /**
+   * Emits an event, invoking all registered listeners sequentially in order.
+   * @param eventName - The event to emit.
+   * @param eventArgs - The data to pass to listeners.
+   */
+  async emitSerial(eventName, eventArgs) {
+    if (isMetaEvent(eventName) && !this._canEmitMetaEvents) {
+      throw new TypeError(NO_META_EVENT_ERROR_MESSAGE);
+    }
+    const filterMatch = (args, filter) => {
+      switch (typeof filter) {
+        case "object": {
+          if (filter === null || args === null || typeof args !== "object") return args === filter;
+          return Object.entries(args).reduce((prev, [key, value]) => filter[key] === value ? true : prev, false);
+        }
+        default: {
+          return args === filter;
+        }
+      }
+    };
+    this.logIfDebugEnabled("emitSerial", eventName, eventArgs);
+    const listeners = this.getListeners(eventName) ?? /* @__PURE__ */ new Set();
+    const filteredListeners = [...listeners].filter((value) => isDefined(value.filter) ? filterMatch(eventArgs, value.filter) : true).map((info) => info.listener);
+    const anyListeners = assertEx(_Events.anyMap.get(this));
+    const staticListeners = [...filteredListeners];
+    const staticAnyListeners = [...anyListeners];
+    await resolvedPromise;
+    for (const listener of staticListeners) {
+      await this.safeCallListener(eventName, eventArgs, listener);
+    }
+    for (const listener of staticAnyListeners) {
+      await this.safeCallAnyListener(eventName, eventArgs, listener);
+    }
+  }
+  /**
+   * Returns the total number of listeners registered for the specified event name(s).
+   * @param eventNames - One or more event names to count listeners for.
+   * @returns The total listener count.
+   */
+  // TODO: Make test for this
+  listenerCount(eventNames) {
+    const eventNamesArray = Array.isArray(eventNames) ? eventNames : [eventNames];
+    let count = 0;
+    for (const eventName of eventNamesArray) {
+      if (typeof eventName === "string") {
+        count += assertEx(_Events.anyMap.get(this)).size + (this.getListeners(eventName)?.size ?? 0);
+        continue;
+      }
+      count += assertEx(_Events.anyMap.get(this)).size;
+      const eventListeners = assertEx(_Events.eventsMap.get(this)).values();
+      for (const value of eventListeners) {
+        count += value.size;
+      }
+    }
+    return count;
+  }
+  /**
+   * Logs debug information if debug mode is enabled.
+   * @param type - The type of operation being logged.
+   * @param eventName - The event name, if applicable.
+   * @param eventArgs - The event data, if applicable.
+   */
+  logIfDebugEnabled(type, eventName, eventArgs) {
+    if (_Events.isDebugEnabled || this.debug?.enabled === true) {
+      this.debug?.logger?.(type, this.debug.name, eventName, eventArgs);
+    }
+  }
+  /**
+   * Removes a specific listener from the specified event name(s).
+   * @param eventNames - One or more event names to unsubscribe from.
+   * @param listener - The listener to remove.
+   */
+  off(eventNames, listener) {
+    const eventNamesArray = Array.isArray(eventNames) ? eventNames : [eventNames];
+    for (const eventName of eventNamesArray) {
+      const set = this.getListeners(eventName);
+      if (set) {
+        set.delete(listener);
+        if (set.size === 0) {
+          const events = _Events.eventsMap.get(this);
+          events?.delete(eventName);
+        }
+      }
+      this.logIfDebugEnabled("unsubscribe", eventName);
+      if (!isMetaEvent(eventName)) {
+        forget(this.emitMetaEvent("listenerRemoved", { eventName, listener }));
+      }
+    }
+  }
+  /**
+   * Removes a wildcard listener that was receiving all events.
+   * @param listener - The wildcard listener to remove.
+   */
+  offAny(listener) {
+    this.logIfDebugEnabled("unsubscribeAny");
+    const typedMap = _Events.anyMap.get(this);
+    typedMap?.delete(listener);
+    forget(this.emitMetaEvent("listenerRemoved", { listener }));
+  }
+  /**
+   * Subscribes a listener to the specified event name(s).
+   * @param eventNames - One or more event names to listen for.
+   * @param listener - The callback to invoke when the event fires.
+   * @param filter - Optional filter to selectively invoke the listener based on event data.
+   * @returns An unsubscribe function.
+   */
+  on(eventNames, listener, filter) {
+    const eventNamesArray = Array.isArray(eventNames) ? eventNames : [eventNames];
+    for (const eventName of eventNamesArray) {
+      let set = this.getListeners(eventName);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        const events = _Events.eventsMap.get(this);
+        events?.set(eventName, set);
+      }
+      set.add({ filter, listener });
+      this.logIfDebugEnabled("subscribe", eventName);
+      if (!isMetaEvent(eventName)) {
+        forget(this.emitMetaEvent("listenerAdded", { eventName, listener }));
+      }
+    }
+    return this.off.bind(this, eventNames, listener);
+  }
+  /**
+   * Subscribes a wildcard listener that receives all events.
+   * @param listener - The callback to invoke for any event.
+   * @returns An unsubscribe function.
+   */
+  onAny(listener) {
+    this.logIfDebugEnabled("subscribeAny");
+    _Events.anyMap.get(this)?.add(listener);
+    forget(this.emitMetaEvent("listenerAdded", { listener }));
+    return this.offAny.bind(this, listener);
+  }
+  /**
+   * Subscribes a listener that will be invoked only once for the specified event, then automatically removed.
+   * @param eventName - The event to listen for.
+   * @param listener - The callback to invoke once.
+   * @returns An unsubscribe function.
+   */
+  once(eventName, listener) {
+    const subListener = async (args) => {
+      this.off(eventName, subListener);
+      await this.safeCallListener(eventName, args, listener);
+    };
+    this.on(eventName, subListener);
+    return this.off.bind(this, eventName, subListener);
+  }
+  async emitInternal(eventName, eventArgs, filter) {
+    if (isMetaEvent(eventName) && !this._canEmitMetaEvents) {
+      throw new TypeError(NO_META_EVENT_ERROR_MESSAGE);
+    }
+    this.logIfDebugEnabled("emit", eventName, eventArgs);
+    const listeners = this.getListeners(eventName) ?? /* @__PURE__ */ new Set();
+    const filteredListeners = [...listeners].filter((value) => isDefined(filter) ? isDefined(value.listener) : true).map((info) => info.listener);
+    const anyListeners = assertEx(_Events.anyMap.get(this));
+    const staticListeners = [...filteredListeners];
+    const staticAnyListeners = isMetaEvent(eventName) ? [] : [...anyListeners];
+    await resolvedPromise;
+    await Promise.all([
+      ...staticListeners.map(async (listener) => {
+        await this.safeCallListener(eventName, eventArgs, listener);
+      }),
+      ...staticAnyListeners.map(async (listener) => {
+        if (anyListeners.has(listener)) {
+          await this.safeCallAnyListener(eventName, eventArgs, listener);
+        }
+      })
+    ]);
+  }
+  async emitMetaEventInternal(eventName, eventArgs) {
+    if (isMetaEvent(eventName) && !this._canEmitMetaEvents) {
+      throw new TypeError("`eventName` cannot be meta event `listenerAdded` or `listenerRemoved`");
+    }
+    this.logIfDebugEnabled("emit", eventName, eventArgs);
+    const listeners = this.getListeners(eventName) ?? /* @__PURE__ */ new Set();
+    const filteredListeners = [...listeners].map((info) => info.listener);
+    const anyListeners = assertEx(_Events.anyMap.get(this));
+    const staticListeners = [...filteredListeners];
+    const staticAnyListeners = isMetaEvent(eventName) ? [] : [...anyListeners];
+    await resolvedPromise;
+    await Promise.all([
+      ...staticListeners.map(async (listener) => {
+        await this.safeCallListener(eventName, eventArgs, listener);
+      }),
+      /* v8 ignore start -- race condition guard */
+      ...staticAnyListeners.map(async (listener) => {
+        if (anyListeners.has(listener)) {
+          await this.safeCallAnyListener(eventName, eventArgs, listener);
+        }
+      })
+      /* v8 ignore stop */
+    ]);
+    return true;
+  }
+  getListeners(eventName) {
+    const events = assertEx(_Events.eventsMap.get(this));
+    if (!events.has(eventName)) {
+      return;
+    }
+    return events.get(eventName);
+  }
+  async safeCallAnyListener(eventName, eventArgs, listener) {
+    try {
+      return await listener(eventName, eventArgs);
+    } catch (ex) {
+      handleError(ex, (error) => {
+        this.logger?.error(`Listener[${String(eventName)}] Excepted: ${error.message}`);
+      });
+    }
+  }
+  async safeCallListener(eventName, eventArgs, listener) {
+    try {
+      return await listener(eventArgs);
+    } catch (ex) {
+      handleError(ex, (error) => {
+        this.logger?.error(`Listener[${String(eventName)}] Excepted: ${error.message}`);
+      });
+    }
+  }
+};
+
+// src/BaseEmitter.ts
+var BaseEmitter = class extends Base2 {
+  // just here to query types
+  eventData = {};
+  events;
+  constructor(params) {
+    super(params);
+    this.events = new Events();
+  }
+  /**
+   * Removes all listeners for the specified event name(s).
+   * @param eventNames - One or more event names to clear listeners for.
+   * @returns This instance for chaining.
+   */
+  clearListeners(eventNames) {
+    this.events.clearListeners(eventNames);
+    return this;
+  }
+  /**
+   * Emits an event, invoking all registered listeners concurrently.
+   * @param eventName - The event to emit.
+   * @param eventArgs - The data to pass to listeners.
+   */
+  emit(eventName, eventArgs) {
+    return this.events.emit(eventName, eventArgs);
+  }
+  /**
+   * Emits an event, invoking all registered listeners sequentially in order.
+   * @param eventName - The event to emit.
+   * @param eventArgs - The data to pass to listeners.
+   */
+  emitSerial(eventName, eventArgs) {
+    return this.events.emitSerial(eventName, eventArgs);
+  }
+  /**
+   * Returns the total number of listeners registered for the specified event name(s).
+   * @param eventNames - One or more event names to count listeners for.
+   * @returns The total listener count.
+   */
+  listenerCount(eventNames) {
+    return this.events.listenerCount(eventNames);
+  }
+  /**
+   * Removes a specific listener from the specified event name(s).
+   * @param eventNames - One or more event names to unsubscribe from.
+   * @param listener - The listener to remove.
+   */
+  off(eventNames, listener) {
+    return this.events.off(eventNames, listener);
+  }
+  /**
+   * Removes a wildcard listener that was receiving all events.
+   * @param listener - The wildcard listener to remove.
+   */
+  offAny(listener) {
+    return this.events.offAny(listener);
+  }
+  /**
+   * Subscribes a listener to the specified event name(s).
+   * @param eventNames - One or more event names to listen for.
+   * @param listener - The callback to invoke when the event fires.
+   * @returns An unsubscribe function.
+   */
+  on(eventNames, listener) {
+    return this.events.on(eventNames, listener);
+  }
+  /**
+   * Subscribes a wildcard listener that receives all events.
+   * @param listener - The callback to invoke for any event.
+   * @returns An unsubscribe function.
+   */
+  onAny(listener) {
+    return this.events.onAny(listener);
+  }
+  /**
+   * Subscribes a listener that will be invoked only once for the specified event, then automatically removed.
+   * @param eventName - The event to listen for.
+   * @param listener - The callback to invoke once.
+   * @returns An unsubscribe function.
+   */
+  once(eventName, listener) {
+    return this.events.once(eventName, listener);
+  }
+};
+export {
+  BaseEmitter,
+  Events
+};
+//# sourceMappingURL=index.mjs.map

package/dist/_pkg/events/neutral/model/Event.d.ts

@@ -0,0 +1,21 @@
+import type { Promisable } from '../../../promise/neutral/index.ts';
+/** A valid event name, which can be any property key (string, number, or symbol). */
+export type EventName = PropertyKey;
+/** The allowed type for event argument payloads. */
+export type EventArgs = unknown;
+/** A mapping of event names to their corresponding event argument types. */
+export type EventData = object;
+/** A function returned by event subscription methods that unsubscribes the listener when called. */
+export type EventUnsubscribeFunction = () => void;
+/**
+ * A listener that receives all events regardless of name.
+ * @param eventName - The name of the emitted event.
+ * @param eventData - The data associated with the event.
+ */
+export type EventAnyListener<TEventArgs extends EventArgs = EventArgs> = (eventName: EventName, eventData: TEventArgs) => Promisable<void>;
+/**
+ * A listener for a specific event type.
+ * @param eventData - The data associated with the event.
+ */
+export type EventListener<TEventArgs extends EventArgs = EventArgs> = (eventData: TEventArgs) => Promisable<void>;
+//# sourceMappingURL=Event.d.ts.map

package/dist/_pkg/events/neutral/model/EventEmitter.d.ts

@@ -0,0 +1,25 @@
+import type { EventAnyListener, EventData, EventListener, EventUnsubscribeFunction } from './Event.ts';
+/** Interface for a typed event emitter that supports subscribing, unsubscribing, and emitting events. */
+export interface EventEmitter<T extends EventData> {
+    /** Type-level reference to the event data shape for external type queries. */
+    eventData: T;
+    /** Removes all listeners for the specified event name(s). */
+    clearListeners(eventNames: keyof T | (keyof T)[]): void;
+    /** Emits an event, invoking all registered listeners concurrently. */
+    emit<TEventName extends keyof T>(eventName: TEventName, eventArgs: T[TEventName]): Promise<void>;
+    /** Emits an event, invoking all registered listeners sequentially in order. */
+    emitSerial<TEventName extends keyof T>(eventName: TEventName, eventArgs: T[TEventName]): Promise<void>;
+    /** Returns the total number of listeners registered for the specified event name(s). */
+    listenerCount(eventNames: keyof T | (keyof T)[]): number;
+    /** Removes a specific listener from the specified event name(s). */
+    off<TEventName extends keyof T>(eventNames: TEventName | TEventName[], listener: EventListener<T[TEventName]>): void;
+    /** Removes a wildcard listener that was receiving all events. */
+    offAny(listener: EventAnyListener | Promise<void>): void;
+    /** Subscribes a listener to the specified event name(s) and returns an unsubscribe function. */
+    on<TEventName extends keyof T>(eventNames: TEventName | TEventName[], listener: EventListener<T[TEventName]>): EventUnsubscribeFunction;
+    /** Subscribes a wildcard listener that receives all events and returns an unsubscribe function. */
+    onAny(listener: EventAnyListener): EventUnsubscribeFunction;
+    /** Subscribes a listener that will be invoked only once for the specified event, then automatically removed. */
+    once<TEventName extends keyof T>(eventName: TEventName, listener: EventListener<T[TEventName]>): EventUnsubscribeFunction;
+}
+//# sourceMappingURL=EventEmitter.d.ts.map

package/dist/_pkg/events/neutral/model/index.d.ts

@@ -0,0 +1,3 @@
+export * from './Event.ts';
+export * from './EventEmitter.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/_pkg/events/neutral/model.d.ts

@@ -0,0 +1,3 @@
+export type { BaseEmitterParams, BaseEmitterParamsFields, } from './BaseEmitter.ts';
+export type * from './model/index.ts';
+//# sourceMappingURL=model.d.ts.map

package/dist/_pkg/events/neutral/model.mjs

@@ -0,0 +1 @@
+//# sourceMappingURL=model.mjs.map

package/dist/_pkg/exists/neutral/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Used to type narrow an object which is possibly null or undefined. Works well
+ * with functional Array methods. For example:
+ * @example
+ * const payloads: XyoPayload[] = boundWitness._payloads?.filter(exists) || []
+ * @param x The object which is potentially undefined or null
+ * @returns False if the object is null/undefined, true otherwise
+ */
+export declare const exists: <T>(x?: T | null) => x is NonNullable<T>;
+//# sourceMappingURL=index.d.ts.map

package/dist/_pkg/exists/neutral/index.mjs

@@ -0,0 +1,8 @@
+// src/index.ts
+var exists = (x) => {
+  return x === void 0 || x === null ? false : true;
+};
+export {
+  exists
+};
+//# sourceMappingURL=index.mjs.map

package/dist/_pkg/fetch/neutral/FetchClient.d.ts

@@ -0,0 +1,46 @@
+import { FetchError } from './FetchError.ts';
+import type { FetchJsonOptions, FetchJsonResponse } from './types.ts';
+/** Configuration for a FetchClient instance. */
+export interface FetchClientConfig extends Omit<FetchJsonOptions, 'method' | 'body'> {
+    baseURL?: string;
+    params?: Record<string, string>;
+    timeout?: number;
+    /**
+     * Determines whether a given HTTP status code should resolve or throw.
+     * Returns true to resolve, false to throw a FetchClientError (a FetchError of type 'http-status').
+     * Default: status >= 200 && status < 300 (like Axios).
+     */
+    validateStatus?: ((status: number) => boolean) | null;
+}
+/** Per-request config, extending the instance defaults. */
+export interface FetchClientRequestConfig extends FetchClientConfig {
+    data?: unknown;
+    method?: string;
+    url?: string;
+}
+/**
+ * HTTP-status error thrown when validateStatus rejects the response status code.
+ * Specialization of {@link FetchError} (type 'http-status') that also exposes the request `config`.
+ * `isFetchError` and `instanceof FetchError` both return true for it.
+ */
+export declare class FetchClientError<T = unknown> extends FetchError {
+    readonly config: FetchClientRequestConfig;
+    readonly response: FetchJsonResponse<T>;
+    constructor(message: string, response: FetchJsonResponse<T>, config: FetchClientRequestConfig);
+}
+/**
+ * Stateful, instance-based HTTP client backed by native fetch with
+ * JSON serialization and optional gzip compression via @internal/fetch.
+ */
+export declare class FetchClient {
+    defaults: FetchClientConfig;
+    constructor(defaults?: FetchClientConfig);
+    static create(config?: FetchClientConfig): FetchClient;
+    delete<T = unknown>(url: string, config?: FetchClientConfig): Promise<FetchJsonResponse<T>>;
+    get<T = unknown>(url: string, config?: FetchClientConfig): Promise<FetchJsonResponse<T>>;
+    patch<T = unknown>(url: string, data?: unknown, config?: FetchClientConfig): Promise<FetchJsonResponse<T>>;
+    post<T = unknown>(url: string, data?: unknown, config?: FetchClientConfig): Promise<FetchJsonResponse<T>>;
+    put<T = unknown>(url: string, data?: unknown, config?: FetchClientConfig): Promise<FetchJsonResponse<T>>;
+    request<T = unknown>(config: FetchClientRequestConfig): Promise<FetchJsonResponse<T>>;
+}
+//# sourceMappingURL=FetchClient.d.ts.map

package/dist/_pkg/fetch/neutral/FetchError.d.ts

@@ -0,0 +1,80 @@
+import type { FetchJsonResponse } from './types.ts';
+/**
+ * Classification of why a fetch request failed.
+ * - `dns` — host could not be resolved (ENOTFOUND, EAI_AGAIN)
+ * - `connection-refused` — the host actively refused the connection (ECONNREFUSED)
+ * - `connection-reset` — the connection was reset/broken mid-flight (ECONNRESET, EPIPE)
+ * - `connection-timeout` — the connection could not be established in time (ETIMEDOUT)
+ * - `timeout` — the request exceeded its time budget (AbortSignal.timeout, undici header/body timeouts)
+ * - `aborted` — the request was aborted by an AbortController
+ * - `tls` — a TLS/certificate problem (expired, self-signed, hostname mismatch, ...)
+ * - `unreachable` — the host or network is unreachable (EHOSTUNREACH, ENETUNREACH)
+ * - `http-status` — the response arrived but its status was rejected by validateStatus
+ * - `parse` — a successful response had a non-empty body that could not be parsed as JSON
+ * - `network` — a generic network failure with no recognizable cause (e.g. browser "Failed to fetch")
+ * - `unknown` — the failure could not be classified
+ */
+export type FetchErrorType = 'dns' | 'connection-refused' | 'connection-reset' | 'connection-timeout' | 'timeout' | 'aborted' | 'tls' | 'unreachable' | 'http-status' | 'parse' | 'network' | 'unknown';
+/**
+ * Classifies a raw error thrown by native `fetch` (or its `cause` chain) into a FetchErrorType.
+ * Recognizes DNS, connection, TLS, timeout and abort failures from Node/undici system codes
+ * and DOMException names, falling back to `network` for generic failures and `unknown` otherwise.
+ */
+export declare function classifyFetchError(error: unknown): {
+    code?: string;
+    type: FetchErrorType;
+};
+/** Context attached to a FetchError describing the request and (when available) the response. */
+export interface FetchErrorContext {
+    /** Raw response body text — set for `parse` errors so the unparseable payload can be inspected. */
+    body?: string;
+    cause?: unknown;
+    code?: string;
+    method?: string;
+    response?: FetchJsonResponse<unknown>;
+    status?: number;
+    statusText?: string;
+    type?: FetchErrorType;
+    url?: string;
+}
+/** Plain serializable shape of a FetchError, safe for logging/telemetry (no circular refs). */
+export interface FetchErrorJson {
+    code?: string;
+    message: string;
+    method?: string;
+    name: string;
+    status?: number;
+    statusText?: string;
+    type: FetchErrorType;
+    url?: string;
+}
+/**
+ * Structured error for every failure mode of the @internal/fetch stack.
+ * Carries a classified `type`, the underlying system `code` (when known), request context
+ * (`url`, `method`) and, for HTTP-status failures, the parsed `response`. The original error
+ * is preserved on `cause`. Detect with {@link isFetchError}.
+ */
+export declare class FetchError extends Error {
+    readonly __fetchErrorMarker = "$$xylabs-fetch-error";
+    readonly body?: string;
+    readonly code?: string;
+    readonly method?: string;
+    readonly response?: FetchJsonResponse<unknown>;
+    readonly status?: number;
+    readonly statusText?: string;
+    readonly type: FetchErrorType;
+    readonly url?: string;
+    constructor(message: string, context?: FetchErrorContext);
+    toJSON(): FetchErrorJson;
+}
+/** Type guard: true for any FetchError we built, robust across bundle/realm copies via a brand marker. */
+export declare function isFetchError(value: unknown): value is FetchError;
+/**
+ * Wraps a raw thrown error into a structured FetchError, classifying network failures.
+ * Idempotent: an existing FetchError is returned unchanged so wrapping at multiple layers is safe.
+ */
+export declare function toFetchError(error: unknown, context?: {
+    method?: string;
+    url?: string;
+}): FetchError;
+//# sourceMappingURL=FetchError.d.ts.map

package/dist/_pkg/fetch/neutral/FetchJsonClient.d.ts

@@ -0,0 +1,19 @@
+import type { FetchClientConfig } from './FetchClient.ts';
+import { FetchClient } from './FetchClient.ts';
+/**
+ * Pre-configured FetchClient for JSON APIs with optional gzip compression.
+ * Drop-in replacement for `@xylabs/axios`'s `axiosJson` / `AxiosJson`.
+ *
+ * Default behavior matches axiosJsonConfig():
+ * - JSON Accept/Content-Type headers
+ * - Request bodies > compressMinLength (default 1024) are gzip-compressed
+ * - Responses are parsed as JSON
+ * - Non-2xx status codes throw (like Axios default)
+ */
+export declare class FetchJsonClient extends FetchClient {
+    constructor(config?: FetchClientConfig);
+    static create(config?: FetchClientConfig): FetchJsonClient;
+}
+/** Ready-to-use JSON fetch client, equivalent to `axiosJson` from `@xylabs/axios`. */
+export declare const fetchJsonClient: FetchJsonClient;
+//# sourceMappingURL=FetchJsonClient.d.ts.map

package/dist/_pkg/fetch/neutral/fetchCompress.d.ts

@@ -0,0 +1,12 @@
+export interface FetchCompressOptions extends RequestInit {
+    /** Gzip payloads larger than this byte count. */
+    compressMinLength?: number;
+}
+/**
+ * Drop-in replacement for native `fetch` that optionally gzip-compresses the request body.
+ * When `compressMinLength` is set and the body string exceeds that threshold, the body is
+ * gzip-compressed using native compression and `Content-Encoding: gzip` is added to the headers.
+ * Returns a standard `Response` — identical to what native `fetch` returns.
+ */
+export declare function fetchCompress(url: string | URL, options?: FetchCompressOptions): Promise<Response>;
+//# sourceMappingURL=fetchCompress.d.ts.map

package/dist/_pkg/fetch/neutral/fetchJson.d.ts

@@ -0,0 +1,7 @@
+import type { FetchJsonOptions, FetchJsonResponse } from './types.ts';
+/**
+ * JSON-configured fetch with optional gzip compression on request bodies.
+ * Request bodies exceeding `compressMinLength` bytes are gzip-compressed using native compression.
+ */
+export declare function fetchJson<T>(url: string, options?: FetchJsonOptions): Promise<FetchJsonResponse<T>>;
+//# sourceMappingURL=fetchJson.d.ts.map