@namehash/ens-referrals 1.6.0 → 1.7.0

package/dist/v1/index.cjs

@@ -16561,6 +16561,12 @@ var makeReferrerLeaderboardPageContextSchema = (valueLabel = "ReferrerLeaderboar
   endIndex: import_v43.default.optional(makeNonNegativeIntegerSchema(`${valueLabel}.endIndex`))
 });
 var makeReferralProgramStatusSchema = (_valueLabel = "status") => import_v43.default.enum(ReferralProgramStatuses);
+var makeBaseReferrerLeaderboardPageSchema = (valueLabel) => import_v43.default.object({
+  awardModel: import_v43.default.string(),
+  pageContext: makeReferrerLeaderboardPageContextSchema(`${valueLabel}.pageContext`),
+  status: makeReferralProgramStatusSchema(`${valueLabel}.status`),
+  accurateAsOf: makeUnixTimestampSchema(`${valueLabel}.accurateAsOf`)
+});
 
 // src/v1/award-models/shared/edition-metrics.ts
 var ReferrerEditionMetricsTypeIds = {
@@ -16703,7 +16709,7 @@ var makeReferrerEditionMetricsPieSplitSchema = (valueLabel = "ReferrerEditionMet
   makeReferrerEditionMetricsRankedPieSplitSchema(valueLabel),
   makeReferrerEditionMetricsUnrankedPieSplitSchema(valueLabel)
 ]);
-var makeReferrerLeaderboardPagePieSplitSchema = (valueLabel = "ReferrerLeaderboardPagePieSplit") => import_v44.default.object({
+var makeReferrerLeaderboardPagePieSplitSchema = (valueLabel = "ReferrerLeaderboardPagePieSplit") => makeBaseReferrerLeaderboardPageSchema(valueLabel).safeExtend({
   awardModel: import_v44.default.literal(ReferralProgramAwardModels.PieSplit),
   rules: makeReferralProgramRulesPieSplitSchema(`${valueLabel}.rules`),
   referrers: import_v44.default.array(
@@ -16711,10 +16717,7 @@ var makeReferrerLeaderboardPagePieSplitSchema = (valueLabel = "ReferrerLeaderboa
   ),
   aggregatedMetrics: makeAggregatedReferrerMetricsPieSplitSchema(
     `${valueLabel}.aggregatedMetrics`
-  ),
-  pageContext: makeReferrerLeaderboardPageContextSchema(`${valueLabel}.pageContext`),
-  status: makeReferralProgramStatusSchema(`${valueLabel}.status`),
-  accurateAsOf: makeUnixTimestampSchema(`${valueLabel}.accurateAsOf`)
+  )
 }).refine((data) => data.awardModel === data.rules.awardModel, {
   message: `${valueLabel}.awardModel must equal ${valueLabel}.rules.awardModel`,
   path: ["awardModel"]
@@ -16837,7 +16840,7 @@ var makeReferrerEditionMetricsRevShareLimitSchema = (valueLabel = "ReferrerEditi
   makeReferrerEditionMetricsRankedRevShareLimitSchema(valueLabel),
   makeReferrerEditionMetricsUnrankedRevShareLimitSchema(valueLabel)
 ]);
-var makeReferrerLeaderboardPageRevShareLimitSchema = (valueLabel = "ReferrerLeaderboardPageRevShareLimit") => import_v45.default.object({
+var makeReferrerLeaderboardPageRevShareLimitSchema = (valueLabel = "ReferrerLeaderboardPageRevShareLimit") => makeBaseReferrerLeaderboardPageSchema(valueLabel).safeExtend({
   awardModel: import_v45.default.literal(ReferralProgramAwardModels.RevShareLimit),
   rules: makeReferralProgramRulesRevShareLimitSchema(`${valueLabel}.rules`),
   referrers: import_v45.default.array(
@@ -16845,10 +16848,7 @@ var makeReferrerLeaderboardPageRevShareLimitSchema = (valueLabel = "ReferrerLead
   ),
   aggregatedMetrics: makeAggregatedReferrerMetricsRevShareLimitSchema(
     `${valueLabel}.aggregatedMetrics`
-  ),
-  pageContext: makeReferrerLeaderboardPageContextSchema(`${valueLabel}.pageContext`),
-  status: makeReferralProgramStatusSchema(`${valueLabel}.status`),
-  accurateAsOf: makeUnixTimestampSchema(`${valueLabel}.accurateAsOf`)
+  )
 }).refine((data) => data.awardModel === data.rules.awardModel, {
   message: `${valueLabel}.awardModel must equal ${valueLabel}.rules.awardModel`,
   path: ["awardModel"]
@@ -16892,10 +16892,49 @@ var makeReferralProgramRulesSchema = (valueLabel = "ReferralProgramRules") => im
   makeReferralProgramRulesPieSplitSchema(valueLabel),
   makeReferralProgramRulesRevShareLimitSchema(valueLabel)
 ]);
-var makeReferrerLeaderboardPageSchema = (valueLabel = "ReferrerLeaderboardPage") => import_v46.default.discriminatedUnion("awardModel", [
-  makeReferrerLeaderboardPagePieSplitSchema(valueLabel),
-  makeReferrerLeaderboardPageRevShareLimitSchema(valueLabel)
-]);
+var makeReferrerLeaderboardPageSchema = (valueLabel = "ReferrerLeaderboardPage") => {
+  const knownAwardModels = Object.values(ReferralProgramAwardModels).filter(
+    (m) => m !== ReferralProgramAwardModels.Unrecognized
+  );
+  const looseSchema = import_v46.default.object({ awardModel: import_v46.default.string() }).passthrough();
+  const knownSchema = import_v46.default.discriminatedUnion("awardModel", [
+    makeReferrerLeaderboardPagePieSplitSchema(valueLabel),
+    makeReferrerLeaderboardPageRevShareLimitSchema(valueLabel)
+  ]);
+  const baseSchema = makeBaseReferrerLeaderboardPageSchema(valueLabel);
+  return looseSchema.transform((data, ctx) => {
+    if (knownAwardModels.includes(data.awardModel)) {
+      const parsed2 = knownSchema.safeParse(data);
+      if (!parsed2.success) {
+        for (const issue of parsed2.error.issues) {
+          ctx.addIssue({
+            code: "custom",
+            path: issue.path,
+            message: issue.message
+          });
+        }
+        return import_v46.default.NEVER;
+      }
+      return parsed2.data;
+    }
+    const parsed = baseSchema.safeParse(data);
+    if (!parsed.success) {
+      for (const issue of parsed.error.issues) {
+        ctx.addIssue({
+          code: "custom",
+          path: issue.path,
+          message: issue.message
+        });
+      }
+      return import_v46.default.NEVER;
+    }
+    return {
+      ...parsed.data,
+      awardModel: ReferralProgramAwardModels.Unrecognized,
+      originalAwardModel: data.awardModel
+    };
+  });
+};
 var makeReferrerLeaderboardPageResponseOkSchema = (valueLabel = "ReferrerLeaderboardPageResponseOk") => import_v46.default.object({
   responseCode: import_v46.default.literal(ReferrerLeaderboardPageResponseCodes.Ok),
   data: makeReferrerLeaderboardPageSchema(`${valueLabel}.data`)
@@ -16909,10 +16948,36 @@ var makeReferrerLeaderboardPageResponseSchema = (valueLabel = "ReferrerLeaderboa
   makeReferrerLeaderboardPageResponseOkSchema(valueLabel),
   makeReferrerLeaderboardPageResponseErrorSchema(valueLabel)
 ]);
-var makeReferrerEditionMetricsSchema = (valueLabel = "ReferrerEditionMetrics") => import_v46.default.discriminatedUnion("awardModel", [
-  makeReferrerEditionMetricsPieSplitSchema(valueLabel),
-  makeReferrerEditionMetricsRevShareLimitSchema(valueLabel)
-]);
+var makeReferrerEditionMetricsSchema = (valueLabel = "ReferrerEditionMetrics") => {
+  const knownAwardModels = Object.values(ReferralProgramAwardModels).filter(
+    (m) => m !== ReferralProgramAwardModels.Unrecognized
+  );
+  const looseSchema = import_v46.default.object({ awardModel: import_v46.default.string() }).passthrough();
+  const knownSchema = import_v46.default.discriminatedUnion("awardModel", [
+    makeReferrerEditionMetricsPieSplitSchema(valueLabel),
+    makeReferrerEditionMetricsRevShareLimitSchema(valueLabel)
+  ]);
+  return looseSchema.transform((data, ctx) => {
+    if (knownAwardModels.includes(data.awardModel)) {
+      const parsed = knownSchema.safeParse(data);
+      if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+          ctx.addIssue({
+            code: "custom",
+            path: issue.path,
+            message: issue.message
+          });
+        }
+        return import_v46.default.NEVER;
+      }
+      return parsed.data;
+    }
+    return {
+      awardModel: ReferralProgramAwardModels.Unrecognized,
+      originalAwardModel: data.awardModel
+    };
+  });
+};
 var makeReferralProgramEditionSlugSchema = (valueLabel = "ReferralProgramEditionSlug") => import_v46.default.string().min(1, `${valueLabel} must not be empty`).regex(
   /^[a-z0-9]+(-[a-z0-9]+)*$/,
   `${valueLabel} must contain only lowercase letters, digits, and hyphens. Must not start or end with a hyphen.`
@@ -17150,6 +17215,18 @@ function serializeReferrerEditionMetricsUnrankedPieSplit(detail) {
     accurateAsOf: detail.accurateAsOf
   };
 }
+function serializeReferrerEditionMetricsPieSplit(detail) {
+  switch (detail.type) {
+    case ReferrerEditionMetricsTypeIds.Ranked:
+      return serializeReferrerEditionMetricsRankedPieSplit(detail);
+    case ReferrerEditionMetricsTypeIds.Unranked:
+      return serializeReferrerEditionMetricsUnrankedPieSplit(detail);
+    default: {
+      const _exhaustiveCheck = detail;
+      throw new Error(`Unknown type: ${_exhaustiveCheck.type}`);
+    }
+  }
+}
 function serializeReferrerLeaderboardPagePieSplit(page) {
   return {
     awardModel: page.awardModel,
@@ -17236,6 +17313,20 @@ function serializeReferrerEditionMetricsUnrankedRevShareLimit(detail) {
     accurateAsOf: detail.accurateAsOf
   };
 }
+function serializeReferrerEditionMetricsRevShareLimit(detail) {
+  switch (detail.type) {
+    case ReferrerEditionMetricsTypeIds.Ranked:
+      return serializeReferrerEditionMetricsRankedRevShareLimit(detail);
+    case ReferrerEditionMetricsTypeIds.Unranked:
+      return serializeReferrerEditionMetricsUnrankedRevShareLimit(detail);
+    default: {
+      const _exhaustiveCheck = detail;
+      throw new Error(
+        `Unknown type: ${_exhaustiveCheck.type}`
+      );
+    }
+  }
+}
 function serializeReferrerLeaderboardPageRevShareLimit(page) {
   return {
     awardModel: page.awardModel,
@@ -17275,6 +17366,12 @@ function serializeReferrerLeaderboardPage(page) {
       return serializeReferrerLeaderboardPagePieSplit(page);
     case ReferralProgramAwardModels.RevShareLimit:
       return serializeReferrerLeaderboardPageRevShareLimit(page);
+    case ReferralProgramAwardModels.Unrecognized: {
+      const unrecognized = page;
+      throw new Error(
+        `ReferrerLeaderboardPageUnrecognized (originalAwardModel: '${unrecognized.originalAwardModel}') must not be serialized \u2014 it is a client-side forward-compatibility placeholder only.`
+      );
+    }
     default: {
       const _exhaustiveCheck = page;
       throw new Error(
@@ -17283,26 +17380,18 @@ function serializeReferrerLeaderboardPage(page) {
     }
   }
 }
-function serializeReferrerEditionMetricsRanked(detail) {
+function serializeReferrerEditionMetrics(detail) {
   switch (detail.awardModel) {
     case ReferralProgramAwardModels.PieSplit:
-      return serializeReferrerEditionMetricsRankedPieSplit(detail);
+      return serializeReferrerEditionMetricsPieSplit(detail);
     case ReferralProgramAwardModels.RevShareLimit:
-      return serializeReferrerEditionMetricsRankedRevShareLimit(detail);
-    default: {
-      const _exhaustiveCheck = detail;
+      return serializeReferrerEditionMetricsRevShareLimit(detail);
+    case ReferralProgramAwardModels.Unrecognized: {
+      const unrecognized = detail;
       throw new Error(
-        `Unknown award model: ${_exhaustiveCheck.awardModel}`
+        `ReferrerEditionMetricsUnrecognized (originalAwardModel: '${unrecognized.originalAwardModel}') must not be serialized \u2014 it is a client-side forward-compatibility placeholder only.`
       );
     }
-  }
-}
-function serializeReferrerEditionMetricsUnranked(detail) {
-  switch (detail.awardModel) {
-    case ReferralProgramAwardModels.PieSplit:
-      return serializeReferrerEditionMetricsUnrankedPieSplit(detail);
-    case ReferralProgramAwardModels.RevShareLimit:
-      return serializeReferrerEditionMetricsUnrankedRevShareLimit(detail);
     default: {
       const _exhaustiveCheck = detail;
       throw new Error(
@@ -17311,18 +17400,6 @@ function serializeReferrerEditionMetricsUnranked(detail) {
     }
   }
 }
-function serializeReferrerEditionMetrics(detail) {
-  switch (detail.type) {
-    case "ranked":
-      return serializeReferrerEditionMetricsRanked(detail);
-    case "unranked":
-      return serializeReferrerEditionMetricsUnranked(detail);
-    default: {
-      const _exhaustiveCheck = detail;
-      throw new Error(`Unknown detail type: ${_exhaustiveCheck.type}`);
-    }
-  }
-}
 function serializeReferralProgramEditionConfig(editionConfig) {
   return {
     slug: editionConfig.slug,
@@ -18222,12 +18299,13 @@ var ENSReferralsClient = class _ENSReferralsClient {
    * @param request.recordsPerPage - Number of records per page (default: 25, max: 100)
    * @returns {ReferrerLeaderboardPageResponse}
    *
+   * @remarks If the server returns a leaderboard page whose `awardModel` is not recognized by
+   * this client version, it is preserved as {@link ReferrerLeaderboardPageUnrecognized}. Callers
+   * should check `response.data.awardModel` and handle the `"unrecognized"` case accordingly.
+   *
    * @throws if the ENSNode request fails
    * @throws if the ENSNode API returns an error response
    * @throws if the ENSNode response breaks required invariants
-   * @throws if the requested edition uses an award model not recognized by this version of
-   *   the client. Call {@link getEditionConfigSet} first to verify the edition's `awardModel`
-   *   is supported before requesting its leaderboard.
    *
    * @example
    * ```typescript
@@ -18235,17 +18313,16 @@ var ENSReferralsClient = class _ENSReferralsClient {
    * const editionSlug = "2025-12";
    * const response = await client.getReferrerLeaderboardPage({ edition: editionSlug });
    * if (response.responseCode === ReferrerLeaderboardPageResponseCodes.Ok) {
-   *   const {
-   *     aggregatedMetrics,
-   *     referrers,
-   *     rules,
-   *     pageContext,
-   *     accurateAsOf
-   *   } = response.data;
-   *   console.log(`Edition: ${editionSlug}`);
-   *   console.log(`Subregistry: ${rules.subregistryId}`);
-   *   console.log(`Total Referrers: ${pageContext.totalRecords}`);
-   *   console.log(`Page ${pageContext.page} of ${pageContext.totalPages}`);
+   *   const { awardModel, pageContext, accurateAsOf } = response.data;
+   *   if (awardModel === ReferralProgramAwardModels.Unrecognized) {
+   *     console.log(`Unrecognized award model: ${response.data.originalAwardModel} — skipping`);
+   *   } else {
+   *     const { aggregatedMetrics, referrers, rules } = response.data;
+   *     console.log(`Edition: ${editionSlug}`);
+   *     console.log(`Subregistry: ${rules.subregistryId}`);
+   *     console.log(`Total Referrers: ${pageContext.totalRecords}`);
+   *     console.log(`Page ${pageContext.page} of ${pageContext.totalPages}`);
+   *   }
    * }
    * ```
    *
@@ -18294,22 +18371,17 @@ var ENSReferralsClient = class _ENSReferralsClient {
    * referral program editions. Returns a record mapping each requested edition slug
    * to the referrer's metrics for that edition.
    *
-   * The response data maps edition slugs to referrer metrics. Each edition's data is a
-   * discriminated union type with a `type` field:
-   *
-   * **For referrers on the leaderboard** (`ReferrerEditionMetricsRanked`):
-   * - `type`: {@link ReferrerEditionMetricsTypeIds.Ranked}
-   * - `referrer`: The `AwardedReferrerMetrics` with rank, qualification status, and award share
-   * - `rules`: The referral program rules for this edition
-   * - `aggregatedMetrics`: Aggregated metrics for all referrers on the leaderboard
-   * - `accurateAsOf`: Unix timestamp indicating when the data was last updated
+   * The response data maps edition slugs to referrer metrics. Each edition's entry is a
+   * {@link ReferrerEditionMetrics} discriminated union. Narrow on `awardModel` first to
+   * exclude unrecognized models, then on `type` to distinguish ranked from unranked:
    *
-   * **For referrers NOT on the leaderboard** (`ReferrerEditionMetricsUnranked`):
-   * - `type`: {@link ReferrerEditionMetricsTypeIds.Unranked}
-   * - `referrer`: The `UnrankedReferrerMetrics` from @namehash/ens-referrals
-   * - `rules`: The referral program rules for this edition
-   * - `aggregatedMetrics`: Aggregated metrics for all referrers on the leaderboard
-   * - `accurateAsOf`: Unix timestamp indicating when the data was last updated
+   * - `awardModel: "unrecognized"` ({@link ReferrerEditionMetricsUnrecognized}): the server
+   *   returned an award model this client does not recognize. Only `originalAwardModel` is
+   *   available; no model-specific fields are present.
+   * - `type: "ranked"` ({@link ReferrerEditionMetricsTypeIds.Ranked}): the referrer appears on
+   *   the leaderboard. `referrer` contains rank, qualification status, and award share.
+   * - `type: "unranked"` ({@link ReferrerEditionMetricsTypeIds.Unranked}): the referrer has no
+   *   activity in this edition. `referrer` contains zero-value placeholders.
    *
    * **Note:** This endpoint does not allow partial success. When `responseCode === Ok`,
    * all requested editions are guaranteed to be present in the response data. If any
@@ -18320,11 +18392,13 @@ var ENSReferralsClient = class _ENSReferralsClient {
    * @param request The referrer address and edition slugs to query
    * @returns {ReferrerMetricsEditionsResponse} Returns the referrer metrics for requested editions
    *
+   * @remarks If the server returns metrics for an edition whose `awardModel` is not recognized by
+   * this client version, that edition's entry in `response.data` is preserved as
+   * {@link ReferrerEditionMetricsUnrecognized}. Callers should check each edition's `awardModel`
+   * and handle the `"unrecognized"` case accordingly.
+   *
    * @throws if the ENSNode request fails
    * @throws if the response data is malformed
-   * @throws if any of the requested editions use an award model not recognized by this
-   *   version of the client. Call {@link getEditionConfigSet} first to verify each
-   *   edition's `awardModel` is supported before requesting metrics.
    *
    * @example
    * ```typescript
@@ -18337,6 +18411,10 @@ var ENSReferralsClient = class _ENSReferralsClient {
    *   // All requested editions are present in response.data
    *   for (const [editionSlug, detail] of Object.entries(response.data)) {
    *     console.log(`Edition: ${editionSlug}`);
+   *     if (detail.awardModel === ReferralProgramAwardModels.Unrecognized) {
+   *       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}`);
@@ -18354,12 +18432,12 @@ var ENSReferralsClient = class _ENSReferralsClient {
    *   editions: ["2025-12"]
    * });
    * if (response.responseCode === ReferrerMetricsEditionsResponseCodes.Ok) {
-   *   const edition202512Detail = response.data["2025-12"];
-   *   if (edition202512Detail && edition202512Detail.type === ReferrerEditionMetricsTypeIds.Ranked) {
-   *     // TypeScript knows this is ReferrerEditionMetricsRanked
-   *     console.log(`Edition 2025-12 Rank: ${edition202512Detail.referrer.rank}`);
-   *   } else if (edition202512Detail) {
-   *     // TypeScript knows this is ReferrerEditionMetricsUnranked
+   *   const detail = response.data["2025-12"];
+   *   if (detail && detail.awardModel === ReferralProgramAwardModels.Unrecognized) {
+   *     console.log(`Unrecognized award model: ${detail.originalAwardModel} — skipping`);
+   *   } else if (detail && detail.type === ReferrerEditionMetricsTypeIds.Ranked) {
+   *     console.log(`Edition 2025-12 Rank: ${detail.referrer.rank}`);
+   *   } else if (detail) {
    *     console.log("Referrer is not on the leaderboard for 2025-12");
    *   }
    * }
@@ -18529,6 +18607,12 @@ var getReferrerEditionMetrics = (referrer, leaderboard) => {
         accurateAsOf: leaderboard.accurateAsOf
       };
     }
+    default: {
+      const _exhaustiveCheck = leaderboard;
+      throw new Error(
+        `Unknown award model: ${_exhaustiveCheck.awardModel}`
+      );
+    }
   }
 };
 
@@ -18540,6 +18624,12 @@ var getReferrerLeaderboardPage = (pageParams, leaderboard) => {
       return buildLeaderboardPagePieSplit(pageContext, leaderboard);
     case ReferralProgramAwardModels.RevShareLimit:
       return buildLeaderboardPageRevShareLimit(pageContext, leaderboard);
+    default: {
+      const _exhaustiveCheck = leaderboard;
+      throw new Error(
+        `Unknown award model: ${_exhaustiveCheck.awardModel}`
+      );
+    }
   }
 };