@ensnode/ensrainbow-sdk 0.0.0-next-20260102143513

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NameHash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# ENSRainbow SDK
+
+TypeScript library for interacting with the [ENSRainbow API](https://github.com/namehash/ensnode/tree/main/apps/ensrainbow).
+
+Learn more about [ENSRainbow](https://ensrainbow.io) and [ENSNode](https://ensnode.io).
+
+## API Reference
+
+### Heal Label
+Attempt to heal a labelhash to its original label.
+
+```typescript
+const response = await client.heal(
+  "0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc"
+);
+
+console.log(response);
+
+// Output:
+// {
+//   status: "success",
+//   label: "vitalik"
+// }
+```
+
+### Label Count
+Get Count of Healable Labels
+
+```typescript
+const response = await client.count();
+
+console.log(response);
+
+// {
+//   "status": "success",
+//   "count": 133856894,
+//   "timestamp": "2024-01-30T11:18:56Z"
+// }
+```
+
+### Health Check
+Simple verification that the service is running, either in your local setup or for the provided hosted instance
+
+```typescript
+const response = await client.health();
+
+console.log(response);
+
+// {
+//   "status": "ok",
+// }
+```
+
+### Response Types & Error Handling
+Each API endpoint has a designated response type that includes a successful and an erroneous response to account for possible mishaps that could occur during a request.
+
+Below is an example of a failed `heal` operation, that shows the resulting error returned by the SDK
+
+```typescript
+const notFoundResponse = await client.heal(
+  "0xf64dc17ae2e2b9b16dbcb8cb05f35a2e6080a5ff1dc53ac0bc48f0e79111f264"
+);
+
+console.log(notFoundResponse);
+
+// Output:
+// {
+//   status: "error",
+//   error: "Label not found",
+//   errorCode: 404
+// }
+```
+
+## Contact Us
+
+Visit our [website](https://namehashlabs.org/) to get in contact.
+
+## License
+
+Licensed under the MIT License, Copyright © 2025-present [NameHash Labs](https://namehashlabs.org).
+
+See [LICENSE](./LICENSE) for more information.

package/dist/client.d.ts

@@ -0,0 +1,290 @@
+import { EnsRainbowClientLabelSet, LabelHash, Label, EnsRainbowServerLabelSet } from '@ensnode/ensnode-sdk';
+
+declare namespace EnsRainbow {
+    export type ApiClientOptions = EnsRainbowApiClientOptions;
+    export interface ApiClient {
+        count(): Promise<CountResponse>;
+        /**
+         * Heal a labelhash to its original label
+         * @param labelHash The labelhash to heal
+         */
+        heal(labelHash: LabelHash): Promise<HealResponse>;
+        health(): Promise<HealthResponse>;
+        version(): Promise<VersionResponse>;
+        getOptions(): Readonly<EnsRainbowApiClientOptions>;
+    }
+    type StatusCode = (typeof StatusCode)[keyof typeof StatusCode];
+    type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+    export interface HealthResponse {
+        status: "ok";
+    }
+    export interface BaseHealResponse<Status extends StatusCode, Error extends ErrorCode> {
+        status: Status;
+        label?: Label | never;
+        error?: string | never;
+        errorCode?: Error | never;
+    }
+    export interface HealSuccess extends BaseHealResponse<typeof StatusCode.Success, never> {
+        status: typeof StatusCode.Success;
+        label: Label;
+        error?: never;
+        errorCode?: never;
+    }
+    export interface HealNotFoundError extends BaseHealResponse<typeof StatusCode.Error, typeof ErrorCode.NotFound> {
+        status: typeof StatusCode.Error;
+        label?: never;
+        error: string;
+        errorCode: typeof ErrorCode.NotFound;
+    }
+    export interface HealServerError extends BaseHealResponse<typeof StatusCode.Error, typeof ErrorCode.ServerError> {
+        status: typeof StatusCode.Error;
+        label?: never;
+        error: string;
+        errorCode: typeof ErrorCode.ServerError;
+    }
+    export interface HealBadRequestError extends BaseHealResponse<typeof StatusCode.Error, typeof ErrorCode.BadRequest> {
+        status: typeof StatusCode.Error;
+        label?: never;
+        error: string;
+        errorCode: typeof ErrorCode.BadRequest;
+    }
+    export type HealResponse = HealSuccess | HealNotFoundError | HealServerError | HealBadRequestError;
+    export type HealError = Exclude<HealResponse, HealSuccess>;
+    /**
+     * Server errors should not be cached.
+     */
+    export type CacheableHealResponse = Exclude<HealResponse, HealServerError>;
+    export interface BaseCountResponse<Status extends StatusCode, Error extends ErrorCode> {
+        status: Status;
+        count?: number | never;
+        timestamp?: string | never;
+        error?: string | never;
+        errorCode?: Error | never;
+    }
+    export interface CountSuccess extends BaseCountResponse<typeof StatusCode.Success, never> {
+        status: typeof StatusCode.Success;
+        /** The total count of labels that can be healed by the ENSRainbow instance. Always a
+         * non-negative integer. */
+        count: number;
+        timestamp: string;
+        error?: never;
+        errorCode?: never;
+    }
+    export interface CountServerError extends BaseCountResponse<typeof StatusCode.Error, typeof ErrorCode.ServerError> {
+        status: typeof StatusCode.Error;
+        count?: never;
+        timestamp?: never;
+        error: string;
+        errorCode: typeof ErrorCode.ServerError;
+    }
+    export type CountResponse = CountSuccess | CountServerError;
+    /**
+     * ENSRainbow version information.
+     */
+    export interface VersionInfo {
+        /**
+         * ENSRainbow version.
+         */
+        version: string;
+        /**
+         * ENSRainbow database schema version.
+         */
+        dbSchemaVersion: number;
+        /**
+         * The EnsRainbowServerLabelSet managed by the ENSRainbow server.
+         */
+        labelSet: EnsRainbowServerLabelSet;
+    }
+    /**
+     * Interface for the version endpoint response
+     */
+    export interface VersionResponse {
+        status: typeof StatusCode.Success;
+        versionInfo: VersionInfo;
+    }
+    export {  };
+}
+interface EnsRainbowApiClientOptions {
+    /**
+     * The maximum number of `HealResponse` values to cache.
+     * Must be a non-negative integer.
+     * Setting to 0 will disable caching.
+     */
+    cacheCapacity: number;
+    /**
+     * The URL of an ENSRainbow API endpoint.
+     */
+    endpointUrl: URL;
+    /**
+     * Optional label set preferences that the ENSRainbow server at endpointUrl is expected to
+     * support. If provided, enables deterministic heal results across time, such that only
+     * labels from label sets with versions less than or equal to this value will be returned.
+     * Therefore, even if the ENSRainbow server later ingests label sets with greater versions
+     * than this value, the results returned across time can be deterministic. If
+     * provided, heal operations with this EnsRainbowApiClient will validate the ENSRainbow
+     * server manages a compatible label set. If not provided no specific labelSetId validation
+     * will be performed during heal operations.
+     * If `labelSetId` is provided without `labelSetVersion`, the server will use the latest
+     * available version.
+     * If `labelSetVersion` is defined, only labels from sets less than or equal to this value
+     * will be returned.
+     * When `labelSetVersion` is defined, `labelSetId` must also be defined.
+     */
+    labelSet?: EnsRainbowClientLabelSet;
+}
+/**
+ * ENSRainbow API client
+ *
+ * @example
+ * ```typescript
+ * // default options
+ * const client = new EnsRainbowApiClient();
+ * // custom options
+ * const client = new EnsRainbowApiClient({
+ *  endpointUrl: new URL("https://api.ensrainbow.io"),
+ * });
+ * ```
+ */
+declare class EnsRainbowApiClient implements EnsRainbow.ApiClient {
+    private readonly options;
+    private readonly cache;
+    private readonly labelSetSearchParams;
+    static readonly DEFAULT_CACHE_CAPACITY = 1000;
+    /**
+     * Create default client options.
+     *
+     * @returns default options
+     */
+    static defaultOptions(): EnsRainbow.ApiClientOptions;
+    constructor(options?: Partial<EnsRainbow.ApiClientOptions>);
+    /**
+     * Attempt to heal a labelHash to its original label.
+     *
+     * Note on returned labels: ENSRainbow returns labels exactly as they are
+     * represented in source rainbow table data. This means:
+     *
+     * - Labels may or may not be ENS-normalized
+     * - Labels can contain any valid string, including dots, null bytes, or be empty
+     * - Clients should handle all possible string values appropriately
+     *
+     * @param labelHash all lowercase 64-digit hex string with 0x prefix (total length of 66 characters)
+     * @returns a `HealResponse` indicating the result of the request and the healed label if successful
+     * @throws if the request fails due to network failures, DNS lookup failures, request timeouts,
+     * CORS violations, or Invalid URLs
+     * @example
+     * ```typescript
+     * const response = await client.heal(
+     *   "0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc"
+     * );
+     *
+     * console.log(response);
+     *
+     * // Output:
+     * // {
+     * //   status: "success",
+     * //   label: "vitalik"
+     * // }
+     *
+     * const notFoundResponse = await client.heal(
+     *   "0xf64dc17ae2e2b9b16dbcb8cb05f35a2e6080a5ff1dc53ac0bc48f0e79111f264"
+     * );
+     *
+     * console.log(notFoundResponse);
+     *
+     * // Output:
+     * // {
+     * //   status: "error",
+     * //   error: "Label not found",
+     * //   errorCode: 404
+     * // }
+     * ```
+     */
+    heal(labelHash: LabelHash): Promise<EnsRainbow.HealResponse>;
+    /**
+     * Get Count of Healable Labels
+     *
+     * @returns a `CountResponse` indicating the result and the timestamp of the request and the
+     * number of healable labels if successful
+     * @throws if the request fails due to network failures, DNS lookup failures, request timeouts,
+     * CORS violations, or Invalid URLs
+     * @example
+     *
+     * const response = await client.count();
+     *
+     * console.log(response);
+     *
+     * // {
+     * //   "status": "success",
+     * //   "count": 133856894,
+     * //   "timestamp": "2024-01-30T11:18:56Z"
+     * // }
+     *
+     */
+    count(): Promise<EnsRainbow.CountResponse>;
+    /**
+     *
+     * Simple verification that the service is running, either in your local setup or for the
+     * provided hosted instance.
+     * @returns a status of ENS Rainbow service
+     * @example
+     *
+     * const response = await client.health();
+     *
+     * console.log(response);
+     *
+     * // {
+     * //   "status": "ok",
+     * // }
+     */
+    health(): Promise<EnsRainbow.HealthResponse>;
+    /**
+     * Get the version information of the ENSRainbow service
+     *
+     * @returns the version information of the ENSRainbow service
+     * @throws if the request fails due to network failures, DNS lookup failures, request
+     * timeouts, CORS violations, or invalid URLs
+     * @example
+     * ```typescript
+     * const response = await client.version();
+     *
+     * console.log(response);
+     *
+     * // {
+     * //   "status": "success",
+     * //   "versionInfo": {
+     * //     "version": "0.1.0",
+     * //     "dbSchemaVersion": 2,
+     * //     "labelSet": {
+     * //       "labelSetId": "subgraph",
+     * //       "labelSetVersion": 0
+     * //     }
+     * //   }
+     * // }
+     * ```
+     */
+    version(): Promise<EnsRainbow.VersionResponse>;
+    /**
+     * Get a copy of the current client options.
+     *
+     * @returns a copy of the current client options.
+     */
+    getOptions(): Readonly<EnsRainbowApiClientOptions>;
+}
+/**
+ * Determine if a heal response is an error.
+ *
+ * @param response the heal response to check
+ * @returns true if the response is an error, false otherwise
+ */
+declare const isHealError: (response: EnsRainbow.HealResponse) => response is EnsRainbow.HealError;
+/**
+ * Determine if a heal response is cacheable.
+ *
+ * Server errors at not cachable and should be retried.
+ *
+ * @param response the heal response to check
+ * @returns true if the response is cacheable, false otherwise
+ */
+declare const isCacheableHealResponse: (response: EnsRainbow.HealResponse) => response is EnsRainbow.CacheableHealResponse;
+
+export { EnsRainbow, EnsRainbowApiClient, type EnsRainbowApiClientOptions, isCacheableHealResponse, isHealError };

package/dist/client.js

@@ -0,0 +1,216 @@
+// src/client.ts
+import {
+  buildEnsRainbowClientLabelSet,
+  LruCache
+} from "@ensnode/ensnode-sdk";
+
+// src/consts.ts
+var DEFAULT_ENSRAINBOW_URL = "https://api.ensrainbow.io";
+var StatusCode = {
+  Success: "success",
+  Error: "error"
+};
+var ErrorCode = {
+  BadRequest: 400,
+  NotFound: 404,
+  ServerError: 500
+};
+
+// src/client.ts
+var EnsRainbowApiClient = class _EnsRainbowApiClient {
+  options;
+  cache;
+  labelSetSearchParams;
+  static DEFAULT_CACHE_CAPACITY = 1e3;
+  /**
+   * Create default client options.
+   *
+   * @returns default options
+   */
+  static defaultOptions() {
+    return {
+      endpointUrl: new URL(DEFAULT_ENSRAINBOW_URL),
+      cacheCapacity: _EnsRainbowApiClient.DEFAULT_CACHE_CAPACITY,
+      labelSet: buildEnsRainbowClientLabelSet()
+    };
+  }
+  constructor(options = {}) {
+    const { labelSet: optionsLabelSet, ...rest } = options;
+    const defaultOptions = _EnsRainbowApiClient.defaultOptions();
+    const copiedLabelSet = buildEnsRainbowClientLabelSet(
+      optionsLabelSet?.labelSetId,
+      optionsLabelSet?.labelSetVersion
+    );
+    this.options = {
+      ...defaultOptions,
+      ...rest,
+      labelSet: copiedLabelSet
+    };
+    this.cache = new LruCache(
+      this.options.cacheCapacity
+    );
+    this.labelSetSearchParams = new URLSearchParams();
+    if (this.options.labelSet?.labelSetId !== void 0) {
+      this.labelSetSearchParams.append("label_set_id", this.options.labelSet.labelSetId);
+    }
+    if (this.options.labelSet?.labelSetVersion !== void 0) {
+      this.labelSetSearchParams.append(
+        "label_set_version",
+        this.options.labelSet.labelSetVersion.toString()
+      );
+    }
+  }
+  /**
+   * Attempt to heal a labelHash to its original label.
+   *
+   * Note on returned labels: ENSRainbow returns labels exactly as they are
+   * represented in source rainbow table data. This means:
+   *
+   * - Labels may or may not be ENS-normalized
+   * - Labels can contain any valid string, including dots, null bytes, or be empty
+   * - Clients should handle all possible string values appropriately
+   *
+   * @param labelHash all lowercase 64-digit hex string with 0x prefix (total length of 66 characters)
+   * @returns a `HealResponse` indicating the result of the request and the healed label if successful
+   * @throws if the request fails due to network failures, DNS lookup failures, request timeouts,
+   * CORS violations, or Invalid URLs
+   * @example
+   * ```typescript
+   * const response = await client.heal(
+   *   "0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc"
+   * );
+   *
+   * console.log(response);
+   *
+   * // Output:
+   * // {
+   * //   status: "success",
+   * //   label: "vitalik"
+   * // }
+   *
+   * const notFoundResponse = await client.heal(
+   *   "0xf64dc17ae2e2b9b16dbcb8cb05f35a2e6080a5ff1dc53ac0bc48f0e79111f264"
+   * );
+   *
+   * console.log(notFoundResponse);
+   *
+   * // Output:
+   * // {
+   * //   status: "error",
+   * //   error: "Label not found",
+   * //   errorCode: 404
+   * // }
+   * ```
+   */
+  async heal(labelHash) {
+    const cachedResult = this.cache.get(labelHash);
+    if (cachedResult) return cachedResult;
+    const url = new URL(`/v1/heal/${labelHash}`, this.options.endpointUrl);
+    this.labelSetSearchParams.forEach((value, key) => {
+      url.searchParams.append(key, value);
+    });
+    const response = await fetch(url);
+    const healResponse = await response.json();
+    if (isCacheableHealResponse(healResponse)) {
+      this.cache.set(labelHash, healResponse);
+    }
+    return healResponse;
+  }
+  /**
+   * Get Count of Healable Labels
+   *
+   * @returns a `CountResponse` indicating the result and the timestamp of the request and the
+   * number of healable labels if successful
+   * @throws if the request fails due to network failures, DNS lookup failures, request timeouts,
+   * CORS violations, or Invalid URLs
+   * @example
+   *
+   * const response = await client.count();
+   *
+   * console.log(response);
+   *
+   * // {
+   * //   "status": "success",
+   * //   "count": 133856894,
+   * //   "timestamp": "2024-01-30T11:18:56Z"
+   * // }
+   *
+   */
+  async count() {
+    const response = await fetch(new URL("/v1/labels/count", this.options.endpointUrl));
+    return response.json();
+  }
+  /**
+   *
+   * Simple verification that the service is running, either in your local setup or for the
+   * provided hosted instance.
+   * @returns a status of ENS Rainbow service
+   * @example
+   *
+   * const response = await client.health();
+   *
+   * console.log(response);
+   *
+   * // {
+   * //   "status": "ok",
+   * // }
+   */
+  async health() {
+    const response = await fetch(new URL("/health", this.options.endpointUrl));
+    return response.json();
+  }
+  /**
+   * Get the version information of the ENSRainbow service
+   *
+   * @returns the version information of the ENSRainbow service
+   * @throws if the request fails due to network failures, DNS lookup failures, request
+   * timeouts, CORS violations, or invalid URLs
+   * @example
+   * ```typescript
+   * const response = await client.version();
+   *
+   * console.log(response);
+   *
+   * // {
+   * //   "status": "success",
+   * //   "versionInfo": {
+   * //     "version": "0.1.0",
+   * //     "dbSchemaVersion": 2,
+   * //     "labelSet": {
+   * //       "labelSetId": "subgraph",
+   * //       "labelSetVersion": 0
+   * //     }
+   * //   }
+   * // }
+   * ```
+   */
+  async version() {
+    const response = await fetch(new URL("/v1/version", this.options.endpointUrl));
+    return response.json();
+  }
+  /**
+   * Get a copy of the current client options.
+   *
+   * @returns a copy of the current client options.
+   */
+  getOptions() {
+    const deepCopy = {
+      cacheCapacity: this.options.cacheCapacity,
+      endpointUrl: new URL(this.options.endpointUrl.href),
+      labelSet: this.options.labelSet ? { ...this.options.labelSet } : void 0
+    };
+    return Object.freeze(deepCopy);
+  }
+};
+var isHealError = (response) => {
+  return response.status === StatusCode.Error;
+};
+var isCacheableHealResponse = (response) => {
+  return response.status === StatusCode.Success || response.errorCode !== ErrorCode.ServerError;
+};
+export {
+  EnsRainbowApiClient,
+  isCacheableHealResponse,
+  isHealError
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts","../src/consts.ts"],"sourcesContent":["import {\n  buildEnsRainbowClientLabelSet,\n  type Cache,\n  type EnsRainbowClientLabelSet,\n  type EnsRainbowServerLabelSet,\n  type Label,\n  type LabelHash,\n  LruCache,\n} from \"@ensnode/ensnode-sdk\";\n\nimport { DEFAULT_ENSRAINBOW_URL, ErrorCode, StatusCode } from \"./consts\";\n\nexport namespace EnsRainbow {\n  export type ApiClientOptions = EnsRainbowApiClientOptions;\n\n  export interface ApiClient {\n    count(): Promise<CountResponse>;\n\n    /**\n     * Heal a labelhash to its original label\n     * @param labelHash The labelhash to heal\n     */\n    heal(labelHash: LabelHash): Promise<HealResponse>;\n\n    health(): Promise<HealthResponse>;\n\n    version(): Promise<VersionResponse>;\n\n    getOptions(): Readonly<EnsRainbowApiClientOptions>;\n  }\n\n  type StatusCode = (typeof StatusCode)[keyof typeof StatusCode];\n\n  type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];\n\n  export interface HealthResponse {\n    status: \"ok\";\n  }\n\n  export interface BaseHealResponse<Status extends StatusCode, Error extends ErrorCode> {\n    status: Status;\n    label?: Label | never;\n    error?: string | never;\n    errorCode?: Error | never;\n  }\n\n  export interface HealSuccess extends BaseHealResponse<typeof StatusCode.Success, never> {\n    status: typeof StatusCode.Success;\n    label: Label;\n    error?: never;\n    errorCode?: never;\n  }\n\n  export interface HealNotFoundError\n    extends BaseHealResponse<typeof StatusCode.Error, typeof ErrorCode.NotFound> {\n    status: typeof StatusCode.Error;\n    label?: never;\n    error: string;\n    errorCode: typeof ErrorCode.NotFound;\n  }\n\n  export interface HealServerError\n    extends BaseHealResponse<typeof StatusCode.Error, typeof ErrorCode.ServerError> {\n    status: typeof StatusCode.Error;\n    label?: never;\n    error: string;\n    errorCode: typeof ErrorCode.ServerError;\n  }\n\n  export interface HealBadRequestError\n    extends BaseHealResponse<typeof StatusCode.Error, typeof ErrorCode.BadRequest> {\n    status: typeof StatusCode.Error;\n    label?: never;\n    error: string;\n    errorCode: typeof ErrorCode.BadRequest;\n  }\n\n  export type HealResponse =\n    | HealSuccess\n    | HealNotFoundError\n    | HealServerError\n    | HealBadRequestError;\n  export type HealError = Exclude<HealResponse, HealSuccess>;\n\n  /**\n   * Server errors should not be cached.\n   */\n  export type CacheableHealResponse = Exclude<HealResponse, HealServerError>;\n\n  export interface BaseCountResponse<Status extends StatusCode, Error extends ErrorCode> {\n    status: Status;\n    count?: number | never;\n    timestamp?: string | never;\n    error?: string | never;\n    errorCode?: Error | never;\n  }\n\n  export interface CountSuccess extends BaseCountResponse<typeof StatusCode.Success, never> {\n    status: typeof StatusCode.Success;\n    /** The total count of labels that can be healed by the ENSRainbow instance. Always a\n     * non-negative integer. */\n    count: number;\n    timestamp: string;\n    error?: never;\n    errorCode?: never;\n  }\n\n  export interface CountServerError\n    extends BaseCountResponse<typeof StatusCode.Error, typeof ErrorCode.ServerError> {\n    status: typeof StatusCode.Error;\n    count?: never;\n    timestamp?: never;\n    error: string;\n    errorCode: typeof ErrorCode.ServerError;\n  }\n\n  export type CountResponse = CountSuccess | CountServerError;\n\n  /**\n   * ENSRainbow version information.\n   */\n  export interface VersionInfo {\n    /**\n     * ENSRainbow version.\n     */\n    version: string;\n\n    /**\n     * ENSRainbow database schema version.\n     */\n    dbSchemaVersion: number;\n\n    /**\n     * The EnsRainbowServerLabelSet managed by the ENSRainbow server.\n     */\n    labelSet: EnsRainbowServerLabelSet;\n  }\n\n  /**\n   * Interface for the version endpoint response\n   */\n  export interface VersionResponse {\n    status: typeof StatusCode.Success;\n    versionInfo: VersionInfo;\n  }\n}\n\nexport interface EnsRainbowApiClientOptions {\n  /**\n   * The maximum number of `HealResponse` values to cache.\n   * Must be a non-negative integer.\n   * Setting to 0 will disable caching.\n   */\n  cacheCapacity: number;\n\n  /**\n   * The URL of an ENSRainbow API endpoint.\n   */\n  endpointUrl: URL;\n\n  /**\n   * Optional label set preferences that the ENSRainbow server at endpointUrl is expected to\n   * support. If provided, enables deterministic heal results across time, such that only\n   * labels from label sets with versions less than or equal to this value will be returned.\n   * Therefore, even if the ENSRainbow server later ingests label sets with greater versions\n   * than this value, the results returned across time can be deterministic. If\n   * provided, heal operations with this EnsRainbowApiClient will validate the ENSRainbow\n   * server manages a compatible label set. If not provided no specific labelSetId validation\n   * will be performed during heal operations.\n   * If `labelSetId` is provided without `labelSetVersion`, the server will use the latest\n   * available version.\n   * If `labelSetVersion` is defined, only labels from sets less than or equal to this value\n   * will be returned.\n   * When `labelSetVersion` is defined, `labelSetId` must also be defined.\n   */\n  labelSet?: EnsRainbowClientLabelSet;\n}\n\n/**\n * ENSRainbow API client\n *\n * @example\n * ```typescript\n * // default options\n * const client = new EnsRainbowApiClient();\n * // custom options\n * const client = new EnsRainbowApiClient({\n *  endpointUrl: new URL(\"https://api.ensrainbow.io\"),\n * });\n * ```\n */\nexport class EnsRainbowApiClient implements EnsRainbow.ApiClient {\n  private readonly options: EnsRainbowApiClientOptions;\n  private readonly cache: Cache<LabelHash, EnsRainbow.CacheableHealResponse>;\n  private readonly labelSetSearchParams: URLSearchParams;\n\n  public static readonly DEFAULT_CACHE_CAPACITY = 1000;\n\n  /**\n   * Create default client options.\n   *\n   * @returns default options\n   */\n  static defaultOptions(): EnsRainbow.ApiClientOptions {\n    return {\n      endpointUrl: new URL(DEFAULT_ENSRAINBOW_URL),\n      cacheCapacity: EnsRainbowApiClient.DEFAULT_CACHE_CAPACITY,\n      labelSet: buildEnsRainbowClientLabelSet(),\n    };\n  }\n\n  constructor(options: Partial<EnsRainbow.ApiClientOptions> = {}) {\n    const { labelSet: optionsLabelSet, ...rest } = options;\n    const defaultOptions = EnsRainbowApiClient.defaultOptions();\n\n    const copiedLabelSet = buildEnsRainbowClientLabelSet(\n      optionsLabelSet?.labelSetId,\n      optionsLabelSet?.labelSetVersion,\n    );\n\n    this.options = {\n      ...defaultOptions,\n      ...rest,\n      labelSet: copiedLabelSet,\n    };\n\n    this.cache = new LruCache<LabelHash, EnsRainbow.CacheableHealResponse>(\n      this.options.cacheCapacity,\n    );\n\n    // Pre-compute query parameters for label set options\n    this.labelSetSearchParams = new URLSearchParams();\n    if (this.options.labelSet?.labelSetId !== undefined) {\n      this.labelSetSearchParams.append(\"label_set_id\", this.options.labelSet.labelSetId);\n    }\n    if (this.options.labelSet?.labelSetVersion !== undefined) {\n      this.labelSetSearchParams.append(\n        \"label_set_version\",\n        this.options.labelSet.labelSetVersion.toString(),\n      );\n    }\n  }\n\n  /**\n   * Attempt to heal a labelHash to its original label.\n   *\n   * Note on returned labels: ENSRainbow returns labels exactly as they are\n   * represented in source rainbow table data. This means:\n   *\n   * - Labels may or may not be ENS-normalized\n   * - Labels can contain any valid string, including dots, null bytes, or be empty\n   * - Clients should handle all possible string values appropriately\n   *\n   * @param labelHash all lowercase 64-digit hex string with 0x prefix (total length of 66 characters)\n   * @returns a `HealResponse` indicating the result of the request and the healed label if successful\n   * @throws if the request fails due to network failures, DNS lookup failures, request timeouts,\n   * CORS violations, or Invalid URLs\n   * @example\n   * ```typescript\n   * const response = await client.heal(\n   *   \"0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc\"\n   * );\n   *\n   * console.log(response);\n   *\n   * // Output:\n   * // {\n   * //   status: \"success\",\n   * //   label: \"vitalik\"\n   * // }\n   *\n   * const notFoundResponse = await client.heal(\n   *   \"0xf64dc17ae2e2b9b16dbcb8cb05f35a2e6080a5ff1dc53ac0bc48f0e79111f264\"\n   * );\n   *\n   * console.log(notFoundResponse);\n   *\n   * // Output:\n   * // {\n   * //   status: \"error\",\n   * //   error: \"Label not found\",\n   * //   errorCode: 404\n   * // }\n   * ```\n   */\n  async heal(labelHash: LabelHash): Promise<EnsRainbow.HealResponse> {\n    const cachedResult = this.cache.get(labelHash);\n    if (cachedResult) return cachedResult;\n\n    const url = new URL(`/v1/heal/${labelHash}`, this.options.endpointUrl);\n\n    // Apply pre-computed label set query parameters\n    this.labelSetSearchParams.forEach((value, key) => {\n      url.searchParams.append(key, value);\n    });\n\n    const response = await fetch(url);\n    const healResponse = (await response.json()) as EnsRainbow.HealResponse;\n\n    if (isCacheableHealResponse(healResponse)) {\n      this.cache.set(labelHash, healResponse);\n    }\n\n    return healResponse;\n  }\n\n  /**\n   * Get Count of Healable Labels\n   *\n   * @returns a `CountResponse` indicating the result and the timestamp of the request and the\n   * number of healable labels if successful\n   * @throws if the request fails due to network failures, DNS lookup failures, request timeouts,\n   * CORS violations, or Invalid URLs\n   * @example\n   *\n   * const response = await client.count();\n   *\n   * console.log(response);\n   *\n   * // {\n   * //   \"status\": \"success\",\n   * //   \"count\": 133856894,\n   * //   \"timestamp\": \"2024-01-30T11:18:56Z\"\n   * // }\n   *\n   */\n  async count(): Promise<EnsRainbow.CountResponse> {\n    const response = await fetch(new URL(\"/v1/labels/count\", this.options.endpointUrl));\n\n    return response.json() as Promise<EnsRainbow.CountResponse>;\n  }\n\n  /**\n   *\n   * Simple verification that the service is running, either in your local setup or for the\n   * provided hosted instance.\n   * @returns a status of ENS Rainbow service\n   * @example\n   *\n   * const response = await client.health();\n   *\n   * console.log(response);\n   *\n   * // {\n   * //   \"status\": \"ok\",\n   * // }\n   */\n  async health(): Promise<EnsRainbow.HealthResponse> {\n    const response = await fetch(new URL(\"/health\", this.options.endpointUrl));\n\n    return response.json() as Promise<EnsRainbow.HealthResponse>;\n  }\n\n  /**\n   * Get the version information of the ENSRainbow service\n   *\n   * @returns the version information of the ENSRainbow service\n   * @throws if the request fails due to network failures, DNS lookup failures, request\n   * timeouts, CORS violations, or invalid URLs\n   * @example\n   * ```typescript\n   * const response = await client.version();\n   *\n   * console.log(response);\n   *\n   * // {\n   * //   \"status\": \"success\",\n   * //   \"versionInfo\": {\n   * //     \"version\": \"0.1.0\",\n   * //     \"dbSchemaVersion\": 2,\n   * //     \"labelSet\": {\n   * //       \"labelSetId\": \"subgraph\",\n   * //       \"labelSetVersion\": 0\n   * //     }\n   * //   }\n   * // }\n   * ```\n   */\n  async version(): Promise<EnsRainbow.VersionResponse> {\n    const response = await fetch(new URL(\"/v1/version\", this.options.endpointUrl));\n\n    return response.json() as Promise<EnsRainbow.VersionResponse>;\n  }\n\n  /**\n   * Get a copy of the current client options.\n   *\n   * @returns a copy of the current client options.\n   */\n  getOptions(): Readonly<EnsRainbowApiClientOptions> {\n    // build a deep copy to prevent modification\n    const deepCopy = {\n      cacheCapacity: this.options.cacheCapacity,\n      endpointUrl: new URL(this.options.endpointUrl.href),\n      labelSet: this.options.labelSet ? { ...this.options.labelSet } : undefined,\n    } satisfies EnsRainbowApiClientOptions;\n\n    return Object.freeze(deepCopy);\n  }\n}\n\n/**\n * Determine if a heal response is an error.\n *\n * @param response the heal response to check\n * @returns true if the response is an error, false otherwise\n */\nexport const isHealError = (\n  response: EnsRainbow.HealResponse,\n): response is EnsRainbow.HealError => {\n  return response.status === StatusCode.Error;\n};\n\n/**\n * Determine if a heal response is cacheable.\n *\n * Server errors at not cachable and should be retried.\n *\n * @param response the heal response to check\n * @returns true if the response is cacheable, false otherwise\n */\nexport const isCacheableHealResponse = (\n  response: EnsRainbow.HealResponse,\n): response is EnsRainbow.CacheableHealResponse => {\n  return response.status === StatusCode.Success || response.errorCode !== ErrorCode.ServerError;\n};\n","export const DEFAULT_ENSRAINBOW_URL = \"https://api.ensrainbow.io\" as const;\n\nexport const StatusCode = {\n  Success: \"success\",\n  Error: \"error\",\n} as const;\n\nexport const ErrorCode = {\n  BadRequest: 400,\n  NotFound: 404,\n  ServerError: 500,\n} as const;\n"],"mappings":";AAAA;AAAA,EACE;AAAA,EAMA;AAAA,OACK;;;ACRA,IAAM,yBAAyB;AAE/B,IAAM,aAAa;AAAA,EACxB,SAAS;AAAA,EACT,OAAO;AACT;AAEO,IAAM,YAAY;AAAA,EACvB,YAAY;AAAA,EACZ,UAAU;AAAA,EACV,aAAa;AACf;;;ADoLO,IAAM,sBAAN,MAAM,qBAAoD;AAAA,EAC9C;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,OAAuB,yBAAyB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOhD,OAAO,iBAA8C;AACnD,WAAO;AAAA,MACL,aAAa,IAAI,IAAI,sBAAsB;AAAA,MAC3C,eAAe,qBAAoB;AAAA,MACnC,UAAU,8BAA8B;AAAA,IAC1C;AAAA,EACF;AAAA,EAEA,YAAY,UAAgD,CAAC,GAAG;AAC9D,UAAM,EAAE,UAAU,iBAAiB,GAAG,KAAK,IAAI;AAC/C,UAAM,iBAAiB,qBAAoB,eAAe;AAE1D,UAAM,iBAAiB;AAAA,MACrB,iBAAiB;AAAA,MACjB,iBAAiB;AAAA,IACnB;AAEA,SAAK,UAAU;AAAA,MACb,GAAG;AAAA,MACH,GAAG;AAAA,MACH,UAAU;AAAA,IACZ;AAEA,SAAK,QAAQ,IAAI;AAAA,MACf,KAAK,QAAQ;AAAA,IACf;AAGA,SAAK,uBAAuB,IAAI,gBAAgB;AAChD,QAAI,KAAK,QAAQ,UAAU,eAAe,QAAW;AACnD,WAAK,qBAAqB,OAAO,gBAAgB,KAAK,QAAQ,SAAS,UAAU;AAAA,IACnF;AACA,QAAI,KAAK,QAAQ,UAAU,oBAAoB,QAAW;AACxD,WAAK,qBAAqB;AAAA,QACxB;AAAA,QACA,KAAK,QAAQ,SAAS,gBAAgB,SAAS;AAAA,MACjD;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA4CA,MAAM,KAAK,WAAwD;AACjE,UAAM,eAAe,KAAK,MAAM,IAAI,SAAS;AAC7C,QAAI,aAAc,QAAO;AAEzB,UAAM,MAAM,IAAI,IAAI,YAAY,SAAS,IAAI,KAAK,QAAQ,WAAW;AAGrE,SAAK,qBAAqB,QAAQ,CAAC,OAAO,QAAQ;AAChD,UAAI,aAAa,OAAO,KAAK,KAAK;AAAA,IACpC,CAAC;AAED,UAAM,WAAW,MAAM,MAAM,GAAG;AAChC,UAAM,eAAgB,MAAM,SAAS,KAAK;AAE1C,QAAI,wBAAwB,YAAY,GAAG;AACzC,WAAK,MAAM,IAAI,WAAW,YAAY;AAAA,IACxC;AAEA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAsBA,MAAM,QAA2C;AAC/C,UAAM,WAAW,MAAM,MAAM,IAAI,IAAI,oBAAoB,KAAK,QAAQ,WAAW,CAAC;AAElF,WAAO,SAAS,KAAK;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiBA,MAAM,SAA6C;AACjD,UAAM,WAAW,MAAM,MAAM,IAAI,IAAI,WAAW,KAAK,QAAQ,WAAW,CAAC;AAEzE,WAAO,SAAS,KAAK;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA2BA,MAAM,UAA+C;AACnD,UAAM,WAAW,MAAM,MAAM,IAAI,IAAI,eAAe,KAAK,QAAQ,WAAW,CAAC;AAE7E,WAAO,SAAS,KAAK;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,aAAmD;AAEjD,UAAM,WAAW;AAAA,MACf,eAAe,KAAK,QAAQ;AAAA,MAC5B,aAAa,IAAI,IAAI,KAAK,QAAQ,YAAY,IAAI;AAAA,MAClD,UAAU,KAAK,QAAQ,WAAW,EAAE,GAAG,KAAK,QAAQ,SAAS,IAAI;AAAA,IACnE;AAEA,WAAO,OAAO,OAAO,QAAQ;AAAA,EAC/B;AACF;AAQO,IAAM,cAAc,CACzB,aACqC;AACrC,SAAO,SAAS,WAAW,WAAW;AACxC;AAUO,IAAM,0BAA0B,CACrC,aACiD;AACjD,SAAO,SAAS,WAAW,WAAW,WAAW,SAAS,cAAc,UAAU;AACpF;","names":[]}

package/dist/consts.d.ts

@@ -0,0 +1,12 @@
+declare const DEFAULT_ENSRAINBOW_URL: "https://api.ensrainbow.io";
+declare const StatusCode: {
+    readonly Success: "success";
+    readonly Error: "error";
+};
+declare const ErrorCode: {
+    readonly BadRequest: 400;
+    readonly NotFound: 404;
+    readonly ServerError: 500;
+};
+
+export { DEFAULT_ENSRAINBOW_URL, ErrorCode, StatusCode };

package/dist/consts.js

@@ -0,0 +1,17 @@
+// src/consts.ts
+var DEFAULT_ENSRAINBOW_URL = "https://api.ensrainbow.io";
+var StatusCode = {
+  Success: "success",
+  Error: "error"
+};
+var ErrorCode = {
+  BadRequest: 400,
+  NotFound: 404,
+  ServerError: 500
+};
+export {
+  DEFAULT_ENSRAINBOW_URL,
+  ErrorCode,
+  StatusCode
+};
+//# sourceMappingURL=consts.js.map

package/dist/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/consts.ts"],"sourcesContent":["export const DEFAULT_ENSRAINBOW_URL = \"https://api.ensrainbow.io\" as const;\n\nexport const StatusCode = {\n  Success: \"success\",\n  Error: \"error\",\n} as const;\n\nexport const ErrorCode = {\n  BadRequest: 400,\n  NotFound: 404,\n  ServerError: 500,\n} as const;\n"],"mappings":";AAAO,IAAM,yBAAyB;AAE/B,IAAM,aAAa;AAAA,EACxB,SAAS;AAAA,EACT,OAAO;AACT;AAEO,IAAM,YAAY;AAAA,EACvB,YAAY;AAAA,EACZ,UAAU;AAAA,EACV,aAAa;AACf;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { EnsRainbowClientLabelSet, EnsRainbowServerLabelSet, LabelSetId, LabelSetVersion, buildEnsRainbowClientLabelSet } from '@ensnode/ensnode-sdk';
+export { EnsRainbow, EnsRainbowApiClient, EnsRainbowApiClientOptions, isCacheableHealResponse, isHealError } from './client.js';
+export { DEFAULT_ENSRAINBOW_URL, ErrorCode, StatusCode } from './consts.js';

package/dist/index.js

@@ -0,0 +1,223 @@
+// src/index.ts
+import { buildEnsRainbowClientLabelSet as buildEnsRainbowClientLabelSet2 } from "@ensnode/ensnode-sdk";
+
+// src/client.ts
+import {
+  buildEnsRainbowClientLabelSet,
+  LruCache
+} from "@ensnode/ensnode-sdk";
+
+// src/consts.ts
+var DEFAULT_ENSRAINBOW_URL = "https://api.ensrainbow.io";
+var StatusCode = {
+  Success: "success",
+  Error: "error"
+};
+var ErrorCode = {
+  BadRequest: 400,
+  NotFound: 404,
+  ServerError: 500
+};
+
+// src/client.ts
+var EnsRainbowApiClient = class _EnsRainbowApiClient {
+  options;
+  cache;
+  labelSetSearchParams;
+  static DEFAULT_CACHE_CAPACITY = 1e3;
+  /**
+   * Create default client options.
+   *
+   * @returns default options
+   */
+  static defaultOptions() {
+    return {
+      endpointUrl: new URL(DEFAULT_ENSRAINBOW_URL),
+      cacheCapacity: _EnsRainbowApiClient.DEFAULT_CACHE_CAPACITY,
+      labelSet: buildEnsRainbowClientLabelSet()
+    };
+  }
+  constructor(options = {}) {
+    const { labelSet: optionsLabelSet, ...rest } = options;
+    const defaultOptions = _EnsRainbowApiClient.defaultOptions();
+    const copiedLabelSet = buildEnsRainbowClientLabelSet(
+      optionsLabelSet?.labelSetId,
+      optionsLabelSet?.labelSetVersion
+    );
+    this.options = {
+      ...defaultOptions,
+      ...rest,
+      labelSet: copiedLabelSet
+    };
+    this.cache = new LruCache(
+      this.options.cacheCapacity
+    );
+    this.labelSetSearchParams = new URLSearchParams();
+    if (this.options.labelSet?.labelSetId !== void 0) {
+      this.labelSetSearchParams.append("label_set_id", this.options.labelSet.labelSetId);
+    }
+    if (this.options.labelSet?.labelSetVersion !== void 0) {
+      this.labelSetSearchParams.append(
+        "label_set_version",
+        this.options.labelSet.labelSetVersion.toString()
+      );
+    }
+  }
+  /**
+   * Attempt to heal a labelHash to its original label.
+   *
+   * Note on returned labels: ENSRainbow returns labels exactly as they are
+   * represented in source rainbow table data. This means:
+   *
+   * - Labels may or may not be ENS-normalized
+   * - Labels can contain any valid string, including dots, null bytes, or be empty
+   * - Clients should handle all possible string values appropriately
+   *
+   * @param labelHash all lowercase 64-digit hex string with 0x prefix (total length of 66 characters)
+   * @returns a `HealResponse` indicating the result of the request and the healed label if successful
+   * @throws if the request fails due to network failures, DNS lookup failures, request timeouts,
+   * CORS violations, or Invalid URLs
+   * @example
+   * ```typescript
+   * const response = await client.heal(
+   *   "0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc"
+   * );
+   *
+   * console.log(response);
+   *
+   * // Output:
+   * // {
+   * //   status: "success",
+   * //   label: "vitalik"
+   * // }
+   *
+   * const notFoundResponse = await client.heal(
+   *   "0xf64dc17ae2e2b9b16dbcb8cb05f35a2e6080a5ff1dc53ac0bc48f0e79111f264"
+   * );
+   *
+   * console.log(notFoundResponse);
+   *
+   * // Output:
+   * // {
+   * //   status: "error",
+   * //   error: "Label not found",
+   * //   errorCode: 404
+   * // }
+   * ```
+   */
+  async heal(labelHash) {
+    const cachedResult = this.cache.get(labelHash);
+    if (cachedResult) return cachedResult;
+    const url = new URL(`/v1/heal/${labelHash}`, this.options.endpointUrl);
+    this.labelSetSearchParams.forEach((value, key) => {
+      url.searchParams.append(key, value);
+    });
+    const response = await fetch(url);
+    const healResponse = await response.json();
+    if (isCacheableHealResponse(healResponse)) {
+      this.cache.set(labelHash, healResponse);
+    }
+    return healResponse;
+  }
+  /**
+   * Get Count of Healable Labels
+   *
+   * @returns a `CountResponse` indicating the result and the timestamp of the request and the
+   * number of healable labels if successful
+   * @throws if the request fails due to network failures, DNS lookup failures, request timeouts,
+   * CORS violations, or Invalid URLs
+   * @example
+   *
+   * const response = await client.count();
+   *
+   * console.log(response);
+   *
+   * // {
+   * //   "status": "success",
+   * //   "count": 133856894,
+   * //   "timestamp": "2024-01-30T11:18:56Z"
+   * // }
+   *
+   */
+  async count() {
+    const response = await fetch(new URL("/v1/labels/count", this.options.endpointUrl));
+    return response.json();
+  }
+  /**
+   *
+   * Simple verification that the service is running, either in your local setup or for the
+   * provided hosted instance.
+   * @returns a status of ENS Rainbow service
+   * @example
+   *
+   * const response = await client.health();
+   *
+   * console.log(response);
+   *
+   * // {
+   * //   "status": "ok",
+   * // }
+   */
+  async health() {
+    const response = await fetch(new URL("/health", this.options.endpointUrl));
+    return response.json();
+  }
+  /**
+   * Get the version information of the ENSRainbow service
+   *
+   * @returns the version information of the ENSRainbow service
+   * @throws if the request fails due to network failures, DNS lookup failures, request
+   * timeouts, CORS violations, or invalid URLs
+   * @example
+   * ```typescript
+   * const response = await client.version();
+   *
+   * console.log(response);
+   *
+   * // {
+   * //   "status": "success",
+   * //   "versionInfo": {
+   * //     "version": "0.1.0",
+   * //     "dbSchemaVersion": 2,
+   * //     "labelSet": {
+   * //       "labelSetId": "subgraph",
+   * //       "labelSetVersion": 0
+   * //     }
+   * //   }
+   * // }
+   * ```
+   */
+  async version() {
+    const response = await fetch(new URL("/v1/version", this.options.endpointUrl));
+    return response.json();
+  }
+  /**
+   * Get a copy of the current client options.
+   *
+   * @returns a copy of the current client options.
+   */
+  getOptions() {
+    const deepCopy = {
+      cacheCapacity: this.options.cacheCapacity,
+      endpointUrl: new URL(this.options.endpointUrl.href),
+      labelSet: this.options.labelSet ? { ...this.options.labelSet } : void 0
+    };
+    return Object.freeze(deepCopy);
+  }
+};
+var isHealError = (response) => {
+  return response.status === StatusCode.Error;
+};
+var isCacheableHealResponse = (response) => {
+  return response.status === StatusCode.Success || response.errorCode !== ErrorCode.ServerError;
+};
+export {
+  DEFAULT_ENSRAINBOW_URL,
+  EnsRainbowApiClient,
+  ErrorCode,
+  StatusCode,
+  buildEnsRainbowClientLabelSet2 as buildEnsRainbowClientLabelSet,
+  isCacheableHealResponse,
+  isHealError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/client.ts","../src/consts.ts"],"sourcesContent":["// Re-export types from ensnode-sdk that are needed by consumers\nexport type {\n  EnsRainbowClientLabelSet,\n  EnsRainbowServerLabelSet,\n  LabelSetId,\n  LabelSetVersion,\n} from \"@ensnode/ensnode-sdk\";\n// Re-export utility functions and classes from ensnode-sdk that are needed by consumers\nexport { buildEnsRainbowClientLabelSet } from \"@ensnode/ensnode-sdk\";\n\nexport * from \"./client\";\nexport * from \"./consts\";\n","import {\n  buildEnsRainbowClientLabelSet,\n  type Cache,\n  type EnsRainbowClientLabelSet,\n  type EnsRainbowServerLabelSet,\n  type Label,\n  type LabelHash,\n  LruCache,\n} from \"@ensnode/ensnode-sdk\";\n\nimport { DEFAULT_ENSRAINBOW_URL, ErrorCode, StatusCode } from \"./consts\";\n\nexport namespace EnsRainbow {\n  export type ApiClientOptions = EnsRainbowApiClientOptions;\n\n  export interface ApiClient {\n    count(): Promise<CountResponse>;\n\n    /**\n     * Heal a labelhash to its original label\n     * @param labelHash The labelhash to heal\n     */\n    heal(labelHash: LabelHash): Promise<HealResponse>;\n\n    health(): Promise<HealthResponse>;\n\n    version(): Promise<VersionResponse>;\n\n    getOptions(): Readonly<EnsRainbowApiClientOptions>;\n  }\n\n  type StatusCode = (typeof StatusCode)[keyof typeof StatusCode];\n\n  type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];\n\n  export interface HealthResponse {\n    status: \"ok\";\n  }\n\n  export interface BaseHealResponse<Status extends StatusCode, Error extends ErrorCode> {\n    status: Status;\n    label?: Label | never;\n    error?: string | never;\n    errorCode?: Error | never;\n  }\n\n  export interface HealSuccess extends BaseHealResponse<typeof StatusCode.Success, never> {\n    status: typeof StatusCode.Success;\n    label: Label;\n    error?: never;\n    errorCode?: never;\n  }\n\n  export interface HealNotFoundError\n    extends BaseHealResponse<typeof StatusCode.Error, typeof ErrorCode.NotFound> {\n    status: typeof StatusCode.Error;\n    label?: never;\n    error: string;\n    errorCode: typeof ErrorCode.NotFound;\n  }\n\n  export interface HealServerError\n    extends BaseHealResponse<typeof StatusCode.Error, typeof ErrorCode.ServerError> {\n    status: typeof StatusCode.Error;\n    label?: never;\n    error: string;\n    errorCode: typeof ErrorCode.ServerError;\n  }\n\n  export interface HealBadRequestError\n    extends BaseHealResponse<typeof StatusCode.Error, typeof ErrorCode.BadRequest> {\n    status: typeof StatusCode.Error;\n    label?: never;\n    error: string;\n    errorCode: typeof ErrorCode.BadRequest;\n  }\n\n  export type HealResponse =\n    | HealSuccess\n    | HealNotFoundError\n    | HealServerError\n    | HealBadRequestError;\n  export type HealError = Exclude<HealResponse, HealSuccess>;\n\n  /**\n   * Server errors should not be cached.\n   */\n  export type CacheableHealResponse = Exclude<HealResponse, HealServerError>;\n\n  export interface BaseCountResponse<Status extends StatusCode, Error extends ErrorCode> {\n    status: Status;\n    count?: number | never;\n    timestamp?: string | never;\n    error?: string | never;\n    errorCode?: Error | never;\n  }\n\n  export interface CountSuccess extends BaseCountResponse<typeof StatusCode.Success, never> {\n    status: typeof StatusCode.Success;\n    /** The total count of labels that can be healed by the ENSRainbow instance. Always a\n     * non-negative integer. */\n    count: number;\n    timestamp: string;\n    error?: never;\n    errorCode?: never;\n  }\n\n  export interface CountServerError\n    extends BaseCountResponse<typeof StatusCode.Error, typeof ErrorCode.ServerError> {\n    status: typeof StatusCode.Error;\n    count?: never;\n    timestamp?: never;\n    error: string;\n    errorCode: typeof ErrorCode.ServerError;\n  }\n\n  export type CountResponse = CountSuccess | CountServerError;\n\n  /**\n   * ENSRainbow version information.\n   */\n  export interface VersionInfo {\n    /**\n     * ENSRainbow version.\n     */\n    version: string;\n\n    /**\n     * ENSRainbow database schema version.\n     */\n    dbSchemaVersion: number;\n\n    /**\n     * The EnsRainbowServerLabelSet managed by the ENSRainbow server.\n     */\n    labelSet: EnsRainbowServerLabelSet;\n  }\n\n  /**\n   * Interface for the version endpoint response\n   */\n  export interface VersionResponse {\n    status: typeof StatusCode.Success;\n    versionInfo: VersionInfo;\n  }\n}\n\nexport interface EnsRainbowApiClientOptions {\n  /**\n   * The maximum number of `HealResponse` values to cache.\n   * Must be a non-negative integer.\n   * Setting to 0 will disable caching.\n   */\n  cacheCapacity: number;\n\n  /**\n   * The URL of an ENSRainbow API endpoint.\n   */\n  endpointUrl: URL;\n\n  /**\n   * Optional label set preferences that the ENSRainbow server at endpointUrl is expected to\n   * support. If provided, enables deterministic heal results across time, such that only\n   * labels from label sets with versions less than or equal to this value will be returned.\n   * Therefore, even if the ENSRainbow server later ingests label sets with greater versions\n   * than this value, the results returned across time can be deterministic. If\n   * provided, heal operations with this EnsRainbowApiClient will validate the ENSRainbow\n   * server manages a compatible label set. If not provided no specific labelSetId validation\n   * will be performed during heal operations.\n   * If `labelSetId` is provided without `labelSetVersion`, the server will use the latest\n   * available version.\n   * If `labelSetVersion` is defined, only labels from sets less than or equal to this value\n   * will be returned.\n   * When `labelSetVersion` is defined, `labelSetId` must also be defined.\n   */\n  labelSet?: EnsRainbowClientLabelSet;\n}\n\n/**\n * ENSRainbow API client\n *\n * @example\n * ```typescript\n * // default options\n * const client = new EnsRainbowApiClient();\n * // custom options\n * const client = new EnsRainbowApiClient({\n *  endpointUrl: new URL(\"https://api.ensrainbow.io\"),\n * });\n * ```\n */\nexport class EnsRainbowApiClient implements EnsRainbow.ApiClient {\n  private readonly options: EnsRainbowApiClientOptions;\n  private readonly cache: Cache<LabelHash, EnsRainbow.CacheableHealResponse>;\n  private readonly labelSetSearchParams: URLSearchParams;\n\n  public static readonly DEFAULT_CACHE_CAPACITY = 1000;\n\n  /**\n   * Create default client options.\n   *\n   * @returns default options\n   */\n  static defaultOptions(): EnsRainbow.ApiClientOptions {\n    return {\n      endpointUrl: new URL(DEFAULT_ENSRAINBOW_URL),\n      cacheCapacity: EnsRainbowApiClient.DEFAULT_CACHE_CAPACITY,\n      labelSet: buildEnsRainbowClientLabelSet(),\n    };\n  }\n\n  constructor(options: Partial<EnsRainbow.ApiClientOptions> = {}) {\n    const { labelSet: optionsLabelSet, ...rest } = options;\n    const defaultOptions = EnsRainbowApiClient.defaultOptions();\n\n    const copiedLabelSet = buildEnsRainbowClientLabelSet(\n      optionsLabelSet?.labelSetId,\n      optionsLabelSet?.labelSetVersion,\n    );\n\n    this.options = {\n      ...defaultOptions,\n      ...rest,\n      labelSet: copiedLabelSet,\n    };\n\n    this.cache = new LruCache<LabelHash, EnsRainbow.CacheableHealResponse>(\n      this.options.cacheCapacity,\n    );\n\n    // Pre-compute query parameters for label set options\n    this.labelSetSearchParams = new URLSearchParams();\n    if (this.options.labelSet?.labelSetId !== undefined) {\n      this.labelSetSearchParams.append(\"label_set_id\", this.options.labelSet.labelSetId);\n    }\n    if (this.options.labelSet?.labelSetVersion !== undefined) {\n      this.labelSetSearchParams.append(\n        \"label_set_version\",\n        this.options.labelSet.labelSetVersion.toString(),\n      );\n    }\n  }\n\n  /**\n   * Attempt to heal a labelHash to its original label.\n   *\n   * Note on returned labels: ENSRainbow returns labels exactly as they are\n   * represented in source rainbow table data. This means:\n   *\n   * - Labels may or may not be ENS-normalized\n   * - Labels can contain any valid string, including dots, null bytes, or be empty\n   * - Clients should handle all possible string values appropriately\n   *\n   * @param labelHash all lowercase 64-digit hex string with 0x prefix (total length of 66 characters)\n   * @returns a `HealResponse` indicating the result of the request and the healed label if successful\n   * @throws if the request fails due to network failures, DNS lookup failures, request timeouts,\n   * CORS violations, or Invalid URLs\n   * @example\n   * ```typescript\n   * const response = await client.heal(\n   *   \"0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc\"\n   * );\n   *\n   * console.log(response);\n   *\n   * // Output:\n   * // {\n   * //   status: \"success\",\n   * //   label: \"vitalik\"\n   * // }\n   *\n   * const notFoundResponse = await client.heal(\n   *   \"0xf64dc17ae2e2b9b16dbcb8cb05f35a2e6080a5ff1dc53ac0bc48f0e79111f264\"\n   * );\n   *\n   * console.log(notFoundResponse);\n   *\n   * // Output:\n   * // {\n   * //   status: \"error\",\n   * //   error: \"Label not found\",\n   * //   errorCode: 404\n   * // }\n   * ```\n   */\n  async heal(labelHash: LabelHash): Promise<EnsRainbow.HealResponse> {\n    const cachedResult = this.cache.get(labelHash);\n    if (cachedResult) return cachedResult;\n\n    const url = new URL(`/v1/heal/${labelHash}`, this.options.endpointUrl);\n\n    // Apply pre-computed label set query parameters\n    this.labelSetSearchParams.forEach((value, key) => {\n      url.searchParams.append(key, value);\n    });\n\n    const response = await fetch(url);\n    const healResponse = (await response.json()) as EnsRainbow.HealResponse;\n\n    if (isCacheableHealResponse(healResponse)) {\n      this.cache.set(labelHash, healResponse);\n    }\n\n    return healResponse;\n  }\n\n  /**\n   * Get Count of Healable Labels\n   *\n   * @returns a `CountResponse` indicating the result and the timestamp of the request and the\n   * number of healable labels if successful\n   * @throws if the request fails due to network failures, DNS lookup failures, request timeouts,\n   * CORS violations, or Invalid URLs\n   * @example\n   *\n   * const response = await client.count();\n   *\n   * console.log(response);\n   *\n   * // {\n   * //   \"status\": \"success\",\n   * //   \"count\": 133856894,\n   * //   \"timestamp\": \"2024-01-30T11:18:56Z\"\n   * // }\n   *\n   */\n  async count(): Promise<EnsRainbow.CountResponse> {\n    const response = await fetch(new URL(\"/v1/labels/count\", this.options.endpointUrl));\n\n    return response.json() as Promise<EnsRainbow.CountResponse>;\n  }\n\n  /**\n   *\n   * Simple verification that the service is running, either in your local setup or for the\n   * provided hosted instance.\n   * @returns a status of ENS Rainbow service\n   * @example\n   *\n   * const response = await client.health();\n   *\n   * console.log(response);\n   *\n   * // {\n   * //   \"status\": \"ok\",\n   * // }\n   */\n  async health(): Promise<EnsRainbow.HealthResponse> {\n    const response = await fetch(new URL(\"/health\", this.options.endpointUrl));\n\n    return response.json() as Promise<EnsRainbow.HealthResponse>;\n  }\n\n  /**\n   * Get the version information of the ENSRainbow service\n   *\n   * @returns the version information of the ENSRainbow service\n   * @throws if the request fails due to network failures, DNS lookup failures, request\n   * timeouts, CORS violations, or invalid URLs\n   * @example\n   * ```typescript\n   * const response = await client.version();\n   *\n   * console.log(response);\n   *\n   * // {\n   * //   \"status\": \"success\",\n   * //   \"versionInfo\": {\n   * //     \"version\": \"0.1.0\",\n   * //     \"dbSchemaVersion\": 2,\n   * //     \"labelSet\": {\n   * //       \"labelSetId\": \"subgraph\",\n   * //       \"labelSetVersion\": 0\n   * //     }\n   * //   }\n   * // }\n   * ```\n   */\n  async version(): Promise<EnsRainbow.VersionResponse> {\n    const response = await fetch(new URL(\"/v1/version\", this.options.endpointUrl));\n\n    return response.json() as Promise<EnsRainbow.VersionResponse>;\n  }\n\n  /**\n   * Get a copy of the current client options.\n   *\n   * @returns a copy of the current client options.\n   */\n  getOptions(): Readonly<EnsRainbowApiClientOptions> {\n    // build a deep copy to prevent modification\n    const deepCopy = {\n      cacheCapacity: this.options.cacheCapacity,\n      endpointUrl: new URL(this.options.endpointUrl.href),\n      labelSet: this.options.labelSet ? { ...this.options.labelSet } : undefined,\n    } satisfies EnsRainbowApiClientOptions;\n\n    return Object.freeze(deepCopy);\n  }\n}\n\n/**\n * Determine if a heal response is an error.\n *\n * @param response the heal response to check\n * @returns true if the response is an error, false otherwise\n */\nexport const isHealError = (\n  response: EnsRainbow.HealResponse,\n): response is EnsRainbow.HealError => {\n  return response.status === StatusCode.Error;\n};\n\n/**\n * Determine if a heal response is cacheable.\n *\n * Server errors at not cachable and should be retried.\n *\n * @param response the heal response to check\n * @returns true if the response is cacheable, false otherwise\n */\nexport const isCacheableHealResponse = (\n  response: EnsRainbow.HealResponse,\n): response is EnsRainbow.CacheableHealResponse => {\n  return response.status === StatusCode.Success || response.errorCode !== ErrorCode.ServerError;\n};\n","export const DEFAULT_ENSRAINBOW_URL = \"https://api.ensrainbow.io\" as const;\n\nexport const StatusCode = {\n  Success: \"success\",\n  Error: \"error\",\n} as const;\n\nexport const ErrorCode = {\n  BadRequest: 400,\n  NotFound: 404,\n  ServerError: 500,\n} as const;\n"],"mappings":"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","names":["buildEnsRainbowClientLabelSet"]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@ensnode/ensrainbow-sdk",
+  "version": "0.0.0-next-20260102143513",
+  "type": "module",
+  "description": "ENSRainbow SDK for interacting with the ENSRainbow API.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/namehash/ensnode.git",
+    "directory": "packages/ensrainbow-sdk"
+  },
+  "homepage": "https://github.com/namehash/ensnode/tree/main/packages/ensrainbow-sdk",
+  "keywords": [
+    "ENS",
+    "ENSNode",
+    "ENSRainbow"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./consts": {
+      "types": "./dist/consts.d.ts",
+      "default": "./dist/consts.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "viem": "^2.22.13"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.2",
+    "@ensnode/shared-configs": "0.0.0-next-20260102143513",
+    "@ensnode/ensnode-sdk": "0.0.0-next-20260102143513"
+  },
+  "scripts": {
+    "prepublish": "tsup",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check --write .",
+    "lint:ci": "biome ci"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts"
+}