eteres 0.0.1-security → 6.7.1

package/lib.esm/utils/errors.js

@@ -0,0 +1,217 @@
+/**
+ *  All errors in ethers include properties to ensure they are both
+ *  human-readable (i.e. ``.message``) and machine-readable (i.e. ``.code``).
+ *
+ *  The [[isError]] function can be used to check the error ``code`` and
+ *  provide a type guard for the properties present on that error interface.
+ *
+ *  @_section: api/utils/errors:Errors  [about-errors]
+ */
+import { version } from "../_version.js";
+import { defineProperties } from "./properties.js";
+function stringify(value) {
+    if (value == null) {
+        return "null";
+    }
+    if (Array.isArray(value)) {
+        return "[ " + (value.map(stringify)).join(", ") + " ]";
+    }
+    if (value instanceof Uint8Array) {
+        const HEX = "0123456789abcdef";
+        let result = "0x";
+        for (let i = 0; i < value.length; i++) {
+            result += HEX[value[i] >> 4];
+            result += HEX[value[i] & 0xf];
+        }
+        return result;
+    }
+    if (typeof (value) === "object" && typeof (value.toJSON) === "function") {
+        return stringify(value.toJSON());
+    }
+    switch (typeof (value)) {
+        case "boolean":
+        case "symbol":
+            return value.toString();
+        case "bigint":
+            return BigInt(value).toString();
+        case "number":
+            return (value).toString();
+        case "string":
+            return JSON.stringify(value);
+        case "object": {
+            const keys = Object.keys(value);
+            keys.sort();
+            return "{ " + keys.map((k) => `${stringify(k)}: ${stringify(value[k])}`).join(", ") + " }";
+        }
+    }
+    return `[ COULD NOT SERIALIZE ]`;
+}
+/**
+ *  Returns true if the %%error%% matches an error thrown by ethers
+ *  that matches the error %%code%%.
+ *
+ *  In TypeScript envornoments, this can be used to check that %%error%%
+ *  matches an EthersError type, which means the expected properties will
+ *  be set.
+ *
+ *  @See [ErrorCodes](api:ErrorCode)
+ *  @example
+ *    try {
+ *      // code....
+ *    } catch (e) {
+ *      if (isError(e, "CALL_EXCEPTION")) {
+ *          // The Type Guard has validated this object
+ *          console.log(e.data);
+ *      }
+ *    }
+ */
+export function isError(error, code) {
+    return (error && error.code === code);
+}
+/**
+ *  Returns true if %%error%% is a [[CallExceptionError].
+ */
+export function isCallException(error) {
+    return isError(error, "CALL_EXCEPTION");
+}
+/**
+ *  Returns a new Error configured to the format ethers emits errors, with
+ *  the %%message%%, [[api:ErrorCode]] %%code%% and additioanl properties
+ *  for the corresponding EthersError.
+ *
+ *  Each error in ethers includes the version of ethers, a
+ *  machine-readable [[ErrorCode]], and depneding on %%code%%, additional
+ *  required properties. The error message will also include the %%meeage%%,
+ *  ethers version, %%code%% and all aditional properties, serialized.
+ */
+export function makeError(message, code, info) {
+    {
+        const details = [];
+        if (info) {
+            if ("message" in info || "code" in info || "name" in info) {
+                throw new Error(`value will overwrite populated values: ${stringify(info)}`);
+            }
+            for (const key in info) {
+                const value = (info[key]);
+                //                try {
+                details.push(key + "=" + stringify(value));
+                //                } catch (error: any) {
+                //                console.log("MMM", error.message);
+                //                    details.push(key + "=[could not serialize object]");
+                //                }
+            }
+        }
+        details.push(`code=${code}`);
+        details.push(`version=${version}`);
+        if (details.length) {
+            message += " (" + details.join(", ") + ")";
+        }
+    }
+    let error;
+    switch (code) {
+        case "INVALID_ARGUMENT":
+            error = new TypeError(message);
+            break;
+        case "NUMERIC_FAULT":
+        case "BUFFER_OVERRUN":
+            error = new RangeError(message);
+            break;
+        default:
+            error = new Error(message);
+    }
+    defineProperties(error, { code });
+    if (info) {
+        Object.assign(error, info);
+    }
+    return error;
+}
+/**
+ *  Throws an EthersError with %%message%%, %%code%% and additional error
+ *  %%info%% when %%check%% is falsish..
+ *
+ *  @see [[api:makeError]]
+ */
+export function assert(check, message, code, info) {
+    if (!check) {
+        throw makeError(message, code, info);
+    }
+}
+/**
+ *  A simple helper to simply ensuring provided arguments match expected
+ *  constraints, throwing if not.
+ *
+ *  In TypeScript environments, the %%check%% has been asserted true, so
+ *  any further code does not need additional compile-time checks.
+ */
+export function assertArgument(check, message, name, value) {
+    assert(check, message, "INVALID_ARGUMENT", { argument: name, value: value });
+}
+export function assertArgumentCount(count, expectedCount, message) {
+    if (message == null) {
+        message = "";
+    }
+    if (message) {
+        message = ": " + message;
+    }
+    assert(count >= expectedCount, "missing arguemnt" + message, "MISSING_ARGUMENT", {
+        count: count,
+        expectedCount: expectedCount
+    });
+    assert(count <= expectedCount, "too many arguemnts" + message, "UNEXPECTED_ARGUMENT", {
+        count: count,
+        expectedCount: expectedCount
+    });
+}
+const _normalizeForms = ["NFD", "NFC", "NFKD", "NFKC"].reduce((accum, form) => {
+    try {
+        // General test for normalize
+        /* c8 ignore start */
+        if ("test".normalize(form) !== "test") {
+            throw new Error("bad");
+        }
+        ;
+        /* c8 ignore stop */
+        if (form === "NFD") {
+            const check = String.fromCharCode(0xe9).normalize("NFD");
+            const expected = String.fromCharCode(0x65, 0x0301);
+            /* c8 ignore start */
+            if (check !== expected) {
+                throw new Error("broken");
+            }
+            /* c8 ignore stop */
+        }
+        accum.push(form);
+    }
+    catch (error) { }
+    return accum;
+}, []);
+/**
+ *  Throws if the normalization %%form%% is not supported.
+ */
+export function assertNormalize(form) {
+    assert(_normalizeForms.indexOf(form) >= 0, "platform missing String.prototype.normalize", "UNSUPPORTED_OPERATION", {
+        operation: "String.prototype.normalize", info: { form }
+    });
+}
+/**
+ *  Many classes use file-scoped values to guard the constructor,
+ *  making it effectively private. This facilitates that pattern
+ *  by ensuring the %%givenGaurd%% matches the file-scoped %%guard%%,
+ *  throwing if not, indicating the %%className%% if provided.
+ */
+export function assertPrivate(givenGuard, guard, className) {
+    if (className == null) {
+        className = "";
+    }
+    if (givenGuard !== guard) {
+        let method = className, operation = "new";
+        if (className) {
+            method += ".";
+            operation += " " + className;
+        }
+        assert(false, `private constructor; use ${method}from* methods`, "UNSUPPORTED_OPERATION", {
+            operation
+        });
+    }
+}
+//# sourceMappingURL=errors.js.map

package/lib.esm/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src.ts/utils/errors.ts"],"names":[],"mappings":"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"}

package/lib.esm/utils/events.d.ts

@@ -0,0 +1,77 @@
+/**
+ *  A callback function called when a an event is triggered.
+ */
+export type Listener = (...args: Array<any>) => void;
+/**
+ *  An **EventEmitterable** behaves similar to an EventEmitter
+ *  except provides async access to its methods.
+ *
+ *  An EventEmitter implements the observer pattern.
+ */
+export interface EventEmitterable<T> {
+    /**
+     *  Registers a %%listener%% that is called whenever the
+     *  %%event%% occurs until unregistered.
+     */
+    on(event: T, listener: Listener): Promise<this>;
+    /**
+     *  Registers a %%listener%% that is called the next time
+     *  %%event%% occurs.
+     */
+    once(event: T, listener: Listener): Promise<this>;
+    /**
+     *  Triggers each listener for %%event%% with the %%args%%.
+     */
+    emit(event: T, ...args: Array<any>): Promise<boolean>;
+    /**
+     *  Resolves to the number of listeners for %%event%%.
+     */
+    listenerCount(event?: T): Promise<number>;
+    /**
+     *  Resolves to the listeners for %%event%%.
+     */
+    listeners(event?: T): Promise<Array<Listener>>;
+    /**
+     *  Unregister the %%listener%% for %%event%%. If %%listener%%
+     *  is unspecified, all listeners are unregistered.
+     */
+    off(event: T, listener?: Listener): Promise<this>;
+    /**
+     *  Unregister all listeners for %%event%%.
+     */
+    removeAllListeners(event?: T): Promise<this>;
+    /**
+     *  Alias for [[on]].
+     */
+    addListener(event: T, listener: Listener): Promise<this>;
+    /**
+     *  Alias for [[off]].
+     */
+    removeListener(event: T, listener: Listener): Promise<this>;
+}
+/**
+ *  When an [[EventEmitterable]] triggers a [[Listener]], the
+ *  callback always ahas one additional argument passed, which is
+ *  an **EventPayload**.
+ */
+export declare class EventPayload<T> {
+    #private;
+    /**
+     *  The event filter.
+     */
+    readonly filter: T;
+    /**
+     *  The **EventEmitterable**.
+     */
+    readonly emitter: EventEmitterable<T>;
+    /**
+     *  Create a new **EventPayload** for %%emitter%% with
+     *  the %%listener%% and for %%filter%%.
+     */
+    constructor(emitter: EventEmitterable<T>, listener: null | Listener, filter: T);
+    /**
+     *  Unregister the triggered listener for future events.
+     */
+    removeListener(): Promise<void>;
+}
+//# sourceMappingURL=events.d.ts.map

package/lib.esm/utils/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src.ts/utils/events.ts"],"names":[],"mappings":"AASA;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC;AAErD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IAC/B;;;OAGG;IACH,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhD;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtD;;OAEG;IACH,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1C;;OAEG;IACH,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE/C;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;OAEG;IACH,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7C;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzD;;OAEG;IACH,cAAc,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAED;;;;GAIG;AACH,qBAAa,YAAY,CAAC,CAAC;;IACvB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAG,CAAC,CAAC;IAEpB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAIvC;;;OAGG;gBACS,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,GAAG,QAAQ,EAAE,MAAM,EAAE,CAAC;IAK9E;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;CAIxC"}

package/lib.esm/utils/events.js

@@ -0,0 +1,42 @@
+/**
+ *  Events allow for applications to use the observer pattern, which
+ *  allows subscribing and publishing events, outside the normal
+ *  execution paths.
+ *
+ *  @_section api/utils/events:Events  [about-events]
+ */
+import { defineProperties } from "./properties.js";
+/**
+ *  When an [[EventEmitterable]] triggers a [[Listener]], the
+ *  callback always ahas one additional argument passed, which is
+ *  an **EventPayload**.
+ */
+export class EventPayload {
+    /**
+     *  The event filter.
+     */
+    filter;
+    /**
+     *  The **EventEmitterable**.
+     */
+    emitter;
+    #listener;
+    /**
+     *  Create a new **EventPayload** for %%emitter%% with
+     *  the %%listener%% and for %%filter%%.
+     */
+    constructor(emitter, listener, filter) {
+        this.#listener = listener;
+        defineProperties(this, { emitter, filter });
+    }
+    /**
+     *  Unregister the triggered listener for future events.
+     */
+    async removeListener() {
+        if (this.#listener == null) {
+            return;
+        }
+        await this.emitter.off(this.filter, this.#listener);
+    }
+}
+//# sourceMappingURL=events.js.map

package/lib.esm/utils/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src.ts/utils/events.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AA+DnD;;;;GAIG;AACH,MAAM,OAAO,YAAY;IACrB;;OAEG;IACM,MAAM,CAAK;IAEpB;;OAEG;IACM,OAAO,CAAuB;IAE9B,SAAS,CAAkB;IAEpC;;;OAGG;IACH,YAAY,OAA4B,EAAE,QAAyB,EAAE,MAAS;QAC1E,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,gBAAgB,CAAoB,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IACnE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,cAAc;QAChB,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,EAAE;YAAE,OAAO;SAAE;QACvC,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACxD,CAAC;CACJ"}

package/lib.esm/utils/fetch.d.ts

@@ -0,0 +1,334 @@
+/**
+ *  An environments implementation of ``getUrl`` must return this type.
+ */
+export type GetUrlResponse = {
+    statusCode: number;
+    statusMessage: string;
+    headers: Record<string, string>;
+    body: null | Uint8Array;
+};
+/**
+ *  This can be used to control how throttling is handled in
+ *  [[FetchRequest-setThrottleParams]].
+ */
+export type FetchThrottleParams = {
+    maxAttempts?: number;
+    slotInterval?: number;
+};
+/**
+ *  Called before any network request, allowing updated headers (e.g. Bearer tokens), etc.
+ */
+export type FetchPreflightFunc = (req: FetchRequest) => Promise<FetchRequest>;
+/**
+ *  Called on the response, allowing client-based throttling logic or post-processing.
+ */
+export type FetchProcessFunc = (req: FetchRequest, resp: FetchResponse) => Promise<FetchResponse>;
+/**
+ *  Called prior to each retry; return true to retry, false to abort.
+ */
+export type FetchRetryFunc = (req: FetchRequest, resp: FetchResponse, attempt: number) => Promise<boolean>;
+/**
+ *  Called on Gateway URLs.
+ */
+export type FetchGatewayFunc = (url: string, signal?: FetchCancelSignal) => Promise<FetchRequest | FetchResponse>;
+/**
+ *  Used to perform a fetch; use this to override the underlying network
+ *  fetch layer. In NodeJS, the default uses the "http" and "https" libraries
+ *  and in the browser ``fetch`` is used. If you wish to use Axios, this is
+ *  how you would register it.
+ */
+export type FetchGetUrlFunc = (req: FetchRequest, signal?: FetchCancelSignal) => Promise<GetUrlResponse>;
+/**
+ *  @_ignore
+ */
+export declare class FetchCancelSignal {
+    #private;
+    constructor(request: FetchRequest);
+    addListener(listener: () => void): void;
+    get cancelled(): boolean;
+    checkSignal(): void;
+}
+/**
+ *  Represents a request for a resource using a URI.
+ *
+ *  By default, the supported schemes are ``HTTP``, ``HTTPS``, ``data:``,
+ *  and ``IPFS:``.
+ *
+ *  Additional schemes can be added globally using [[registerGateway]].
+ *
+ *  @example:
+ *    req = new FetchRequest("https://www.ricmoo.com")
+ *    resp = await req.send()
+ *    resp.body.length
+ *    //_result:
+ */
+export declare class FetchRequest implements Iterable<[key: string, value: string]> {
+    #private;
+    /**
+     *  The fetch URI to requrest.
+     */
+    get url(): string;
+    set url(url: string);
+    /**
+     *  The fetch body, if any, to send as the request body. //(default: null)//
+     *
+     *  When setting a body, the intrinsic ``Content-Type`` is automatically
+     *  set and will be used if **not overridden** by setting a custom
+     *  header.
+     *
+     *  If %%body%% is null, the body is cleared (along with the
+     *  intrinsic ``Content-Type``) and the .
+     *
+     *  If %%body%% is a string, the intrincis ``Content-Type`` is set to
+     *  ``text/plain``.
+     *
+     *  If %%body%% is a Uint8Array, the intrincis ``Content-Type`` is set to
+     *  ``application/octet-stream``.
+     *
+     *  If %%body%% is any other object, the intrincis ``Content-Type`` is
+     *  set to ``application/json``.
+     */
+    get body(): null | Uint8Array;
+    set body(body: null | string | Readonly<object> | Readonly<Uint8Array>);
+    /**
+     *  Returns true if the request has a body.
+     */
+    hasBody(): this is (FetchRequest & {
+        body: Uint8Array;
+    });
+    /**
+     *  The HTTP method to use when requesting the URI. If no method
+     *  has been explicitly set, then ``GET`` is used if the body is
+     *  null and ``POST`` otherwise.
+     */
+    get method(): string;
+    set method(method: null | string);
+    /**
+     *  The headers that will be used when requesting the URI. All
+     *  keys are lower-case.
+     *
+     *  This object is a copy, so any chnages will **NOT** be reflected
+     *  in the ``FetchRequest``.
+     *
+     *  To set a header entry, use the ``setHeader`` method.
+     */
+    get headers(): Record<string, string>;
+    /**
+     *  Get the header for %%key%%, ignoring case.
+     */
+    getHeader(key: string): string;
+    /**
+     *  Set the header for %%key%% to %%value%%. All values are coerced
+     *  to a string.
+     */
+    setHeader(key: string, value: string | number): void;
+    /**
+     *  Clear all headers, resetting all intrinsic headers.
+     */
+    clearHeaders(): void;
+    [Symbol.iterator](): Iterator<[key: string, value: string]>;
+    /**
+     *  The value that will be sent for the ``Authorization`` header.
+     *
+     *  To set the credentials, use the ``setCredentials`` method.
+     */
+    get credentials(): null | string;
+    /**
+     *  Sets an ``Authorization`` for %%username%% with %%password%%.
+     */
+    setCredentials(username: string, password: string): void;
+    /**
+     *  Enable and request gzip-encoded responses. The response will
+     *  automatically be decompressed. //(default: true)//
+     */
+    get allowGzip(): boolean;
+    set allowGzip(value: boolean);
+    /**
+     *  Allow ``Authentication`` credentials to be sent over insecure
+     *  channels. //(default: false)//
+     */
+    get allowInsecureAuthentication(): boolean;
+    set allowInsecureAuthentication(value: boolean);
+    /**
+     *  The timeout (in milliseconds) to wait for a complere response.
+     *  //(default: 5 minutes)//
+     */
+    get timeout(): number;
+    set timeout(timeout: number);
+    /**
+     *  This function is called prior to each request, for example
+     *  during a redirection or retry in case of server throttling.
+     *
+     *  This offers an opportunity to populate headers or update
+     *  content before sending a request.
+     */
+    get preflightFunc(): null | FetchPreflightFunc;
+    set preflightFunc(preflight: null | FetchPreflightFunc);
+    /**
+     *  This function is called after each response, offering an
+     *  opportunity to provide client-level throttling or updating
+     *  response data.
+     *
+     *  Any error thrown in this causes the ``send()`` to throw.
+     *
+     *  To schedule a retry attempt (assuming the maximum retry limit
+     *  has not been reached), use [[response.throwThrottleError]].
+     */
+    get processFunc(): null | FetchProcessFunc;
+    set processFunc(process: null | FetchProcessFunc);
+    /**
+     *  This function is called on each retry attempt.
+     */
+    get retryFunc(): null | FetchRetryFunc;
+    set retryFunc(retry: null | FetchRetryFunc);
+    /**
+     *  Create a new FetchRequest instance with default values.
+     *
+     *  Once created, each property may be set before issuing a
+     *  ``.send()`` to make the request.
+     */
+    constructor(url: string);
+    toString(): string;
+    /**
+     *  Update the throttle parameters used to determine maximum
+     *  attempts and exponential-backoff properties.
+     */
+    setThrottleParams(params: FetchThrottleParams): void;
+    /**
+     *  Resolves to the response by sending the request.
+     */
+    send(): Promise<FetchResponse>;
+    /**
+     *  Cancels the inflight response, causing a ``CANCELLED``
+     *  error to be rejected from the [[send]].
+     */
+    cancel(): void;
+    /**
+     *  Returns a new [[FetchRequest]] that represents the redirection
+     *  to %%location%%.
+     */
+    redirect(location: string): FetchRequest;
+    /**
+     *  Create a new copy of this request.
+     */
+    clone(): FetchRequest;
+    /**
+     *  Locks all static configuration for gateways and FetchGetUrlFunc
+     *  registration.
+     */
+    static lockConfig(): void;
+    /**
+     *  Get the current Gateway function for %%scheme%%.
+     */
+    static getGateway(scheme: string): null | FetchGatewayFunc;
+    /**
+     *  Use the %%func%% when fetching URIs using %%scheme%%.
+     *
+     *  This method affects all requests globally.
+     *
+     *  If [[lockConfig]] has been called, no change is made and this
+     *  throws.
+     */
+    static registerGateway(scheme: string, func: FetchGatewayFunc): void;
+    /**
+     *  Use %%getUrl%% when fetching URIs over HTTP and HTTPS requests.
+     *
+     *  This method affects all requests globally.
+     *
+     *  If [[lockConfig]] has been called, no change is made and this
+     *  throws.
+     */
+    static registerGetUrl(getUrl: FetchGetUrlFunc): void;
+    /**
+     *  Creates a function that can "fetch" data URIs.
+     *
+     *  Note that this is automatically done internally to support
+     *  data URIs, so it is not necessary to register it.
+     *
+     *  This is not generally something that is needed, but may
+     *  be useful in a wrapper to perfom custom data URI functionality.
+     */
+    static createDataGateway(): FetchGatewayFunc;
+    /**
+     *  Creates a function that will fetch IPFS (unvalidated) from
+     *  a custom gateway baseUrl.
+     *
+     *  The default IPFS gateway used internally is
+     *  ``"https:/\/gateway.ipfs.io/ipfs/"``.
+     */
+    static createIpfsGatewayFunc(baseUrl: string): FetchGatewayFunc;
+}
+/**
+ *  The response for a FetchREquest.
+ */
+export declare class FetchResponse implements Iterable<[key: string, value: string]> {
+    #private;
+    toString(): string;
+    /**
+     *  The response status code.
+     */
+    get statusCode(): number;
+    /**
+     *  The response status message.
+     */
+    get statusMessage(): string;
+    /**
+     *  The response headers. All keys are lower-case.
+     */
+    get headers(): Record<string, string>;
+    /**
+     *  The response body, or ``null`` if there was no body.
+     */
+    get body(): null | Readonly<Uint8Array>;
+    /**
+     *  The response body as a UTF-8 encoded string, or the empty
+     *  string (i.e. ``""``) if there was no body.
+     *
+     *  An error is thrown if the body is invalid UTF-8 data.
+     */
+    get bodyText(): string;
+    /**
+     *  The response body, decoded as JSON.
+     *
+     *  An error is thrown if the body is invalid JSON-encoded data
+     *  or if there was no body.
+     */
+    get bodyJson(): any;
+    [Symbol.iterator](): Iterator<[key: string, value: string]>;
+    constructor(statusCode: number, statusMessage: string, headers: Readonly<Record<string, string>>, body: null | Uint8Array, request?: FetchRequest);
+    /**
+     *  Return a Response with matching headers and body, but with
+     *  an error status code (i.e. 599) and %%message%% with an
+     *  optional %%error%%.
+     */
+    makeServerError(message?: string, error?: Error): FetchResponse;
+    /**
+     *  If called within a [request.processFunc](FetchRequest-processFunc)
+     *  call, causes the request to retry as if throttled for %%stall%%
+     *  milliseconds.
+     */
+    throwThrottleError(message?: string, stall?: number): never;
+    /**
+     *  Get the header value for %%key%%, ignoring case.
+     */
+    getHeader(key: string): string;
+    /**
+     *  Returns true of the response has a body.
+     */
+    hasBody(): this is (FetchResponse & {
+        body: Uint8Array;
+    });
+    /**
+     *  The request made for this response.
+     */
+    get request(): null | FetchRequest;
+    /**
+     *  Returns true if this response was a success statusCode.
+     */
+    ok(): boolean;
+    /**
+     *  Throws a ``SERVER_ERROR`` if this response is not ok.
+     */
+    assertOk(): void;
+}
+//# sourceMappingURL=fetch.d.ts.map