@ensnode/ensrainbow-sdk 0.1.0

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,216 @@
+import { Labelhash } from '@ensnode/utils/types';
+
+declare namespace EnsRainbow {
+    export type ApiClientOptions = EnsRainbowApiClientOptions;
+    export interface ApiClient {
+        count(): Promise<CountResponse>;
+        heal(labelhash: Labelhash): Promise<HealResponse>;
+        health(): Promise<HealthResponse>;
+        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?: string | never;
+        error?: string | never;
+        errorCode?: Error | never;
+    }
+    export interface HealSuccess extends BaseHealResponse<typeof StatusCode.Success, never> {
+        status: typeof StatusCode.Success;
+        label: string;
+        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;
+    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;
+}
+/**
+ * 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;
+    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 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,161 @@
+// src/client.ts
+import { LruCache } from "@ensnode/utils/cache";
+
+// 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;
+  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
+    };
+  }
+  constructor(options = {}) {
+    this.options = {
+      ..._EnsRainbowApiClient.defaultOptions(),
+      ...options
+    };
+    this.cache = new LruCache(
+      this.options.cacheCapacity
+    );
+  }
+  /**
+   * 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 response = await fetch(new URL(`/v1/heal/${labelhash}`, this.options.endpointUrl));
+    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 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)
+    };
+    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 type { Cache } from \"@ensnode/utils/cache\";\nimport { LruCache } from \"@ensnode/utils/cache\";\nimport type { Labelhash } from \"@ensnode/utils/types\";\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    heal(labelhash: Labelhash): Promise<HealResponse>;\n\n    health(): Promise<HealthResponse>;\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?: string | 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: string;\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 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\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/**\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\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    };\n  }\n\n  constructor(options: Partial<EnsRainbow.ApiClientOptions> = {}) {\n    this.options = {\n      ...EnsRainbowApiClient.defaultOptions(),\n      ...options,\n    };\n\n    this.cache = new LruCache<Labelhash, EnsRainbow.CacheableHealResponse>(\n      this.options.cacheCapacity,\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, CORS violations, or Invalid URLs\n   *\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\n    if (cachedResult) {\n      return cachedResult;\n    }\n\n    const response = await fetch(new URL(`/v1/heal/${labelhash}`, this.options.endpointUrl));\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 number of healable labels if successful\n   * @throws if the request fails due to network failures, DNS lookup failures, request timeouts, CORS violations, or Invalid URLs\n   *\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 provided hosted instance\n   *\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 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    } 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":";AACA,SAAS,gBAAgB;;;ACDlB,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;;;ADyHO,IAAM,sBAAN,MAAM,qBAAoD;AAAA,EAC9C;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,IACrC;AAAA,EACF;AAAA,EAEA,YAAY,UAAgD,CAAC,GAAG;AAC9D,SAAK,UAAU;AAAA,MACb,GAAG,qBAAoB,eAAe;AAAA,MACtC,GAAG;AAAA,IACL;AAEA,SAAK,QAAQ,IAAI;AAAA,MACf,KAAK,QAAQ;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;AAE7C,QAAI,cAAc;AAChB,aAAO;AAAA,IACT;AAEA,UAAM,WAAW,MAAM,MAAM,IAAI,IAAI,YAAY,SAAS,IAAI,KAAK,QAAQ,WAAW,CAAC;AACvF,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,EAqBA,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,EAOA,aAAmD;AAEjD,UAAM,WAAW;AAAA,MACf,eAAe,KAAK,QAAQ;AAAA,MAC5B,aAAa,IAAI,IAAI,KAAK,QAAQ,YAAY,IAAI;AAAA,IACpD;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,5 @@
+export { EnsRainbow, EnsRainbowApiClient, EnsRainbowApiClientOptions, isCacheableHealResponse, isHealError } from './client.js';
+export { DEFAULT_ENSRAINBOW_URL, ErrorCode, StatusCode } from './consts.js';
+export { labelHashToBytes } from './labelUtils.js';
+import '@ensnode/utils/types';
+import 'viem';

package/dist/index.js

@@ -0,0 +1,191 @@
+// src/client.ts
+import { LruCache } from "@ensnode/utils/cache";
+
+// 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;
+  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
+    };
+  }
+  constructor(options = {}) {
+    this.options = {
+      ..._EnsRainbowApiClient.defaultOptions(),
+      ...options
+    };
+    this.cache = new LruCache(
+      this.options.cacheCapacity
+    );
+  }
+  /**
+   * 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 response = await fetch(new URL(`/v1/heal/${labelhash}`, this.options.endpointUrl));
+    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 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)
+    };
+    return Object.freeze(deepCopy);
+  }
+};
+var isHealError = (response) => {
+  return response.status === StatusCode.Error;
+};
+var isCacheableHealResponse = (response) => {
+  return response.status === StatusCode.Success || response.errorCode !== ErrorCode.ServerError;
+};
+
+// src/label-utils.ts
+import { hexToBytes } from "viem";
+function labelHashToBytes(labelHash) {
+  try {
+    if (labelHash.length !== 66) {
+      throw new Error(`Invalid labelhash length ${labelHash.length} characters (expected 66)`);
+    }
+    if (labelHash !== labelHash.toLowerCase()) {
+      throw new Error("Labelhash must be in lowercase");
+    }
+    if (!labelHash.startsWith("0x")) {
+      throw new Error("Labelhash must be 0x-prefixed");
+    }
+    const bytes = hexToBytes(labelHash);
+    if (bytes.length !== 32) {
+      throw new Error(`Invalid labelhash length ${bytes.length} bytes (expected 32)`);
+    }
+    return bytes;
+  } catch (e) {
+    if (e instanceof Error) {
+      throw e;
+    }
+    throw new Error("Invalid hex format");
+  }
+}
+export {
+  DEFAULT_ENSRAINBOW_URL,
+  EnsRainbowApiClient,
+  ErrorCode,
+  StatusCode,
+  isCacheableHealResponse,
+  isHealError,
+  labelHashToBytes
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts","../src/consts.ts","../src/label-utils.ts"],"sourcesContent":["import type { Cache } from \"@ensnode/utils/cache\";\nimport { LruCache } from \"@ensnode/utils/cache\";\nimport type { Labelhash } from \"@ensnode/utils/types\";\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    heal(labelhash: Labelhash): Promise<HealResponse>;\n\n    health(): Promise<HealthResponse>;\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?: string | 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: string;\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 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\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/**\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\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    };\n  }\n\n  constructor(options: Partial<EnsRainbow.ApiClientOptions> = {}) {\n    this.options = {\n      ...EnsRainbowApiClient.defaultOptions(),\n      ...options,\n    };\n\n    this.cache = new LruCache<Labelhash, EnsRainbow.CacheableHealResponse>(\n      this.options.cacheCapacity,\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, CORS violations, or Invalid URLs\n   *\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\n    if (cachedResult) {\n      return cachedResult;\n    }\n\n    const response = await fetch(new URL(`/v1/heal/${labelhash}`, this.options.endpointUrl));\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 number of healable labels if successful\n   * @throws if the request fails due to network failures, DNS lookup failures, request timeouts, CORS violations, or Invalid URLs\n   *\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 provided hosted instance\n   *\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 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    } 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","import type { Labelhash } from \"@ensnode/utils/types\";\nimport { ByteArray, hexToBytes } from \"viem\";\n\n/**\n * Converts a Labelhash to bytes, with validation\n * @param labelHash The Labelhash to convert\n * @returns A ByteArray containing the bytes\n * @throws Error if `labelHash` is not a valid 32-byte hex string\n */\nexport function labelHashToBytes(labelHash: Labelhash): ByteArray {\n  try {\n    if (labelHash.length !== 66) {\n      throw new Error(`Invalid labelhash length ${labelHash.length} characters (expected 66)`);\n    }\n    if (labelHash !== labelHash.toLowerCase()) {\n      throw new Error(\"Labelhash must be in lowercase\");\n    }\n    if (!labelHash.startsWith(\"0x\")) {\n      throw new Error(\"Labelhash must be 0x-prefixed\");\n    }\n    const bytes = hexToBytes(labelHash);\n    if (bytes.length !== 32) {\n      // should be redundant but keeping it for the principle of defensive programming\n      throw new Error(`Invalid labelhash length ${bytes.length} bytes (expected 32)`);\n    }\n    return bytes;\n  } catch (e) {\n    if (e instanceof Error) {\n      throw e;\n    }\n    throw new Error(\"Invalid hex format\");\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/label-utils.d.ts

@@ -0,0 +1,3 @@
+import '@ensnode/utils/types';
+import 'viem';
+export { labelHashToBytes } from './labelUtils.js';

package/dist/label-utils.js

@@ -0,0 +1,29 @@
+// src/label-utils.ts
+import { hexToBytes } from "viem";
+function labelHashToBytes(labelHash) {
+  try {
+    if (labelHash.length !== 66) {
+      throw new Error(`Invalid labelhash length ${labelHash.length} characters (expected 66)`);
+    }
+    if (labelHash !== labelHash.toLowerCase()) {
+      throw new Error("Labelhash must be in lowercase");
+    }
+    if (!labelHash.startsWith("0x")) {
+      throw new Error("Labelhash must be 0x-prefixed");
+    }
+    const bytes = hexToBytes(labelHash);
+    if (bytes.length !== 32) {
+      throw new Error(`Invalid labelhash length ${bytes.length} bytes (expected 32)`);
+    }
+    return bytes;
+  } catch (e) {
+    if (e instanceof Error) {
+      throw e;
+    }
+    throw new Error("Invalid hex format");
+  }
+}
+export {
+  labelHashToBytes
+};
+//# sourceMappingURL=label-utils.js.map

package/dist/label-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/label-utils.ts"],"sourcesContent":["import type { Labelhash } from \"@ensnode/utils/types\";\nimport { ByteArray, hexToBytes } from \"viem\";\n\n/**\n * Converts a Labelhash to bytes, with validation\n * @param labelHash The Labelhash to convert\n * @returns A ByteArray containing the bytes\n * @throws Error if `labelHash` is not a valid 32-byte hex string\n */\nexport function labelHashToBytes(labelHash: Labelhash): ByteArray {\n  try {\n    if (labelHash.length !== 66) {\n      throw new Error(`Invalid labelhash length ${labelHash.length} characters (expected 66)`);\n    }\n    if (labelHash !== labelHash.toLowerCase()) {\n      throw new Error(\"Labelhash must be in lowercase\");\n    }\n    if (!labelHash.startsWith(\"0x\")) {\n      throw new Error(\"Labelhash must be 0x-prefixed\");\n    }\n    const bytes = hexToBytes(labelHash);\n    if (bytes.length !== 32) {\n      // should be redundant but keeping it for the principle of defensive programming\n      throw new Error(`Invalid labelhash length ${bytes.length} bytes (expected 32)`);\n    }\n    return bytes;\n  } catch (e) {\n    if (e instanceof Error) {\n      throw e;\n    }\n    throw new Error(\"Invalid hex format\");\n  }\n}\n"],"mappings":";AACA,SAAoB,kBAAkB;AAQ/B,SAAS,iBAAiB,WAAiC;AAChE,MAAI;AACF,QAAI,UAAU,WAAW,IAAI;AAC3B,YAAM,IAAI,MAAM,4BAA4B,UAAU,MAAM,2BAA2B;AAAA,IACzF;AACA,QAAI,cAAc,UAAU,YAAY,GAAG;AACzC,YAAM,IAAI,MAAM,gCAAgC;AAAA,IAClD;AACA,QAAI,CAAC,UAAU,WAAW,IAAI,GAAG;AAC/B,YAAM,IAAI,MAAM,+BAA+B;AAAA,IACjD;AACA,UAAM,QAAQ,WAAW,SAAS;AAClC,QAAI,MAAM,WAAW,IAAI;AAEvB,YAAM,IAAI,MAAM,4BAA4B,MAAM,MAAM,sBAAsB;AAAA,IAChF;AACA,WAAO;AAAA,EACT,SAAS,GAAG;AACV,QAAI,aAAa,OAAO;AACtB,YAAM;AAAA,IACR;AACA,UAAM,IAAI,MAAM,oBAAoB;AAAA,EACtC;AACF;","names":[]}

package/dist/labelUtils.d.ts

@@ -0,0 +1,12 @@
+import { Labelhash } from '@ensnode/utils/types';
+import { ByteArray } from 'viem';
+
+/**
+ * Converts a Labelhash to bytes, with validation
+ * @param labelHash The Labelhash to convert
+ * @returns A ByteArray containing the bytes
+ * @throws Error if `labelHash` is not a valid 32-byte hex string
+ */
+declare function labelHashToBytes(labelHash: Labelhash): ByteArray;
+
+export { labelHashToBytes };

package/dist/labelUtils.js

@@ -0,0 +1,29 @@
+// src/label-utils.ts
+import { hexToBytes } from "viem";
+function labelHashToBytes(labelHash) {
+  try {
+    if (labelHash.length !== 66) {
+      throw new Error(`Invalid labelhash length ${labelHash.length} characters (expected 66)`);
+    }
+    if (labelHash !== labelHash.toLowerCase()) {
+      throw new Error("Labelhash must be in lowercase");
+    }
+    if (!labelHash.startsWith("0x")) {
+      throw new Error("Labelhash must be 0x-prefixed");
+    }
+    const bytes = hexToBytes(labelHash);
+    if (bytes.length !== 32) {
+      throw new Error(`Invalid labelhash length ${bytes.length} bytes (expected 32)`);
+    }
+    return bytes;
+  } catch (e) {
+    if (e instanceof Error) {
+      throw e;
+    }
+    throw new Error("Invalid hex format");
+  }
+}
+export {
+  labelHashToBytes
+};
+//# sourceMappingURL=labelUtils.js.map

package/dist/labelUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/label-utils.ts"],"sourcesContent":["import type { Labelhash } from \"@ensnode/utils/types\";\nimport { ByteArray, hexToBytes } from \"viem\";\n\n/**\n * Converts a Labelhash to bytes, with validation\n * @param labelHash The Labelhash to convert\n * @returns A ByteArray containing the bytes\n * @throws Error if `labelHash` is not a valid 32-byte hex string\n */\nexport function labelHashToBytes(labelHash: Labelhash): ByteArray {\n  try {\n    if (labelHash.length !== 66) {\n      throw new Error(`Invalid labelhash length ${labelHash.length} characters (expected 66)`);\n    }\n    if (labelHash !== labelHash.toLowerCase()) {\n      throw new Error(\"Labelhash must be in lowercase\");\n    }\n    if (!labelHash.startsWith(\"0x\")) {\n      throw new Error(\"Labelhash must be 0x-prefixed\");\n    }\n    const bytes = hexToBytes(labelHash);\n    if (bytes.length !== 32) {\n      // should be redundant but keeping it for the principle of defensive programming\n      throw new Error(`Invalid labelhash length ${bytes.length} bytes (expected 32)`);\n    }\n    return bytes;\n  } catch (e) {\n    if (e instanceof Error) {\n      throw e;\n    }\n    throw new Error(\"Invalid hex format\");\n  }\n}\n"],"mappings":";AACA,SAAoB,kBAAkB;AAQ/B,SAAS,iBAAiB,WAAiC;AAChE,MAAI;AACF,QAAI,UAAU,WAAW,IAAI;AAC3B,YAAM,IAAI,MAAM,4BAA4B,UAAU,MAAM,2BAA2B;AAAA,IACzF;AACA,QAAI,cAAc,UAAU,YAAY,GAAG;AACzC,YAAM,IAAI,MAAM,gCAAgC;AAAA,IAClD;AACA,QAAI,CAAC,UAAU,WAAW,IAAI,GAAG;AAC/B,YAAM,IAAI,MAAM,+BAA+B;AAAA,IACjD;AACA,UAAM,QAAQ,WAAW,SAAS;AAClC,QAAI,MAAM,WAAW,IAAI;AAEvB,YAAM,IAAI,MAAM,4BAA4B,MAAM,MAAM,sBAAsB;AAAA,IAChF;AACA,WAAO;AAAA,EACT,SAAS,GAAG;AACV,QAAI,aAAa,OAAO;AACtB,YAAM;AAAA,IACR;AACA,UAAM,IAAI,MAAM,oBAAoB;AAAA,EACtC;AACF;","names":[]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@ensnode/ensrainbow-sdk",
+  "version": "0.1.0",
+  "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"
+  ],
+  "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"
+    },
+    "./label-utils": {
+      "types": "./dist/label-utils.d.ts",
+      "default": "./dist/label-utils.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "viem": "^2.22.13"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@ensnode/shared-configs": "",
+    "@ensnode/utils": "",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  },
+  "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"
+}