@namehash/ens-referrals 1.8.1 → 1.9.0

package/README.md

@@ -1,6 +1,8 @@
 # ENS Referrals
 
-This package provides utilities for working with ENS Referrals, including useful types and utility functions.
+Utilities for working with ENS Referrals data. This package is intended for developers who want to build referral dashboards, stats pages, or other integrations on top of ENS Referrals APIs.
+
+The main entry point today is [`v1`](https://github.com/namehash/ensnode/tree/main/packages/ens-referrals/src/v1), which includes the current client and response types for the latest ENS Referrals program format.
 
 ## Installation
 
@@ -8,24 +10,161 @@ This package provides utilities for working with ENS Referrals, including useful
 npm install @namehash/ens-referrals viem
 ```
 
-### Basic Usage
+## Quick Start
+
+`v1` is the recommended version for new integrations.
+
+- [`v1`](https://github.com/namehash/ensnode/tree/main/packages/ens-referrals/src/v1) is the actively supported version that reflects the current ENS Referrals program rules and awards.
+- The root [`@namehash/ens-referrals`](https://github.com/namehash/ensnode/tree/main/packages/ens-referrals/src/client.ts) import is deprecated and is planned to be removed soon.
+
+### Set up `ENSReferralsClient`
+
+`ENSReferralsClient` is the main way to read referral data from ENSNode.
 
 ```typescript
-import {
-  buildEncodedReferrer,
-  decodeEncodedReferrer,
-  buildEnsReferralUrl
-} from "@namehash/ens-referrals";
-import type { Address } from 'viem';
+import { ENSReferralsClient } from "@namehash/ens-referrals/v1";
 
-const referrerAddress: Address = "0xd8da6bf26964af9d7eed9e03e53415d37aa96045";
+// Create a client with the default ENSNode API URL
+const client = new ENSReferralsClient();
+```
+
+If you want to use a specific ENSNode deployment, pass its URL to the client:
+
+```typescript
+const client = new ENSReferralsClient({
+  url: new URL("https://my-ensnode-instance.com"),
+});
+```
+
+## Use ENS Referrals API (`v1`)
+
+### Get all referral program editions → `getEditionSummaries()`
+
+Returns the currently configured referral program editions. Editions are sorted by start time, with the newest edition first.
+
+Use these edition slugs when calling the leaderboard and referrer endpoints.
+
+```typescript
+const response = await client.getEditionSummaries();
+
+if (response.responseCode === ReferralProgramEditionSummariesResponseCodes.Ok) {
+  console.log(`Found ${response.data.editions.length} editions`);
+
+  for (const edition of response.data.editions) {
+    console.log(`${edition.slug}: ${edition.displayName}`);
+  }
+}
+```
+
+More examples are available in [`packages/ens-referrals/src/v1/client.ts`](https://github.com/namehash/ensnode/tree/main/packages/ens-referrals/src/v1/client.ts).
+
+### Get a referrer leaderboard page → `getReferrerLeaderboardPage()`
+
+Returns a paginated leaderboard for a specific referral program edition.
+
+```typescript
+const editionSlug = "2025-12";
 
-// Build an encoded referrer value (according to the subjective referrer encoding used for ENS Holiday Awards)
-const encodedReferrer = buildEncodedReferrer(referrerAddress); // 0x000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa96045
+const response = await client.getReferrerLeaderboardPage({
+  edition: editionSlug,
+});
 
-// Decode an encoded referrer value (according to the subjective referrer encoding used for ENS Holiday Awards)
-const decodedReferrer = decodeEncodedReferrer(encodedReferrer); // 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+if (response.responseCode === ReferrerLeaderboardPageResponseCodes.Ok) {
+  const leaderboardPage = response.data;
+
+  if (leaderboardPage.awardModel === ReferralProgramAwardModels.Unrecognized) {
+    // gracefully handle forwards-compatibility as new award models are added in the future
+    console.log(`Unrecognized award model: ${leaderboardPage.originalAwardModel} - skipping`);
+  } else {
+    console.log(`Edition: ${editionSlug}`);
+    console.log(`Subregistry: ${leaderboardPage.rules.subregistryId}`);
+    console.log(`Total Referrers: ${leaderboardPage.pageContext.totalRecords}`);
+    console.log(
+      `Page ${leaderboardPage.pageContext.page} of ${leaderboardPage.pageContext.totalPages}`,
+    );
+
+    const noReferrersFallback = "No referrers in this edition";
+    const firstReferrer = leaderboardPage.referrers[0] ?? null;
+
+    if (leaderboardPage.awardModel === ReferralProgramAwardModels.PieSplit) {
+      console.log(`Max Qualified Referrers: ${leaderboardPage.rules.maxQualifiedReferrers}`);
+      console.log(
+        `First Referrer's Final Score Boost: ${firstReferrer !== null ? firstReferrer.finalScoreBoost : noReferrersFallback}`,
+      );
+      console.log(
+        `First Referrer's Award Pool Share: ${firstReferrer !== null ? firstReferrer.awardPoolShare : noReferrersFallback}`,
+      );
+    }
+
+    if (leaderboardPage.awardModel === ReferralProgramAwardModels.RevShareLimit) {
+      console.log(
+        `Min Qualified Revenue Contribution: ${leaderboardPage.rules.minQualifiedRevenueContribution}`,
+      );
+      console.log(`Qualified Revenue Share: ${leaderboardPage.rules.qualifiedRevenueShare}`);
+      console.log(
+        `Tentative award for the best referrer: ${firstReferrer !== null ? firstReferrer.awardPoolApproxValue : noReferrersFallback}`,
+      );
+    }
+  }
+}
+```
+
+More examples are available in [`packages/ens-referrals/src/v1/client.ts`](https://github.com/namehash/ensnode/tree/main/packages/ens-referrals/src/v1/client.ts).
+
+### Get a referrer's metrics across editions → `getReferrerMetricsEditions()`
+
+Returns referrer metrics for a specified referrer across one or more editions.
+
+```typescript
+const response = await client.getReferrerMetricsEditions({
+  referrer: "0x1234567890123456789012345678901234567890",
+  editions: ["2025-12", "2026-01"],
+});
+
+if (response.responseCode === ReferrerMetricsEditionsResponseCodes.Ok) {
+  for (const [editionSlug, detail] of Object.entries(response.data)) {
+    console.log(`Edition: ${editionSlug}`);
+
+    if (detail.awardModel === ReferralProgramAwardModels.Unrecognized) {
+      // gracefully handle forwards-compatibility as new award models are added in the future
+      console.log(`Unrecognized award model: ${detail.originalAwardModel} - skipping`);
+      continue;
+    }
+
+    console.log(`Type: ${detail.type}`);
+
+    if (detail.type === ReferrerEditionMetricsTypeIds.Ranked) {
+      console.log(`Rank: ${detail.referrer.rank}`);
+    }
+
+    if (detail.awardModel === ReferralProgramAwardModels.PieSplit) {
+      console.log(`Referrer's Final Score: ${detail.referrer.finalScore}`);
+      console.log(`Referrer's Award Pool Share: ${detail.referrer.awardPoolShare * 100}%`);
+    }
+
+    if (detail.awardModel === ReferralProgramAwardModels.RevShareLimit) {
+      console.log(
+        `Referrer's total base revenue contribution: ${detail.referrer.totalBaseRevenueContribution}`,
+      );
+      console.log(`Referrer's standard award value: ${detail.referrer.standardAwardValue}`);
+    }
+  }
+}
+```
+
+More examples are available in [`packages/ens-referrals/src/v1/client.ts`](https://github.com/namehash/ensnode/tree/main/packages/ens-referrals/src/v1/client.ts).
+
+## Other Utilities
+
+The package also includes helpers for building referral links.
+
+```typescript
+import { buildEnsReferralUrl } from "@namehash/ens-referrals/v1";
+import type { Address } from "viem";
+
+const referrerAddress: Address = "0xd8da6bf26964af9d7eed9e03e53415d37aa96045";
 
 // Build a referrer URL to the official ENS manager app
-const referrerUrl = buildEnsReferralUrl(referrerAddress).toString(); // https://app.ens.domains/?referrer=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+const referrerUrl = buildEnsReferralUrl(referrerAddress).toString();
+// https://app.ens.domains/?referrer=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namehash/ens-referrals",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "type": "module",
   "description": "Utilities for ENS Referrals.",
   "license": "MIT",
@@ -50,7 +50,7 @@
   },
   "dependencies": {
     "zod": "^4.3.6",
-    "@ensnode/ensnode-sdk": "1.8.1"
+    "@ensnode/ensnode-sdk": "1.9.0"
   },
   "devDependencies": {
     "@types/node": "24.10.9",
@@ -58,7 +58,7 @@
     "typescript": "^5.7.3",
     "viem": "^2.22.13",
     "vitest": "^4.0.2",
-    "@ensnode/shared-configs": "1.8.1"
+    "@ensnode/shared-configs": "1.9.0"
   },
   "scripts": {
     "prepublish": "tsup",