@namehash/ens-referrals 1.1.0 → 1.3.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)
@@ -416,10 +441,10 @@ interface ReferrerLeaderboardPaginationParams {
      * @invariant Must be a positive integer (>= 1) and less than or equal to {@link REFERRERS_PER_LEADERBOARD_PAGE_MAX}
      * @default {@link REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT}
      */
-    itemsPerPage?: number;
+    recordsPerPage?: 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)
@@ -432,7 +457,7 @@ interface ReferrerLeaderboardPaginationContext extends Required<ReferrerLeaderbo
     totalPages: number;
     /**
      * Indicates if there is a next page available
-     * @invariant true if and only if (`page` * `itemsPerPage` < `total`)
+     * @invariant true if and only if (`page` * `recordsPerPage` < `total`)
      */
     hasNext: boolean;
     /**
@@ -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.
  */
@@ -473,9 +498,9 @@ interface ReferrerLeaderboardPage {
     rules: ReferralProgramRules;
     /**
      * Ordered list of {@link AwardedReferrerMetrics} for the {@link ReferrerLeaderboardPage}
-     * described by `paginationContext` within the related {@link ReferrerLeaderboard}.
+     * described by `pageContext` within the related {@link ReferrerLeaderboard}.
      *
-     * @invariant Array will be empty if `paginationContext.totalRecords` is 0.
+     * @invariant Array will be empty if `pageContext.totalRecords` is 0.
      * @invariant Array entries are ordered by `rank` (descending).
      */
     referrers: AwardedReferrerMetrics[];
@@ -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;
+    pageContext: 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: (pageParams: 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)
@@ -416,10 +441,10 @@ interface ReferrerLeaderboardPaginationParams {
      * @invariant Must be a positive integer (>= 1) and less than or equal to {@link REFERRERS_PER_LEADERBOARD_PAGE_MAX}
      * @default {@link REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT}
      */
-    itemsPerPage?: number;
+    recordsPerPage?: 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)
@@ -432,7 +457,7 @@ interface ReferrerLeaderboardPaginationContext extends Required<ReferrerLeaderbo
     totalPages: number;
     /**
      * Indicates if there is a next page available
-     * @invariant true if and only if (`page` * `itemsPerPage` < `total`)
+     * @invariant true if and only if (`page` * `recordsPerPage` < `total`)
      */
     hasNext: boolean;
     /**
@@ -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.
  */
@@ -473,9 +498,9 @@ interface ReferrerLeaderboardPage {
     rules: ReferralProgramRules;
     /**
      * Ordered list of {@link AwardedReferrerMetrics} for the {@link ReferrerLeaderboardPage}
-     * described by `paginationContext` within the related {@link ReferrerLeaderboard}.
+     * described by `pageContext` within the related {@link ReferrerLeaderboard}.
      *
-     * @invariant Array will be empty if `paginationContext.totalRecords` is 0.
+     * @invariant Array will be empty if `pageContext.totalRecords` is 0.
      * @invariant Array entries are ordered by `rank` (descending).
      */
     referrers: AwardedReferrerMetrics[];
@@ -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;
+    pageContext: 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: (pageParams: 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 };