@namehash/ens-referrals 1.1.0 → 1.2.0

package/dist/index.d.cts

@@ -279,6 +279,31 @@ interface AwardedReferrerMetrics extends RankedReferrerMetrics {
 }
 declare const validateAwardedReferrerMetrics: (referrer: AwardedReferrerMetrics, rules: ReferralProgramRules) => void;
 declare const buildAwardedReferrerMetrics: (referrer: RankedReferrerMetrics, aggregatedMetrics: AggregatedReferrerMetrics, rules: ReferralProgramRules) => AwardedReferrerMetrics;
+/**
+ * Extends {@link AwardedReferrerMetrics} but with rank set to null to represent
+ * a referrer who is not on the leaderboard (has zero referrals within the rules associated with the leaderboard).
+ */
+interface UnrankedReferrerMetrics extends Omit<AwardedReferrerMetrics, "rank" | "isQualified"> {
+    /**
+     * The referrer is not on the leaderboard and therefore has no rank.
+     */
+    rank: null;
+    /**
+     * Always false for unranked referrers.
+     */
+    isQualified: false;
+}
+declare const validateUnrankedReferrerMetrics: (metrics: UnrankedReferrerMetrics) => void;
+/**
+ * Build an unranked zero-score referrer record for a referrer address that is not in the leaderboard.
+ *
+ * This is useful when you want to return a referrer record for an address that has no referrals
+ * and is not qualified for the leaderboard.
+ *
+ * @param referrer - The referrer address
+ * @returns An {@link UnrankedReferrerMetrics} with zero values for all metrics and null rank
+ */
+declare const buildUnrankedReferrerMetrics: (referrer: Address) => UnrankedReferrerMetrics;
 
 /**
  * Represents aggregated metrics for a list of `RankedReferrerMetrics`.
@@ -404,7 +429,7 @@ declare const REFERRERS_PER_LEADERBOARD_PAGE_MAX = 100;
 /**
  * Pagination params for leaderboard queries.
  */
-interface ReferrerLeaderboardPaginationParams {
+interface ReferrerLeaderboardPageParams {
     /**
      * Requested referrer leaderboard page number (1-indexed)
      * @invariant Must be a positive integer (>= 1)
@@ -418,8 +443,8 @@ interface ReferrerLeaderboardPaginationParams {
      */
     itemsPerPage?: number;
 }
-declare const buildReferrerLeaderboardPaginationParams: (params: ReferrerLeaderboardPaginationParams) => Required<ReferrerLeaderboardPaginationParams>;
-interface ReferrerLeaderboardPaginationContext extends Required<ReferrerLeaderboardPaginationParams> {
+declare const buildReferrerLeaderboardPageParams: (params: ReferrerLeaderboardPageParams) => Required<ReferrerLeaderboardPageParams>;
+interface ReferrerLeaderboardPageContext extends Required<ReferrerLeaderboardPageParams> {
     /**
      * Total number of referrers across all leaderboard pages
      * @invariant Guaranteed to be a non-negative integer (>= 0)
@@ -460,8 +485,8 @@ interface ReferrerLeaderboardPaginationContext extends Required<ReferrerLeaderbo
      */
     endIndex?: number;
 }
-declare const validateReferrerLeaderboardPaginationContext: (context: ReferrerLeaderboardPaginationContext) => void;
-declare const buildReferrerLeaderboardPaginationContext: (optionalParams: ReferrerLeaderboardPaginationParams, leaderboard: ReferrerLeaderboard) => ReferrerLeaderboardPaginationContext;
+declare const validateReferrerLeaderboardPageContext: (context: ReferrerLeaderboardPageContext) => void;
+declare const buildReferrerLeaderboardPageContext: (optionalParams: ReferrerLeaderboardPageParams, leaderboard: ReferrerLeaderboard) => ReferrerLeaderboardPageContext;
 /**
  * A page of referrers from the referrer leaderboard.
  */
@@ -484,16 +509,16 @@ interface ReferrerLeaderboardPage {
      */
     aggregatedMetrics: AggregatedReferrerMetrics;
     /**
-     * The {@link ReferrerLeaderboardPaginationContext} of this {@link ReferrerLeaderboardPage} relative to the overall
+     * The {@link ReferrerLeaderboardPageContext} of this {@link ReferrerLeaderboardPage} relative to the overall
      * {@link ReferrerLeaderboard}.
      */
-    paginationContext: ReferrerLeaderboardPaginationContext;
+    paginationContext: ReferrerLeaderboardPageContext;
     /**
      * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerLeaderboardPage} was accurate as of.
      */
     accurateAsOf: UnixTimestamp;
 }
-declare const getReferrerLeaderboardPage: (paginationParams: ReferrerLeaderboardPaginationParams, leaderboard: ReferrerLeaderboard) => ReferrerLeaderboardPage;
+declare const getReferrerLeaderboardPage: (paginationParams: ReferrerLeaderboardPageParams, leaderboard: ReferrerLeaderboard) => ReferrerLeaderboardPage;
 
 /**
  * Build a URL to the official ENS manager app
@@ -507,4 +532,109 @@ declare const isPositiveInteger: (value: number) => boolean;
 declare const validateNonNegativeInteger: (value: number) => void;
 declare const isFiniteNonNegativeNumber: (value: number) => boolean;
 
-export { type AccountId, type AggregatedReferrerMetrics, type AwardedReferrerMetrics, type ChainId, type Duration, ENCODED_REFERRER_BYTE_LENGTH, ENCODED_REFERRER_BYTE_OFFSET, ENS_HOLIDAY_AWARDS_END_DATE, ENS_HOLIDAY_AWARDS_MAX_QUALIFIED_REFERRERS, ENS_HOLIDAY_AWARDS_START_DATE, ENS_HOLIDAY_AWARDS_TOTAL_AWARD_POOL_VALUE, EXPECTED_ENCODED_REFERRER_PADDING, type EncodedReferrer, REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT, REFERRERS_PER_LEADERBOARD_PAGE_MAX, type RankedReferrerMetrics, type ReferralProgramRules, type ReferrerLeaderboard, type ReferrerLeaderboardPage, type ReferrerLeaderboardPaginationContext, type ReferrerLeaderboardPaginationParams, type ReferrerMetrics, type ReferrerMetricsForComparison, type ReferrerRank, type ReferrerScore, SECONDS_PER_YEAR, type ScoredReferrerMetrics, type USDQuantity, type UnixTimestamp, ZERO_ENCODED_REFERRER, buildAggregatedReferrerMetrics, buildAwardedReferrerMetrics, buildEncodedReferrer, buildEnsReferralUrl, buildRankedReferrerMetrics, buildReferralProgramRules, buildReferrerLeaderboard, buildReferrerLeaderboardPaginationContext, buildReferrerLeaderboardPaginationParams, buildReferrerMetrics, buildScoredReferrerMetrics, calcReferrerAwardPoolShare, calcReferrerFinalScore, calcReferrerFinalScoreBoost, calcReferrerFinalScoreMultiplier, calcReferrerScore, compareReferrerMetrics, decodeEncodedReferrer, getReferrerLeaderboardPage, isFiniteNonNegativeNumber, isInteger, isNonNegativeInteger, isPositiveInteger, isReferrerQualified, isValidDuration, isValidReferrerScore, isValidUSDQuantity, normalizeAddress, sortReferrerMetrics, validateAggregatedReferrerMetrics, validateAwardedReferrerMetrics, validateDuration, validateLowercaseAddress, validateNonNegativeInteger, validateRankedReferrerMetrics, validateReferralProgramRules, validateReferrerLeaderboardPaginationContext, validateReferrerMetrics, validateReferrerRank, validateReferrerScore, validateScoredReferrerMetrics, validateUSDQuantity, validateUnixTimestamp };
+/**
+ * The type of referrer detail data.
+ */
+declare const ReferrerDetailTypeIds: {
+    /**
+     * Represents a referrer who is ranked on the leaderboard.
+     */
+    readonly Ranked: "ranked";
+    /**
+     * Represents a referrer who is not ranked on the leaderboard.
+     */
+    readonly Unranked: "unranked";
+};
+/**
+ * The derived string union of possible {@link ReferrerDetailTypeIds}.
+ */
+type ReferrerDetailTypeId = (typeof ReferrerDetailTypeIds)[keyof typeof ReferrerDetailTypeIds];
+/**
+ * Referrer detail data for a specific referrer address on the leaderboard.
+ *
+ * Includes the referrer's awarded metrics from the leaderboard plus timestamp.
+ *
+ * Invariants:
+ * - `type` is always {@link ReferrerDetailTypeIds.Ranked}.
+ *
+ * @see {@link AwardedReferrerMetrics}
+ */
+interface ReferrerDetailRanked {
+    /**
+     * The type of referrer detail data.
+     */
+    type: typeof ReferrerDetailTypeIds.Ranked;
+    /**
+     * The {@link ReferralProgramRules} used to calculate the {@link AwardedReferrerMetrics}.
+     */
+    rules: ReferralProgramRules;
+    /**
+     * The awarded referrer metrics from the leaderboard.
+     *
+     * Contains all calculated metrics including score, rank, qualification status,
+     * and award pool share information.
+     */
+    referrer: AwardedReferrerMetrics;
+    /**
+     * Aggregated metrics for all referrers on the leaderboard.
+     */
+    aggregatedMetrics: AggregatedReferrerMetrics;
+    /**
+     * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerDetailData} was accurate as of.
+     */
+    accurateAsOf: UnixTimestamp;
+}
+/**
+ * Referrer detail data for a specific referrer address NOT on the leaderboard.
+ *
+ * Includes the referrer's unranked metrics (with null rank and isQualified: false) plus timestamp.
+ *
+ * Invariants:
+ * - `type` is always {@link ReferrerDetailTypeIds.Unranked}.
+ *
+ * @see {@link UnrankedReferrerMetrics}
+ */
+interface ReferrerDetailUnranked {
+    /**
+     * The type of referrer detail data.
+     */
+    type: typeof ReferrerDetailTypeIds.Unranked;
+    /**
+     * The {@link ReferralProgramRules} used to calculate the {@link UnrankedReferrerMetrics}.
+     */
+    rules: ReferralProgramRules;
+    /**
+     * The unranked referrer metrics (not on the leaderboard).
+     *
+     * Contains all calculated metrics with rank set to null and isQualified set to false.
+     */
+    referrer: UnrankedReferrerMetrics;
+    /**
+     * Aggregated metrics for all referrers on the leaderboard.
+     */
+    aggregatedMetrics: AggregatedReferrerMetrics;
+    /**
+     * The {@link UnixTimestamp} of when the data used to build the {@link UnrankedReferrerDetailData} was accurate as of.
+     */
+    accurateAsOf: UnixTimestamp;
+}
+/**
+ * Referrer detail data for a specific referrer address.
+ *
+ * Use the `type` field to determine the specific type interpretation
+ * at runtime.
+ */
+type ReferrerDetail = ReferrerDetailRanked | ReferrerDetailUnranked;
+/**
+ * Get the detail for a specific referrer from the leaderboard.
+ *
+ * Returns a {@link ReferrerDetailRanked} if the referrer is on the leaderboard,
+ * or a {@link ReferrerDetailUnranked} if the referrer has no referrals.
+ *
+ * @param referrer - The referrer address to look up
+ * @param leaderboard - The referrer leaderboard to query
+ * @returns The appropriate {@link ReferrerDetail} (ranked or unranked)
+ */
+declare const getReferrerDetail: (referrer: Address, leaderboard: ReferrerLeaderboard) => ReferrerDetail;
+
+export { type AccountId, type AggregatedReferrerMetrics, type AwardedReferrerMetrics, type ChainId, type Duration, ENCODED_REFERRER_BYTE_LENGTH, ENCODED_REFERRER_BYTE_OFFSET, ENS_HOLIDAY_AWARDS_END_DATE, ENS_HOLIDAY_AWARDS_MAX_QUALIFIED_REFERRERS, ENS_HOLIDAY_AWARDS_START_DATE, ENS_HOLIDAY_AWARDS_TOTAL_AWARD_POOL_VALUE, EXPECTED_ENCODED_REFERRER_PADDING, type EncodedReferrer, REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT, REFERRERS_PER_LEADERBOARD_PAGE_MAX, type RankedReferrerMetrics, type ReferralProgramRules, type ReferrerDetail, type ReferrerDetailRanked, type ReferrerDetailTypeId, ReferrerDetailTypeIds, type ReferrerDetailUnranked, type ReferrerLeaderboard, type ReferrerLeaderboardPage, type ReferrerLeaderboardPageContext, type ReferrerLeaderboardPageParams, type ReferrerMetrics, type ReferrerMetricsForComparison, type ReferrerRank, type ReferrerScore, SECONDS_PER_YEAR, type ScoredReferrerMetrics, type USDQuantity, type UnixTimestamp, type UnrankedReferrerMetrics, ZERO_ENCODED_REFERRER, buildAggregatedReferrerMetrics, buildAwardedReferrerMetrics, buildEncodedReferrer, buildEnsReferralUrl, buildRankedReferrerMetrics, buildReferralProgramRules, buildReferrerLeaderboard, buildReferrerLeaderboardPageContext, buildReferrerLeaderboardPageParams, buildReferrerMetrics, buildScoredReferrerMetrics, buildUnrankedReferrerMetrics, calcReferrerAwardPoolShare, calcReferrerFinalScore, calcReferrerFinalScoreBoost, calcReferrerFinalScoreMultiplier, calcReferrerScore, compareReferrerMetrics, decodeEncodedReferrer, getReferrerDetail, getReferrerLeaderboardPage, isFiniteNonNegativeNumber, isInteger, isNonNegativeInteger, isPositiveInteger, isReferrerQualified, isValidDuration, isValidReferrerScore, isValidUSDQuantity, normalizeAddress, sortReferrerMetrics, validateAggregatedReferrerMetrics, validateAwardedReferrerMetrics, validateDuration, validateLowercaseAddress, validateNonNegativeInteger, validateRankedReferrerMetrics, validateReferralProgramRules, validateReferrerLeaderboardPageContext, validateReferrerMetrics, validateReferrerRank, validateReferrerScore, validateScoredReferrerMetrics, validateUSDQuantity, validateUnixTimestamp, validateUnrankedReferrerMetrics };

package/dist/index.d.ts

@@ -279,6 +279,31 @@ interface AwardedReferrerMetrics extends RankedReferrerMetrics {
 }
 declare const validateAwardedReferrerMetrics: (referrer: AwardedReferrerMetrics, rules: ReferralProgramRules) => void;
 declare const buildAwardedReferrerMetrics: (referrer: RankedReferrerMetrics, aggregatedMetrics: AggregatedReferrerMetrics, rules: ReferralProgramRules) => AwardedReferrerMetrics;
+/**
+ * Extends {@link AwardedReferrerMetrics} but with rank set to null to represent
+ * a referrer who is not on the leaderboard (has zero referrals within the rules associated with the leaderboard).
+ */
+interface UnrankedReferrerMetrics extends Omit<AwardedReferrerMetrics, "rank" | "isQualified"> {
+    /**
+     * The referrer is not on the leaderboard and therefore has no rank.
+     */
+    rank: null;
+    /**
+     * Always false for unranked referrers.
+     */
+    isQualified: false;
+}
+declare const validateUnrankedReferrerMetrics: (metrics: UnrankedReferrerMetrics) => void;
+/**
+ * Build an unranked zero-score referrer record for a referrer address that is not in the leaderboard.
+ *
+ * This is useful when you want to return a referrer record for an address that has no referrals
+ * and is not qualified for the leaderboard.
+ *
+ * @param referrer - The referrer address
+ * @returns An {@link UnrankedReferrerMetrics} with zero values for all metrics and null rank
+ */
+declare const buildUnrankedReferrerMetrics: (referrer: Address) => UnrankedReferrerMetrics;
 
 /**
  * Represents aggregated metrics for a list of `RankedReferrerMetrics`.
@@ -404,7 +429,7 @@ declare const REFERRERS_PER_LEADERBOARD_PAGE_MAX = 100;
 /**
  * Pagination params for leaderboard queries.
  */
-interface ReferrerLeaderboardPaginationParams {
+interface ReferrerLeaderboardPageParams {
     /**
      * Requested referrer leaderboard page number (1-indexed)
      * @invariant Must be a positive integer (>= 1)
@@ -418,8 +443,8 @@ interface ReferrerLeaderboardPaginationParams {
      */
     itemsPerPage?: number;
 }
-declare const buildReferrerLeaderboardPaginationParams: (params: ReferrerLeaderboardPaginationParams) => Required<ReferrerLeaderboardPaginationParams>;
-interface ReferrerLeaderboardPaginationContext extends Required<ReferrerLeaderboardPaginationParams> {
+declare const buildReferrerLeaderboardPageParams: (params: ReferrerLeaderboardPageParams) => Required<ReferrerLeaderboardPageParams>;
+interface ReferrerLeaderboardPageContext extends Required<ReferrerLeaderboardPageParams> {
     /**
      * Total number of referrers across all leaderboard pages
      * @invariant Guaranteed to be a non-negative integer (>= 0)
@@ -460,8 +485,8 @@ interface ReferrerLeaderboardPaginationContext extends Required<ReferrerLeaderbo
      */
     endIndex?: number;
 }
-declare const validateReferrerLeaderboardPaginationContext: (context: ReferrerLeaderboardPaginationContext) => void;
-declare const buildReferrerLeaderboardPaginationContext: (optionalParams: ReferrerLeaderboardPaginationParams, leaderboard: ReferrerLeaderboard) => ReferrerLeaderboardPaginationContext;
+declare const validateReferrerLeaderboardPageContext: (context: ReferrerLeaderboardPageContext) => void;
+declare const buildReferrerLeaderboardPageContext: (optionalParams: ReferrerLeaderboardPageParams, leaderboard: ReferrerLeaderboard) => ReferrerLeaderboardPageContext;
 /**
  * A page of referrers from the referrer leaderboard.
  */
@@ -484,16 +509,16 @@ interface ReferrerLeaderboardPage {
      */
     aggregatedMetrics: AggregatedReferrerMetrics;
     /**
-     * The {@link ReferrerLeaderboardPaginationContext} of this {@link ReferrerLeaderboardPage} relative to the overall
+     * The {@link ReferrerLeaderboardPageContext} of this {@link ReferrerLeaderboardPage} relative to the overall
      * {@link ReferrerLeaderboard}.
      */
-    paginationContext: ReferrerLeaderboardPaginationContext;
+    paginationContext: ReferrerLeaderboardPageContext;
     /**
      * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerLeaderboardPage} was accurate as of.
      */
     accurateAsOf: UnixTimestamp;
 }
-declare const getReferrerLeaderboardPage: (paginationParams: ReferrerLeaderboardPaginationParams, leaderboard: ReferrerLeaderboard) => ReferrerLeaderboardPage;
+declare const getReferrerLeaderboardPage: (paginationParams: ReferrerLeaderboardPageParams, leaderboard: ReferrerLeaderboard) => ReferrerLeaderboardPage;
 
 /**
  * Build a URL to the official ENS manager app
@@ -507,4 +532,109 @@ declare const isPositiveInteger: (value: number) => boolean;
 declare const validateNonNegativeInteger: (value: number) => void;
 declare const isFiniteNonNegativeNumber: (value: number) => boolean;
 
-export { type AccountId, type AggregatedReferrerMetrics, type AwardedReferrerMetrics, type ChainId, type Duration, ENCODED_REFERRER_BYTE_LENGTH, ENCODED_REFERRER_BYTE_OFFSET, ENS_HOLIDAY_AWARDS_END_DATE, ENS_HOLIDAY_AWARDS_MAX_QUALIFIED_REFERRERS, ENS_HOLIDAY_AWARDS_START_DATE, ENS_HOLIDAY_AWARDS_TOTAL_AWARD_POOL_VALUE, EXPECTED_ENCODED_REFERRER_PADDING, type EncodedReferrer, REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT, REFERRERS_PER_LEADERBOARD_PAGE_MAX, type RankedReferrerMetrics, type ReferralProgramRules, type ReferrerLeaderboard, type ReferrerLeaderboardPage, type ReferrerLeaderboardPaginationContext, type ReferrerLeaderboardPaginationParams, type ReferrerMetrics, type ReferrerMetricsForComparison, type ReferrerRank, type ReferrerScore, SECONDS_PER_YEAR, type ScoredReferrerMetrics, type USDQuantity, type UnixTimestamp, ZERO_ENCODED_REFERRER, buildAggregatedReferrerMetrics, buildAwardedReferrerMetrics, buildEncodedReferrer, buildEnsReferralUrl, buildRankedReferrerMetrics, buildReferralProgramRules, buildReferrerLeaderboard, buildReferrerLeaderboardPaginationContext, buildReferrerLeaderboardPaginationParams, buildReferrerMetrics, buildScoredReferrerMetrics, calcReferrerAwardPoolShare, calcReferrerFinalScore, calcReferrerFinalScoreBoost, calcReferrerFinalScoreMultiplier, calcReferrerScore, compareReferrerMetrics, decodeEncodedReferrer, getReferrerLeaderboardPage, isFiniteNonNegativeNumber, isInteger, isNonNegativeInteger, isPositiveInteger, isReferrerQualified, isValidDuration, isValidReferrerScore, isValidUSDQuantity, normalizeAddress, sortReferrerMetrics, validateAggregatedReferrerMetrics, validateAwardedReferrerMetrics, validateDuration, validateLowercaseAddress, validateNonNegativeInteger, validateRankedReferrerMetrics, validateReferralProgramRules, validateReferrerLeaderboardPaginationContext, validateReferrerMetrics, validateReferrerRank, validateReferrerScore, validateScoredReferrerMetrics, validateUSDQuantity, validateUnixTimestamp };
+/**
+ * The type of referrer detail data.
+ */
+declare const ReferrerDetailTypeIds: {
+    /**
+     * Represents a referrer who is ranked on the leaderboard.
+     */
+    readonly Ranked: "ranked";
+    /**
+     * Represents a referrer who is not ranked on the leaderboard.
+     */
+    readonly Unranked: "unranked";
+};
+/**
+ * The derived string union of possible {@link ReferrerDetailTypeIds}.
+ */
+type ReferrerDetailTypeId = (typeof ReferrerDetailTypeIds)[keyof typeof ReferrerDetailTypeIds];
+/**
+ * Referrer detail data for a specific referrer address on the leaderboard.
+ *
+ * Includes the referrer's awarded metrics from the leaderboard plus timestamp.
+ *
+ * Invariants:
+ * - `type` is always {@link ReferrerDetailTypeIds.Ranked}.
+ *
+ * @see {@link AwardedReferrerMetrics}
+ */
+interface ReferrerDetailRanked {
+    /**
+     * The type of referrer detail data.
+     */
+    type: typeof ReferrerDetailTypeIds.Ranked;
+    /**
+     * The {@link ReferralProgramRules} used to calculate the {@link AwardedReferrerMetrics}.
+     */
+    rules: ReferralProgramRules;
+    /**
+     * The awarded referrer metrics from the leaderboard.
+     *
+     * Contains all calculated metrics including score, rank, qualification status,
+     * and award pool share information.
+     */
+    referrer: AwardedReferrerMetrics;
+    /**
+     * Aggregated metrics for all referrers on the leaderboard.
+     */
+    aggregatedMetrics: AggregatedReferrerMetrics;
+    /**
+     * The {@link UnixTimestamp} of when the data used to build the {@link ReferrerDetailData} was accurate as of.
+     */
+    accurateAsOf: UnixTimestamp;
+}
+/**
+ * Referrer detail data for a specific referrer address NOT on the leaderboard.
+ *
+ * Includes the referrer's unranked metrics (with null rank and isQualified: false) plus timestamp.
+ *
+ * Invariants:
+ * - `type` is always {@link ReferrerDetailTypeIds.Unranked}.
+ *
+ * @see {@link UnrankedReferrerMetrics}
+ */
+interface ReferrerDetailUnranked {
+    /**
+     * The type of referrer detail data.
+     */
+    type: typeof ReferrerDetailTypeIds.Unranked;
+    /**
+     * The {@link ReferralProgramRules} used to calculate the {@link UnrankedReferrerMetrics}.
+     */
+    rules: ReferralProgramRules;
+    /**
+     * The unranked referrer metrics (not on the leaderboard).
+     *
+     * Contains all calculated metrics with rank set to null and isQualified set to false.
+     */
+    referrer: UnrankedReferrerMetrics;
+    /**
+     * Aggregated metrics for all referrers on the leaderboard.
+     */
+    aggregatedMetrics: AggregatedReferrerMetrics;
+    /**
+     * The {@link UnixTimestamp} of when the data used to build the {@link UnrankedReferrerDetailData} was accurate as of.
+     */
+    accurateAsOf: UnixTimestamp;
+}
+/**
+ * Referrer detail data for a specific referrer address.
+ *
+ * Use the `type` field to determine the specific type interpretation
+ * at runtime.
+ */
+type ReferrerDetail = ReferrerDetailRanked | ReferrerDetailUnranked;
+/**
+ * Get the detail for a specific referrer from the leaderboard.
+ *
+ * Returns a {@link ReferrerDetailRanked} if the referrer is on the leaderboard,
+ * or a {@link ReferrerDetailUnranked} if the referrer has no referrals.
+ *
+ * @param referrer - The referrer address to look up
+ * @param leaderboard - The referrer leaderboard to query
+ * @returns The appropriate {@link ReferrerDetail} (ranked or unranked)
+ */
+declare const getReferrerDetail: (referrer: Address, leaderboard: ReferrerLeaderboard) => ReferrerDetail;
+
+export { type AccountId, type AggregatedReferrerMetrics, type AwardedReferrerMetrics, type ChainId, type Duration, ENCODED_REFERRER_BYTE_LENGTH, ENCODED_REFERRER_BYTE_OFFSET, ENS_HOLIDAY_AWARDS_END_DATE, ENS_HOLIDAY_AWARDS_MAX_QUALIFIED_REFERRERS, ENS_HOLIDAY_AWARDS_START_DATE, ENS_HOLIDAY_AWARDS_TOTAL_AWARD_POOL_VALUE, EXPECTED_ENCODED_REFERRER_PADDING, type EncodedReferrer, REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT, REFERRERS_PER_LEADERBOARD_PAGE_MAX, type RankedReferrerMetrics, type ReferralProgramRules, type ReferrerDetail, type ReferrerDetailRanked, type ReferrerDetailTypeId, ReferrerDetailTypeIds, type ReferrerDetailUnranked, type ReferrerLeaderboard, type ReferrerLeaderboardPage, type ReferrerLeaderboardPageContext, type ReferrerLeaderboardPageParams, type ReferrerMetrics, type ReferrerMetricsForComparison, type ReferrerRank, type ReferrerScore, SECONDS_PER_YEAR, type ScoredReferrerMetrics, type USDQuantity, type UnixTimestamp, type UnrankedReferrerMetrics, ZERO_ENCODED_REFERRER, buildAggregatedReferrerMetrics, buildAwardedReferrerMetrics, buildEncodedReferrer, buildEnsReferralUrl, buildRankedReferrerMetrics, buildReferralProgramRules, buildReferrerLeaderboard, buildReferrerLeaderboardPageContext, buildReferrerLeaderboardPageParams, buildReferrerMetrics, buildScoredReferrerMetrics, buildUnrankedReferrerMetrics, calcReferrerAwardPoolShare, calcReferrerFinalScore, calcReferrerFinalScoreBoost, calcReferrerFinalScoreMultiplier, calcReferrerScore, compareReferrerMetrics, decodeEncodedReferrer, getReferrerDetail, getReferrerLeaderboardPage, isFiniteNonNegativeNumber, isInteger, isNonNegativeInteger, isPositiveInteger, isReferrerQualified, isValidDuration, isValidReferrerScore, isValidUSDQuantity, normalizeAddress, sortReferrerMetrics, validateAggregatedReferrerMetrics, validateAwardedReferrerMetrics, validateDuration, validateLowercaseAddress, validateNonNegativeInteger, validateRankedReferrerMetrics, validateReferralProgramRules, validateReferrerLeaderboardPageContext, validateReferrerMetrics, validateReferrerRank, validateReferrerScore, validateScoredReferrerMetrics, validateUSDQuantity, validateUnixTimestamp, validateUnrankedReferrerMetrics };

package/dist/index.js

@@ -282,6 +282,65 @@ var buildAwardedReferrerMetrics = (referrer, aggregatedMetrics, rules) => {
   validateAwardedReferrerMetrics(result, rules);
   return result;
 };
+var validateUnrankedReferrerMetrics = (metrics) => {
+  validateScoredReferrerMetrics(metrics);
+  if (metrics.rank !== null) {
+    throw new Error(`Invalid UnrankedReferrerMetrics: rank must be null, got: ${metrics.rank}.`);
+  }
+  if (metrics.isQualified !== false) {
+    throw new Error(
+      `Invalid UnrankedReferrerMetrics: isQualified must be false, got: ${metrics.isQualified}.`
+    );
+  }
+  if (metrics.totalReferrals !== 0) {
+    throw new Error(
+      `Invalid UnrankedReferrerMetrics: totalReferrals must be 0, got: ${metrics.totalReferrals}.`
+    );
+  }
+  if (metrics.totalIncrementalDuration !== 0) {
+    throw new Error(
+      `Invalid UnrankedReferrerMetrics: totalIncrementalDuration must be 0, got: ${metrics.totalIncrementalDuration}.`
+    );
+  }
+  if (metrics.score !== 0) {
+    throw new Error(`Invalid UnrankedReferrerMetrics: score must be 0, got: ${metrics.score}.`);
+  }
+  if (metrics.finalScoreBoost !== 0) {
+    throw new Error(
+      `Invalid UnrankedReferrerMetrics: finalScoreBoost must be 0, got: ${metrics.finalScoreBoost}.`
+    );
+  }
+  if (metrics.finalScore !== 0) {
+    throw new Error(
+      `Invalid UnrankedReferrerMetrics: finalScore must be 0, got: ${metrics.finalScore}.`
+    );
+  }
+  if (metrics.awardPoolShare !== 0) {
+    throw new Error(
+      `Invalid UnrankedReferrerMetrics: awardPoolShare must be 0, got: ${metrics.awardPoolShare}.`
+    );
+  }
+  if (metrics.awardPoolApproxValue !== 0) {
+    throw new Error(
+      `Invalid UnrankedReferrerMetrics: awardPoolApproxValue must be 0, got: ${metrics.awardPoolApproxValue}.`
+    );
+  }
+};
+var buildUnrankedReferrerMetrics = (referrer) => {
+  const baseMetrics = buildReferrerMetrics(referrer, 0, 0);
+  const scoredMetrics = buildScoredReferrerMetrics(baseMetrics);
+  const result = {
+    ...scoredMetrics,
+    rank: null,
+    isQualified: false,
+    finalScoreBoost: 0,
+    finalScore: 0,
+    awardPoolShare: 0,
+    awardPoolApproxValue: 0
+  };
+  validateUnrankedReferrerMetrics(result);
+  return result;
+};
 
 // src/leaderboard.ts
 var buildReferrerLeaderboard = (allReferrers, rules, accurateAsOf) => {
@@ -321,66 +380,66 @@ var buildReferrerLeaderboard = (allReferrers, rules, accurateAsOf) => {
 // src/leaderboard-page.ts
 var REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT = 25;
 var REFERRERS_PER_LEADERBOARD_PAGE_MAX = 100;
-var validateReferrerLeaderboardPaginationParams = (params) => {
+var validateReferrerLeaderboardPageParams = (params) => {
   if (params.page !== void 0 && !isPositiveInteger(params.page)) {
     throw new Error(
-      `Invalid ReferrerLeaderboardPaginationParams: ${params.page}. page must be a positive integer.`
+      `Invalid ReferrerLeaderboardPageParams: ${params.page}. page must be a positive integer.`
     );
   }
   if (params.itemsPerPage !== void 0 && !isPositiveInteger(params.itemsPerPage)) {
     throw new Error(
-      `Invalid ReferrerLeaderboardPaginationParams: ${params.itemsPerPage}. itemsPerPage must be a positive integer.`
+      `Invalid ReferrerLeaderboardPageParams: ${params.itemsPerPage}. itemsPerPage must be a positive integer.`
     );
   }
   if (params.itemsPerPage !== void 0 && params.itemsPerPage > REFERRERS_PER_LEADERBOARD_PAGE_MAX) {
     throw new Error(
-      `Invalid ReferrerLeaderboardPaginationParams: ${params.itemsPerPage}. itemsPerPage must be less than or equal to ${REFERRERS_PER_LEADERBOARD_PAGE_MAX}.`
+      `Invalid ReferrerLeaderboardPageParams: ${params.itemsPerPage}. itemsPerPage must be less than or equal to ${REFERRERS_PER_LEADERBOARD_PAGE_MAX}.`
     );
   }
 };
-var buildReferrerLeaderboardPaginationParams = (params) => {
+var buildReferrerLeaderboardPageParams = (params) => {
   const result = {
     page: params.page ?? 1,
     itemsPerPage: params.itemsPerPage ?? REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT
   };
-  validateReferrerLeaderboardPaginationParams(result);
+  validateReferrerLeaderboardPageParams(result);
   return result;
 };
-var validateReferrerLeaderboardPaginationContext = (context) => {
-  validateReferrerLeaderboardPaginationParams(context);
+var validateReferrerLeaderboardPageContext = (context) => {
+  validateReferrerLeaderboardPageParams(context);
   if (!isNonNegativeInteger(context.totalRecords)) {
     throw new Error(
-      `Invalid ReferrerLeaderboardPaginationContext: total must be a non-negative integer but is ${context.totalRecords}.`
+      `Invalid ReferrerLeaderboardPageContext: total must be a non-negative integer but is ${context.totalRecords}.`
     );
   }
   const startIndex = (context.page - 1) * context.itemsPerPage;
   const endIndex = startIndex + context.itemsPerPage;
   if (!context.hasNext && endIndex < context.totalRecords) {
     throw new Error(
-      `Invalid ReferrerLeaderboardPaginationContext: if hasNext is false, endIndex (${endIndex}) must be greater than or equal to total (${context.totalRecords}).`
+      `Invalid ReferrerLeaderboardPageContext: if hasNext is false, endIndex (${endIndex}) must be greater than or equal to total (${context.totalRecords}).`
     );
   } else if (context.hasNext && context.page * context.itemsPerPage >= context.totalRecords) {
     throw new Error(
-      `Invalid ReferrerLeaderboardPaginationContext: if hasNext is true, endIndex (${endIndex}) must be less than total (${context.totalRecords}).`
+      `Invalid ReferrerLeaderboardPageContext: if hasNext is true, endIndex (${endIndex}) must be less than total (${context.totalRecords}).`
     );
   }
   if (!context.hasPrev && context.page !== 1) {
     throw new Error(
-      `Invalid ReferrerLeaderboardPaginationContext: if hasPrev is false, page must be the first page (1) but is ${context.page}.`
+      `Invalid ReferrerLeaderboardPageContext: if hasPrev is false, page must be the first page (1) but is ${context.page}.`
     );
   } else if (context.hasPrev && context.page === 1) {
     throw new Error(
-      `Invalid ReferrerLeaderboardPaginationContext: if hasPrev is true, page must not be the first page (1) but is ${context.page}.`
+      `Invalid ReferrerLeaderboardPageContext: if hasPrev is true, page must not be the first page (1) but is ${context.page}.`
     );
   }
 };
-var buildReferrerLeaderboardPaginationContext = (optionalParams, leaderboard) => {
-  const materializedParams = buildReferrerLeaderboardPaginationParams(optionalParams);
+var buildReferrerLeaderboardPageContext = (optionalParams, leaderboard) => {
+  const materializedParams = buildReferrerLeaderboardPageParams(optionalParams);
   const totalRecords = leaderboard.referrers.size;
   const totalPages = Math.max(1, Math.ceil(totalRecords / materializedParams.itemsPerPage));
   if (materializedParams.page > totalPages) {
     throw new Error(
-      `Invalid ReferrerLeaderboardPaginationContext: page ${materializedParams.page} exceeds total pages ${totalPages}.`
+      `Invalid ReferrerLeaderboardPageContext: page ${materializedParams.page} exceeds total pages ${totalPages}.`
     );
   }
   if (totalRecords === 0) {
@@ -397,7 +456,7 @@ var buildReferrerLeaderboardPaginationContext = (optionalParams, leaderboard) =>
   const startIndex = (materializedParams.page - 1) * materializedParams.itemsPerPage;
   const maxTheoreticalIndexOnPage = startIndex + (materializedParams.itemsPerPage - 1);
   const endIndex = Math.min(maxTheoreticalIndexOnPage, totalRecords - 1);
-  const hasNext = maxTheoreticalIndexOnPage < totalRecords;
+  const hasNext = maxTheoreticalIndexOnPage < totalRecords - 1;
   const hasPrev = materializedParams.page > 1;
   const result = {
     ...materializedParams,
@@ -408,14 +467,11 @@ var buildReferrerLeaderboardPaginationContext = (optionalParams, leaderboard) =>
     startIndex,
     endIndex
   };
-  validateReferrerLeaderboardPaginationContext(result);
+  validateReferrerLeaderboardPageContext(result);
   return result;
 };
 var getReferrerLeaderboardPage = (paginationParams, leaderboard) => {
-  const paginationContext = buildReferrerLeaderboardPaginationContext(
-    paginationParams,
-    leaderboard
-  );
+  const paginationContext = buildReferrerLeaderboardPageContext(paginationParams, leaderboard);
   let referrers;
   if (paginationContext.totalRecords > 0 && typeof paginationContext.startIndex !== "undefined" && typeof paginationContext.endIndex !== "undefined") {
     referrers = Array.from(leaderboard.referrers.values()).slice(
@@ -443,6 +499,37 @@ function buildEnsReferralUrl(address) {
   return ensAppUrl;
 }
 
+// src/referrer-detail.ts
+var ReferrerDetailTypeIds = {
+  /**
+   * Represents a referrer who is ranked on the leaderboard.
+   */
+  Ranked: "ranked",
+  /**
+   * Represents a referrer who is not ranked on the leaderboard.
+   */
+  Unranked: "unranked"
+};
+var getReferrerDetail = (referrer, leaderboard) => {
+  const awardedReferrerMetrics = leaderboard.referrers.get(referrer);
+  if (awardedReferrerMetrics) {
+    return {
+      type: ReferrerDetailTypeIds.Ranked,
+      rules: leaderboard.rules,
+      referrer: awardedReferrerMetrics,
+      aggregatedMetrics: leaderboard.aggregatedMetrics,
+      accurateAsOf: leaderboard.accurateAsOf
+    };
+  }
+  return {
+    type: ReferrerDetailTypeIds.Unranked,
+    rules: leaderboard.rules,
+    referrer: buildUnrankedReferrerMetrics(referrer),
+    aggregatedMetrics: leaderboard.aggregatedMetrics,
+    accurateAsOf: leaderboard.accurateAsOf
+  };
+};
+
 // src/rules.ts
 var ENS_HOLIDAY_AWARDS_START_DATE = 1764547200;
 var ENS_HOLIDAY_AWARDS_END_DATE = 1767225599;
@@ -480,6 +567,7 @@ export {
   EXPECTED_ENCODED_REFERRER_PADDING,
   REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT,
   REFERRERS_PER_LEADERBOARD_PAGE_MAX,
+  ReferrerDetailTypeIds,
   SECONDS_PER_YEAR,
   ZERO_ENCODED_REFERRER,
   buildAggregatedReferrerMetrics,
@@ -489,10 +577,11 @@ export {
   buildRankedReferrerMetrics,
   buildReferralProgramRules,
   buildReferrerLeaderboard,
-  buildReferrerLeaderboardPaginationContext,
-  buildReferrerLeaderboardPaginationParams,
+  buildReferrerLeaderboardPageContext,
+  buildReferrerLeaderboardPageParams,
   buildReferrerMetrics,
   buildScoredReferrerMetrics,
+  buildUnrankedReferrerMetrics,
   calcReferrerAwardPoolShare,
   calcReferrerFinalScore,
   calcReferrerFinalScoreBoost,
@@ -500,6 +589,7 @@ export {
   calcReferrerScore,
   compareReferrerMetrics,
   decodeEncodedReferrer,
+  getReferrerDetail,
   getReferrerLeaderboardPage,
   isFiniteNonNegativeNumber,
   isInteger,
@@ -518,12 +608,13 @@ export {
   validateNonNegativeInteger,
   validateRankedReferrerMetrics,
   validateReferralProgramRules,
-  validateReferrerLeaderboardPaginationContext,
+  validateReferrerLeaderboardPageContext,
   validateReferrerMetrics,
   validateReferrerRank,
   validateReferrerScore,
   validateScoredReferrerMetrics,
   validateUSDQuantity,
-  validateUnixTimestamp
+  validateUnixTimestamp,
+  validateUnrankedReferrerMetrics
 };
 //# sourceMappingURL=index.js.map