@namehash/ens-referrals 1.2.0 → 1.4.0

package/dist/index.d.cts

@@ -180,6 +180,33 @@ interface ReferrerMetricsForComparison {
 }
 declare const compareReferrerMetrics: (a: ReferrerMetricsForComparison, b: ReferrerMetricsForComparison) => number;
 
+/**
+ * Revenue Contribution
+ *
+ * Represents the total revenue contribution (in Wei) made to the ENS DAO.
+ *
+ * This is the sum of the total cost paid by registrants for registrar actions.
+ * From the perspective of the ENS DAO, this represents revenue received.
+ *
+ * @invariant Guaranteed to be a non-negative bigint value (>= 0n)
+ * @invariant Never null (records with null `total` in the database are treated as 0 when summing)
+ */
+type RevenueContribution = bigint;
+/**
+ * Check if a value is a valid revenue contribution.
+ *
+ * @param value - The value to check
+ * @returns true if the value is a non-negative bigint, false otherwise
+ */
+declare function isValidRevenueContribution(value: unknown): value is RevenueContribution;
+/**
+ * Validate that a value is a valid revenue contribution.
+ *
+ * @param value - The value to validate
+ * @throws {Error} If the value is not a valid revenue contribution
+ */
+declare function validateRevenueContribution(value: unknown): void;
+
 /**
  * Represents metrics for a single referrer independent of other referrers.
  */
@@ -200,8 +227,19 @@ interface ReferrerMetrics {
      * the {@link ReferralProgramRules}.
      */
     totalIncrementalDuration: Duration;
+    /**
+     * The total revenue contribution (in Wei) made to the ENS DAO by all referrals
+     * from this referrer.
+     *
+     * This is the sum of the total cost paid by registrants for all registrar actions
+     * where this address was the referrer.
+     *
+     * @invariant Guaranteed to be a non-negative bigint value (>= 0n)
+     * @invariant Never null (records with null `total` in the database are treated as 0 when summing)
+     */
+    totalRevenueContribution: RevenueContribution;
 }
-declare const buildReferrerMetrics: (referrer: Address, totalReferrals: number, totalIncrementalDuration: Duration) => ReferrerMetrics;
+declare const buildReferrerMetrics: (referrer: Address, totalReferrals: number, totalIncrementalDuration: Duration, totalRevenueContribution: RevenueContribution) => ReferrerMetrics;
 declare const validateReferrerMetrics: (metrics: ReferrerMetrics) => void;
 declare const sortReferrerMetrics: (referrers: ReferrerMetrics[]) => ReferrerMetrics[];
 /**
@@ -318,6 +356,15 @@ interface AggregatedReferrerMetrics {
      * @invariant The sum of `totalIncrementalDuration` across all `RankedReferrerMetrics` in the list.
      */
     grandTotalIncrementalDuration: Duration;
+    /**
+     * The total revenue contribution (in Wei) to the ENS DAO from all referrals
+     * across all referrers on the leaderboard.
+     *
+     * This is the sum of `totalRevenueContribution` across all `RankedReferrerMetrics` in the list.
+     *
+     * @invariant Guaranteed to be a non-negative bigint value (>= 0n)
+     */
+    grandTotalRevenueContribution: RevenueContribution;
     /**
      * @invariant The sum of `finalScore` across all `RankedReferrerMetrics` where `isQualified` is `true`.
      */
@@ -441,7 +488,7 @@ interface ReferrerLeaderboardPageParams {
      * @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 buildReferrerLeaderboardPageParams: (params: ReferrerLeaderboardPageParams) => Required<ReferrerLeaderboardPageParams>;
 interface ReferrerLeaderboardPageContext extends Required<ReferrerLeaderboardPageParams> {
@@ -457,7 +504,7 @@ interface ReferrerLeaderboardPageContext extends Required<ReferrerLeaderboardPag
     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;
     /**
@@ -498,9 +545,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[];
@@ -512,13 +559,13 @@ interface ReferrerLeaderboardPage {
      * The {@link ReferrerLeaderboardPageContext} of this {@link ReferrerLeaderboardPage} relative to the overall
      * {@link ReferrerLeaderboard}.
      */
-    paginationContext: ReferrerLeaderboardPageContext;
+    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: ReferrerLeaderboardPageParams, leaderboard: ReferrerLeaderboard) => ReferrerLeaderboardPage;
+declare const getReferrerLeaderboardPage: (pageParams: ReferrerLeaderboardPageParams, leaderboard: ReferrerLeaderboard) => ReferrerLeaderboardPage;
 
 /**
  * Build a URL to the official ENS manager app
@@ -637,4 +684,36 @@ type ReferrerDetail = ReferrerDetailRanked | ReferrerDetailUnranked;
  */
 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 };
+/**
+ * The type of referral program's status.
+ */
+declare const ReferralProgramStatuses: {
+    /**
+     * Represents a referral program that has been announced, but hasn't started yet.
+     */
+    readonly Scheduled: "Scheduled";
+    /**
+     * Represents a currently ongoing referral program.
+     */
+    readonly Active: "Active";
+    /**
+     * Represents a referral program that has already ended.
+     */
+    readonly Closed: "Closed";
+};
+/**
+ * The derived string union of possible {@link ReferralProgramStatuses}.
+ */
+type ReferralProgramStatusId = (typeof ReferralProgramStatuses)[keyof typeof ReferralProgramStatuses];
+/**
+ * Calculate the status of the referral program based on the current date
+ * and program's timeframe available in its rules.
+ *
+ * @param referralProgramRules - Related referral program's rules containing
+ * program's start date and end date.
+ *
+ * @param now - Current date in {@link UnixTimestamp} format.
+ */
+declare const calcReferralProgramStatus: (referralProgramRules: ReferralProgramRules, now: UnixTimestamp) => ReferralProgramStatusId;
+
+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 ReferralProgramStatusId, ReferralProgramStatuses, 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, type RevenueContribution, 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, calcReferralProgramStatus, calcReferrerAwardPoolShare, calcReferrerFinalScore, calcReferrerFinalScoreBoost, calcReferrerFinalScoreMultiplier, calcReferrerScore, compareReferrerMetrics, decodeEncodedReferrer, getReferrerDetail, getReferrerLeaderboardPage, isFiniteNonNegativeNumber, isInteger, isNonNegativeInteger, isPositiveInteger, isReferrerQualified, isValidDuration, isValidReferrerScore, isValidRevenueContribution, isValidUSDQuantity, normalizeAddress, sortReferrerMetrics, validateAggregatedReferrerMetrics, validateAwardedReferrerMetrics, validateDuration, validateLowercaseAddress, validateNonNegativeInteger, validateRankedReferrerMetrics, validateReferralProgramRules, validateReferrerLeaderboardPageContext, validateReferrerMetrics, validateReferrerRank, validateReferrerScore, validateRevenueContribution, validateScoredReferrerMetrics, validateUSDQuantity, validateUnixTimestamp, validateUnrankedReferrerMetrics };

package/dist/index.d.ts

@@ -180,6 +180,33 @@ interface ReferrerMetricsForComparison {
 }
 declare const compareReferrerMetrics: (a: ReferrerMetricsForComparison, b: ReferrerMetricsForComparison) => number;
 
+/**
+ * Revenue Contribution
+ *
+ * Represents the total revenue contribution (in Wei) made to the ENS DAO.
+ *
+ * This is the sum of the total cost paid by registrants for registrar actions.
+ * From the perspective of the ENS DAO, this represents revenue received.
+ *
+ * @invariant Guaranteed to be a non-negative bigint value (>= 0n)
+ * @invariant Never null (records with null `total` in the database are treated as 0 when summing)
+ */
+type RevenueContribution = bigint;
+/**
+ * Check if a value is a valid revenue contribution.
+ *
+ * @param value - The value to check
+ * @returns true if the value is a non-negative bigint, false otherwise
+ */
+declare function isValidRevenueContribution(value: unknown): value is RevenueContribution;
+/**
+ * Validate that a value is a valid revenue contribution.
+ *
+ * @param value - The value to validate
+ * @throws {Error} If the value is not a valid revenue contribution
+ */
+declare function validateRevenueContribution(value: unknown): void;
+
 /**
  * Represents metrics for a single referrer independent of other referrers.
  */
@@ -200,8 +227,19 @@ interface ReferrerMetrics {
      * the {@link ReferralProgramRules}.
      */
     totalIncrementalDuration: Duration;
+    /**
+     * The total revenue contribution (in Wei) made to the ENS DAO by all referrals
+     * from this referrer.
+     *
+     * This is the sum of the total cost paid by registrants for all registrar actions
+     * where this address was the referrer.
+     *
+     * @invariant Guaranteed to be a non-negative bigint value (>= 0n)
+     * @invariant Never null (records with null `total` in the database are treated as 0 when summing)
+     */
+    totalRevenueContribution: RevenueContribution;
 }
-declare const buildReferrerMetrics: (referrer: Address, totalReferrals: number, totalIncrementalDuration: Duration) => ReferrerMetrics;
+declare const buildReferrerMetrics: (referrer: Address, totalReferrals: number, totalIncrementalDuration: Duration, totalRevenueContribution: RevenueContribution) => ReferrerMetrics;
 declare const validateReferrerMetrics: (metrics: ReferrerMetrics) => void;
 declare const sortReferrerMetrics: (referrers: ReferrerMetrics[]) => ReferrerMetrics[];
 /**
@@ -318,6 +356,15 @@ interface AggregatedReferrerMetrics {
      * @invariant The sum of `totalIncrementalDuration` across all `RankedReferrerMetrics` in the list.
      */
     grandTotalIncrementalDuration: Duration;
+    /**
+     * The total revenue contribution (in Wei) to the ENS DAO from all referrals
+     * across all referrers on the leaderboard.
+     *
+     * This is the sum of `totalRevenueContribution` across all `RankedReferrerMetrics` in the list.
+     *
+     * @invariant Guaranteed to be a non-negative bigint value (>= 0n)
+     */
+    grandTotalRevenueContribution: RevenueContribution;
     /**
      * @invariant The sum of `finalScore` across all `RankedReferrerMetrics` where `isQualified` is `true`.
      */
@@ -441,7 +488,7 @@ interface ReferrerLeaderboardPageParams {
      * @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 buildReferrerLeaderboardPageParams: (params: ReferrerLeaderboardPageParams) => Required<ReferrerLeaderboardPageParams>;
 interface ReferrerLeaderboardPageContext extends Required<ReferrerLeaderboardPageParams> {
@@ -457,7 +504,7 @@ interface ReferrerLeaderboardPageContext extends Required<ReferrerLeaderboardPag
     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;
     /**
@@ -498,9 +545,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[];
@@ -512,13 +559,13 @@ interface ReferrerLeaderboardPage {
      * The {@link ReferrerLeaderboardPageContext} of this {@link ReferrerLeaderboardPage} relative to the overall
      * {@link ReferrerLeaderboard}.
      */
-    paginationContext: ReferrerLeaderboardPageContext;
+    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: ReferrerLeaderboardPageParams, leaderboard: ReferrerLeaderboard) => ReferrerLeaderboardPage;
+declare const getReferrerLeaderboardPage: (pageParams: ReferrerLeaderboardPageParams, leaderboard: ReferrerLeaderboard) => ReferrerLeaderboardPage;
 
 /**
  * Build a URL to the official ENS manager app
@@ -637,4 +684,36 @@ type ReferrerDetail = ReferrerDetailRanked | ReferrerDetailUnranked;
  */
 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 };
+/**
+ * The type of referral program's status.
+ */
+declare const ReferralProgramStatuses: {
+    /**
+     * Represents a referral program that has been announced, but hasn't started yet.
+     */
+    readonly Scheduled: "Scheduled";
+    /**
+     * Represents a currently ongoing referral program.
+     */
+    readonly Active: "Active";
+    /**
+     * Represents a referral program that has already ended.
+     */
+    readonly Closed: "Closed";
+};
+/**
+ * The derived string union of possible {@link ReferralProgramStatuses}.
+ */
+type ReferralProgramStatusId = (typeof ReferralProgramStatuses)[keyof typeof ReferralProgramStatuses];
+/**
+ * Calculate the status of the referral program based on the current date
+ * and program's timeframe available in its rules.
+ *
+ * @param referralProgramRules - Related referral program's rules containing
+ * program's start date and end date.
+ *
+ * @param now - Current date in {@link UnixTimestamp} format.
+ */
+declare const calcReferralProgramStatus: (referralProgramRules: ReferralProgramRules, now: UnixTimestamp) => ReferralProgramStatusId;
+
+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 ReferralProgramStatusId, ReferralProgramStatuses, 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, type RevenueContribution, 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, calcReferralProgramStatus, calcReferrerAwardPoolShare, calcReferrerFinalScore, calcReferrerFinalScoreBoost, calcReferrerFinalScoreMultiplier, calcReferrerScore, compareReferrerMetrics, decodeEncodedReferrer, getReferrerDetail, getReferrerLeaderboardPage, isFiniteNonNegativeNumber, isInteger, isNonNegativeInteger, isPositiveInteger, isReferrerQualified, isValidDuration, isValidReferrerScore, isValidRevenueContribution, isValidUSDQuantity, normalizeAddress, sortReferrerMetrics, validateAggregatedReferrerMetrics, validateAwardedReferrerMetrics, validateDuration, validateLowercaseAddress, validateNonNegativeInteger, validateRankedReferrerMetrics, validateReferralProgramRules, validateReferrerLeaderboardPageContext, validateReferrerMetrics, validateReferrerRank, validateReferrerScore, validateRevenueContribution, validateScoredReferrerMetrics, validateUSDQuantity, validateUnixTimestamp, validateUnrankedReferrerMetrics };

package/dist/index.js

@@ -31,6 +31,19 @@ var isFiniteNonNegativeNumber = (value) => {
   return value >= 0 && Number.isFinite(value);
 };
 
+// src/revenue-contribution.ts
+function isValidRevenueContribution(value) {
+  return typeof value === "bigint" && value >= 0n;
+}
+function validateRevenueContribution(value) {
+  if (typeof value !== "bigint") {
+    throw new Error(`Invalid revenue contribution: must be a bigint, got: ${typeof value}`);
+  }
+  if (value < 0n) {
+    throw new Error(`Invalid revenue contribution: must be non-negative, got: ${value.toString()}`);
+  }
+}
+
 // src/time.ts
 var validateUnixTimestamp = (timestamp) => {
   if (!isInteger(timestamp)) {
@@ -66,17 +79,20 @@ var calcReferrerScore = (totalIncrementalDuration) => {
 var validateAggregatedReferrerMetrics = (metrics) => {
   validateNonNegativeInteger(metrics.grandTotalReferrals);
   validateDuration(metrics.grandTotalIncrementalDuration);
+  validateRevenueContribution(metrics.grandTotalRevenueContribution);
   validateReferrerScore(metrics.grandTotalQualifiedReferrersFinalScore);
   validateReferrerScore(metrics.minFinalScoreToQualify);
 };
 var buildAggregatedReferrerMetrics = (referrers, rules) => {
   let grandTotalReferrals = 0;
   let grandTotalIncrementalDuration = 0;
+  let grandTotalRevenueContribution = 0n;
   let grandTotalQualifiedReferrersFinalScore = 0;
   let minFinalScoreToQualify = Number.MAX_SAFE_INTEGER;
   for (const referrer of referrers) {
     grandTotalReferrals += referrer.totalReferrals;
     grandTotalIncrementalDuration += referrer.totalIncrementalDuration;
+    grandTotalRevenueContribution += referrer.totalRevenueContribution;
     if (referrer.isQualified) {
       grandTotalQualifiedReferrersFinalScore += referrer.finalScore;
       if (referrer.finalScore < minFinalScoreToQualify) {
@@ -98,6 +114,7 @@ var buildAggregatedReferrerMetrics = (referrers, rules) => {
   const result = {
     grandTotalReferrals,
     grandTotalIncrementalDuration,
+    grandTotalRevenueContribution,
     grandTotalQualifiedReferrersFinalScore,
     minFinalScoreToQualify
   };
@@ -178,11 +195,12 @@ var compareReferrerMetrics = (a, b) => {
 };
 
 // src/referrer-metrics.ts
-var buildReferrerMetrics = (referrer, totalReferrals, totalIncrementalDuration) => {
+var buildReferrerMetrics = (referrer, totalReferrals, totalIncrementalDuration, totalRevenueContribution) => {
   const result = {
     referrer: normalizeAddress(referrer),
     totalReferrals,
-    totalIncrementalDuration
+    totalIncrementalDuration,
+    totalRevenueContribution
   };
   validateReferrerMetrics(result);
   return result;
@@ -191,6 +209,7 @@ var validateReferrerMetrics = (metrics) => {
   validateLowercaseAddress(metrics.referrer);
   validateNonNegativeInteger(metrics.totalReferrals);
   validateDuration(metrics.totalIncrementalDuration);
+  validateRevenueContribution(metrics.totalRevenueContribution);
 };
 var sortReferrerMetrics = (referrers) => {
   return [...referrers].sort(compareReferrerMetrics);
@@ -302,6 +321,11 @@ var validateUnrankedReferrerMetrics = (metrics) => {
       `Invalid UnrankedReferrerMetrics: totalIncrementalDuration must be 0, got: ${metrics.totalIncrementalDuration}.`
     );
   }
+  if (metrics.totalRevenueContribution !== 0n) {
+    throw new Error(
+      `Invalid UnrankedReferrerMetrics: totalRevenueContribution must be 0n, got: ${metrics.totalRevenueContribution.toString()}.`
+    );
+  }
   if (metrics.score !== 0) {
     throw new Error(`Invalid UnrankedReferrerMetrics: score must be 0, got: ${metrics.score}.`);
   }
@@ -327,7 +351,7 @@ var validateUnrankedReferrerMetrics = (metrics) => {
   }
 };
 var buildUnrankedReferrerMetrics = (referrer) => {
-  const baseMetrics = buildReferrerMetrics(referrer, 0, 0);
+  const baseMetrics = buildReferrerMetrics(referrer, 0, 0, 0n);
   const scoredMetrics = buildScoredReferrerMetrics(baseMetrics);
   const result = {
     ...scoredMetrics,
@@ -386,21 +410,21 @@ var validateReferrerLeaderboardPageParams = (params) => {
       `Invalid ReferrerLeaderboardPageParams: ${params.page}. page must be a positive integer.`
     );
   }
-  if (params.itemsPerPage !== void 0 && !isPositiveInteger(params.itemsPerPage)) {
+  if (params.recordsPerPage !== void 0 && !isPositiveInteger(params.recordsPerPage)) {
     throw new Error(
-      `Invalid ReferrerLeaderboardPageParams: ${params.itemsPerPage}. itemsPerPage must be a positive integer.`
+      `Invalid ReferrerLeaderboardPageParams: ${params.recordsPerPage}. recordsPerPage must be a positive integer.`
     );
   }
-  if (params.itemsPerPage !== void 0 && params.itemsPerPage > REFERRERS_PER_LEADERBOARD_PAGE_MAX) {
+  if (params.recordsPerPage !== void 0 && params.recordsPerPage > REFERRERS_PER_LEADERBOARD_PAGE_MAX) {
     throw new Error(
-      `Invalid ReferrerLeaderboardPageParams: ${params.itemsPerPage}. itemsPerPage must be less than or equal to ${REFERRERS_PER_LEADERBOARD_PAGE_MAX}.`
+      `Invalid ReferrerLeaderboardPageParams: ${params.recordsPerPage}. recordsPerPage must be less than or equal to ${REFERRERS_PER_LEADERBOARD_PAGE_MAX}.`
     );
   }
 };
 var buildReferrerLeaderboardPageParams = (params) => {
   const result = {
     page: params.page ?? 1,
-    itemsPerPage: params.itemsPerPage ?? REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT
+    recordsPerPage: params.recordsPerPage ?? REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT
   };
   validateReferrerLeaderboardPageParams(result);
   return result;
@@ -412,13 +436,13 @@ var validateReferrerLeaderboardPageContext = (context) => {
       `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;
+  const startIndex = (context.page - 1) * context.recordsPerPage;
+  const endIndex = startIndex + context.recordsPerPage;
   if (!context.hasNext && endIndex < context.totalRecords) {
     throw new Error(
       `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) {
+  } else if (context.hasNext && context.page * context.recordsPerPage >= context.totalRecords) {
     throw new Error(
       `Invalid ReferrerLeaderboardPageContext: if hasNext is true, endIndex (${endIndex}) must be less than total (${context.totalRecords}).`
     );
@@ -436,7 +460,7 @@ var validateReferrerLeaderboardPageContext = (context) => {
 var buildReferrerLeaderboardPageContext = (optionalParams, leaderboard) => {
   const materializedParams = buildReferrerLeaderboardPageParams(optionalParams);
   const totalRecords = leaderboard.referrers.size;
-  const totalPages = Math.max(1, Math.ceil(totalRecords / materializedParams.itemsPerPage));
+  const totalPages = Math.max(1, Math.ceil(totalRecords / materializedParams.recordsPerPage));
   if (materializedParams.page > totalPages) {
     throw new Error(
       `Invalid ReferrerLeaderboardPageContext: page ${materializedParams.page} exceeds total pages ${totalPages}.`
@@ -453,8 +477,8 @@ var buildReferrerLeaderboardPageContext = (optionalParams, leaderboard) => {
       endIndex: void 0
     };
   }
-  const startIndex = (materializedParams.page - 1) * materializedParams.itemsPerPage;
-  const maxTheoreticalIndexOnPage = startIndex + (materializedParams.itemsPerPage - 1);
+  const startIndex = (materializedParams.page - 1) * materializedParams.recordsPerPage;
+  const maxTheoreticalIndexOnPage = startIndex + (materializedParams.recordsPerPage - 1);
   const endIndex = Math.min(maxTheoreticalIndexOnPage, totalRecords - 1);
   const hasNext = maxTheoreticalIndexOnPage < totalRecords - 1;
   const hasPrev = materializedParams.page > 1;
@@ -470,13 +494,13 @@ var buildReferrerLeaderboardPageContext = (optionalParams, leaderboard) => {
   validateReferrerLeaderboardPageContext(result);
   return result;
 };
-var getReferrerLeaderboardPage = (paginationParams, leaderboard) => {
-  const paginationContext = buildReferrerLeaderboardPageContext(paginationParams, leaderboard);
+var getReferrerLeaderboardPage = (pageParams, leaderboard) => {
+  const pageContext = buildReferrerLeaderboardPageContext(pageParams, leaderboard);
   let referrers;
-  if (paginationContext.totalRecords > 0 && typeof paginationContext.startIndex !== "undefined" && typeof paginationContext.endIndex !== "undefined") {
+  if (pageContext.totalRecords > 0 && typeof pageContext.startIndex !== "undefined" && typeof pageContext.endIndex !== "undefined") {
     referrers = Array.from(leaderboard.referrers.values()).slice(
-      paginationContext.startIndex,
-      paginationContext.endIndex + 1
+      pageContext.startIndex,
+      pageContext.endIndex + 1
       // For `slice`, this is exclusive of the element at the index 'end'. We need it to be inclusive, hence plus one.
     );
   } else {
@@ -486,7 +510,7 @@ var getReferrerLeaderboardPage = (paginationParams, leaderboard) => {
     rules: leaderboard.rules,
     referrers,
     aggregatedMetrics: leaderboard.aggregatedMetrics,
-    paginationContext,
+    pageContext,
     accurateAsOf: leaderboard.accurateAsOf
   };
 };
@@ -557,6 +581,27 @@ var buildReferralProgramRules = (totalAwardPoolValue, maxQualifiedReferrers, sta
   validateReferralProgramRules(result);
   return result;
 };
+
+// src/status.ts
+var ReferralProgramStatuses = {
+  /**
+   * Represents a referral program that has been announced, but hasn't started yet.
+   */
+  Scheduled: "Scheduled",
+  /**
+   * Represents a currently ongoing referral program.
+   */
+  Active: "Active",
+  /**
+   * Represents a referral program that has already ended.
+   */
+  Closed: "Closed"
+};
+var calcReferralProgramStatus = (referralProgramRules, now) => {
+  if (now < referralProgramRules.startTime) return ReferralProgramStatuses.Scheduled;
+  if (now > referralProgramRules.endTime) return ReferralProgramStatuses.Closed;
+  return ReferralProgramStatuses.Active;
+};
 export {
   ENCODED_REFERRER_BYTE_LENGTH,
   ENCODED_REFERRER_BYTE_OFFSET,
@@ -567,6 +612,7 @@ export {
   EXPECTED_ENCODED_REFERRER_PADDING,
   REFERRERS_PER_LEADERBOARD_PAGE_DEFAULT,
   REFERRERS_PER_LEADERBOARD_PAGE_MAX,
+  ReferralProgramStatuses,
   ReferrerDetailTypeIds,
   SECONDS_PER_YEAR,
   ZERO_ENCODED_REFERRER,
@@ -582,6 +628,7 @@ export {
   buildReferrerMetrics,
   buildScoredReferrerMetrics,
   buildUnrankedReferrerMetrics,
+  calcReferralProgramStatus,
   calcReferrerAwardPoolShare,
   calcReferrerFinalScore,
   calcReferrerFinalScoreBoost,
@@ -598,6 +645,7 @@ export {
   isReferrerQualified,
   isValidDuration,
   isValidReferrerScore,
+  isValidRevenueContribution,
   isValidUSDQuantity,
   normalizeAddress,
   sortReferrerMetrics,
@@ -612,6 +660,7 @@ export {
   validateReferrerMetrics,
   validateReferrerRank,
   validateReferrerScore,
+  validateRevenueContribution,
   validateScoredReferrerMetrics,
   validateUSDQuantity,
   validateUnixTimestamp,