@provex/utils 1.0.16 → 1.2.3

package/dist/src/reputation.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @fileoverview Peer Taker Tiers Reputation System
+ *
+ * Implements the reputation-based rate limiting system for buyers (takers).
+ * Based on: https://docs.peer.xyz/guides/for-buyers/reputation
+ *
+ * The system works by combining:
+ * - **Tier configs**: Volume thresholds, base caps, and cooldown periods
+ * - **Platform risk configs**: Multipliers and cooldown flags from payment.ts
+ *
+ * @remarks
+ * These limits only apply to Base chain deposits using the peer gating service.
+ * Pulsechain deposits do not have reputation-based restrictions.
+ *
+ * Tier progression (by fulfilled volume in USD):
+ * - Peer Peasant: $0+ → $100 cap, 12h cooldown
+ * - Peer: $500+ → $250 cap, 6h cooldown
+ * - Peer Plus: $2,000+ → $1,000 cap, no cooldown
+ * - Peer Pro: $10,000+ → $2,500 cap, no cooldown
+ * - Peer Platinum: $25,000+ → $5,000 cap, no cooldown
+ * - Peer President: Manually assigned VIP → unlimited cap, no cooldown, bypasses all locks
+ *
+ * Platform multipliers modify the base cap:
+ * - Low risk (Revolut, Wise, Monzo, MercadoPago): 5x multiplier, no cooldown
+ * - Medium risk (Zelle): 1.5x multiplier
+ * - High risk (Venmo, CashApp): 1x multiplier
+ * - Highest risk (PayPal): 0.75x multiplier, requires Peer Plus tier
+ *
+ * @see {@link payment} for platform risk configurations
+ */
+import { type ProviderKey, type TakerTier } from './payment.js';
+/**
+ * Configuration for a single reputation tier.
+ * Defines the requirements and limits for users at this tier level.
+ */
+export interface TierConfig {
+    /** Display name for the tier */
+    name: string;
+    /** Minimum fulfilled volume (USD) to reach this tier. Infinity = manually assigned only. */
+    volumeThreshold: number;
+    /** Base per-intent cap (USD) before platform multiplier. 0 = unlimited (VIP). */
+    baseCap: number;
+    /** Cooldown duration in hours (0 = no cooldown) */
+    cooldownHours: number;
+    /** Volume range display text (e.g. "$500 - $2k") */
+    volumeRangeDisplay: string;
+}
+/**
+ * Complete tier configuration registry.
+ * Maps universal tier names to their configuration.
+ *
+ * @remarks
+ * Tier names in the codebase use short universal names (peasant, neutral, plus, pro, platinum, president)
+ * while the UI displays the peer brand names (Peer Peasant, Peer, Peer Plus, etc.)
+ */
+export declare const TAKER_TIERS: Record<TakerTier, TierConfig>;
+/**
+ * Ordered list of tiers from lowest to highest.
+ * president sits above platinum but is never reached via getTierFromVolume.
+ */
+export declare const TIER_ORDER: TakerTier[];
+/**
+ * Get the volume range display string for a tier.
+ * Matches peer.xyz's TR() function behaviour.
+ *
+ * @example
+ * getVolumeRangeDisplay('pro')    // "$10k - $25k"
+ * getVolumeRangeDisplay('president') // "VIP"
+ */
+export declare function getVolumeRangeDisplay(tier: TakerTier): string;
+/**
+ * Calculate the effective cap for a tier and platform combination.
+ * Derives from tier base cap and platform risk multiplier.
+ *
+ * @param tier - The user's current tier
+ * @param providerKey - The payment platform
+ * @returns Effective cap in USD, null if platform is locked for this tier,
+ *          or Infinity if the user is president (no cap).
+ */
+export declare function getEffectiveCap({ tier, providerKey, }: {
+    tier: TakerTier;
+    providerKey: ProviderKey;
+}): number | null;
+/**
+ * Get the cooldown duration for a tier and platform.
+ * Derives from tier cooldown hours and platform hasCooldown flag.
+ * @returns Cooldown in hours, or 0 if no cooldown.
+ */
+export declare function getCooldownHours({ tier, providerKey, }: {
+    tier: TakerTier;
+    providerKey: ProviderKey;
+}): number;
+/**
+ * Format cooldown duration for display
+ */
+export declare function formatCooldown(hours: number): string;
+/**
+ * Format cap for display
+ */
+export declare function formatCap(cap: number | null): string;
+/**
+ * Get tier from fulfilled volume.
+ * Note: 'president' is never returned here — it is assigned manually.
+ */
+export declare function getTierFromVolume(volumeUsd: number): TakerTier;
+/**
+ * Complete user reputation state including tier, volume, and cooldown status.
+ * Fetched from the peer gating service API.
+ *
+ * @remarks
+ * Volume is measured in USDC which is assumed 1:1 with USD for tier calculations.
+ */
+export interface UserReputation {
+    /** Current tier based on fulfilled volume */
+    tier: TakerTier;
+    /** Total fulfilled volume in USDC (6 decimals, 1:1 with USD) */
+    fulfilledVolumeUsdc: number;
+    lockScore: number;
+    cooldownEndsAt: Date | null;
+    isOnCooldown: boolean;
+}
+/**
+ * Default reputation for new/unknown users (most restrictive)
+ */
+export declare const DEFAULT_REPUTATION: UserReputation;

package/dist/src/reputation.js

@@ -0,0 +1,188 @@
+/**
+ * @fileoverview Peer Taker Tiers Reputation System
+ *
+ * Implements the reputation-based rate limiting system for buyers (takers).
+ * Based on: https://docs.peer.xyz/guides/for-buyers/reputation
+ *
+ * The system works by combining:
+ * - **Tier configs**: Volume thresholds, base caps, and cooldown periods
+ * - **Platform risk configs**: Multipliers and cooldown flags from payment.ts
+ *
+ * @remarks
+ * These limits only apply to Base chain deposits using the peer gating service.
+ * Pulsechain deposits do not have reputation-based restrictions.
+ *
+ * Tier progression (by fulfilled volume in USD):
+ * - Peer Peasant: $0+ → $100 cap, 12h cooldown
+ * - Peer: $500+ → $250 cap, 6h cooldown
+ * - Peer Plus: $2,000+ → $1,000 cap, no cooldown
+ * - Peer Pro: $10,000+ → $2,500 cap, no cooldown
+ * - Peer Platinum: $25,000+ → $5,000 cap, no cooldown
+ * - Peer President: Manually assigned VIP → unlimited cap, no cooldown, bypasses all locks
+ *
+ * Platform multipliers modify the base cap:
+ * - Low risk (Revolut, Wise, Monzo, MercadoPago): 5x multiplier, no cooldown
+ * - Medium risk (Zelle): 1.5x multiplier
+ * - High risk (Venmo, CashApp): 1x multiplier
+ * - Highest risk (PayPal): 0.75x multiplier, requires Peer Plus tier
+ *
+ * @see {@link payment} for platform risk configurations
+ */
+import { base } from 'viem/chains';
+import { tiers, getPlatformRisk, } from './payment.js';
+/**
+ * Complete tier configuration registry.
+ * Maps universal tier names to their configuration.
+ *
+ * @remarks
+ * Tier names in the codebase use short universal names (peasant, neutral, plus, pro, platinum, president)
+ * while the UI displays the peer brand names (Peer Peasant, Peer, Peer Plus, etc.)
+ */
+export const TAKER_TIERS = {
+    [tiers.PEASANT]: {
+        name: 'Peer Peasant',
+        volumeThreshold: 0,
+        baseCap: 100,
+        cooldownHours: 12,
+        volumeRangeDisplay: '$0 - $500',
+    },
+    [tiers.NEUTRAL]: {
+        name: 'Peer',
+        volumeThreshold: 500,
+        baseCap: 250,
+        cooldownHours: 6,
+        volumeRangeDisplay: '$500 - $2k',
+    },
+    [tiers.PLUS]: {
+        name: 'Peer Plus',
+        volumeThreshold: 2000,
+        baseCap: 1000,
+        cooldownHours: 0,
+        volumeRangeDisplay: '$2k - $10k',
+    },
+    [tiers.PRO]: {
+        name: 'Peer Pro',
+        volumeThreshold: 10000,
+        baseCap: 2500,
+        cooldownHours: 0,
+        volumeRangeDisplay: '$10k - $25k',
+    },
+    [tiers.PLATINUM]: {
+        name: 'Peer Platinum',
+        volumeThreshold: 25000,
+        baseCap: 5000,
+        cooldownHours: 0,
+        volumeRangeDisplay: '$25k+',
+    },
+    [tiers.PRESIDENT]: {
+        name: 'Peer President',
+        volumeThreshold: Infinity, // Manually assigned — cannot be reached via volume
+        baseCap: 0, // 0 = no cap (VIP limits)
+        cooldownHours: 0,
+        volumeRangeDisplay: 'VIP',
+    },
+};
+/**
+ * Ordered list of tiers from lowest to highest.
+ * president sits above platinum but is never reached via getTierFromVolume.
+ */
+export const TIER_ORDER = [
+    tiers.PEASANT, tiers.NEUTRAL, tiers.PLUS, tiers.PRO, tiers.PLATINUM, tiers.PRESIDENT,
+];
+/**
+ * Get the volume range display string for a tier.
+ * Matches peer.xyz's TR() function behaviour.
+ *
+ * @example
+ * getVolumeRangeDisplay('pro')    // "$10k - $25k"
+ * getVolumeRangeDisplay('president') // "VIP"
+ */
+export function getVolumeRangeDisplay(tier) {
+    return TAKER_TIERS[tier].volumeRangeDisplay;
+}
+/**
+ * Calculate the effective cap for a tier and platform combination.
+ * Derives from tier base cap and platform risk multiplier.
+ *
+ * @param tier - The user's current tier
+ * @param providerKey - The payment platform
+ * @returns Effective cap in USD, null if platform is locked for this tier,
+ *          or Infinity if the user is president (no cap).
+ */
+export function getEffectiveCap({ tier, providerKey, }) {
+    // President bypasses all caps and locks
+    if (tier === tiers.PRESIDENT)
+        return Infinity;
+    const tierConfig = TAKER_TIERS[tier];
+    const platformRisk = getPlatformRisk(base.id, providerKey);
+    // Check if platform is locked for this tier
+    if (platformRisk.minimumTier) {
+        const tierIndex = TIER_ORDER.indexOf(tier);
+        const minTierIndex = TIER_ORDER.indexOf(platformRisk.minimumTier);
+        if (tierIndex < minTierIndex) {
+            return null; // Platform locked
+        }
+    }
+    return Math.floor(tierConfig.baseCap * platformRisk.capMultiplier);
+}
+/**
+ * Get the cooldown duration for a tier and platform.
+ * Derives from tier cooldown hours and platform hasCooldown flag.
+ * @returns Cooldown in hours, or 0 if no cooldown.
+ */
+export function getCooldownHours({ tier, providerKey, }) {
+    // President has no cooldown on any platform
+    if (tier === tiers.PRESIDENT)
+        return 0;
+    const tierConfig = TAKER_TIERS[tier];
+    const platformRisk = getPlatformRisk(base.id, providerKey);
+    // Low-risk platforms have no cooldown regardless of tier
+    if (!platformRisk.hasCooldown)
+        return 0;
+    return tierConfig.cooldownHours;
+}
+/**
+ * Format cooldown duration for display
+ */
+export function formatCooldown(hours) {
+    if (hours === 0)
+        return 'No cooldown';
+    if (hours < 1)
+        return `${Math.round(hours * 60)}m cooldown`;
+    return `${hours}h cooldown`;
+}
+/**
+ * Format cap for display
+ */
+export function formatCap(cap) {
+    if (cap === null)
+        return 'Locked';
+    if (cap === Infinity)
+        return 'No limit';
+    return `$${cap.toLocaleString()} max`;
+}
+/**
+ * Get tier from fulfilled volume.
+ * Note: 'president' is never returned here — it is assigned manually.
+ */
+export function getTierFromVolume(volumeUsd) {
+    // Iterate from platinum down (exclude president — manual assignment only)
+    const volumeTiers = TIER_ORDER.filter(t => t !== tiers.PRESIDENT);
+    for (let i = volumeTiers.length - 1; i >= 0; i--) {
+        const tier = volumeTiers[i];
+        if (volumeUsd >= TAKER_TIERS[tier].volumeThreshold) {
+            return tier;
+        }
+    }
+    return 'peasant';
+}
+/**
+ * Default reputation for new/unknown users (most restrictive)
+ */
+export const DEFAULT_REPUTATION = {
+    tier: 'peasant',
+    fulfilledVolumeUsdc: 0,
+    lockScore: 0,
+    cooldownEndsAt: null,
+    isOnCooldown: false,
+};

package/dist/src/reputation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/reputation.test.js

@@ -0,0 +1,156 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { TAKER_TIERS, TIER_ORDER, getTierFromVolume, getEffectiveCap, getCooldownHours, getVolumeRangeDisplay, formatCooldown, formatCap, } from './reputation.js';
+import { tiers } from './payment.js';
+describe('TAKER_TIERS', () => {
+    it('should have correct tier names', () => {
+        assert.equal(TAKER_TIERS.peasant.name, 'Peer Peasant');
+        assert.equal(TAKER_TIERS.neutral.name, 'Peer');
+        assert.equal(TAKER_TIERS.plus.name, 'Peer Plus');
+        assert.equal(TAKER_TIERS.pro.name, 'Peer Pro');
+        assert.equal(TAKER_TIERS.platinum.name, 'Peer Platinum');
+    });
+    it('should have correct volume thresholds', () => {
+        assert.equal(TAKER_TIERS.peasant.volumeThreshold, 0);
+        assert.equal(TAKER_TIERS.neutral.volumeThreshold, 500);
+        assert.equal(TAKER_TIERS.plus.volumeThreshold, 2000);
+        assert.equal(TAKER_TIERS.pro.volumeThreshold, 10000);
+        assert.equal(TAKER_TIERS.platinum.volumeThreshold, 25000);
+    });
+    it('should have correct base caps', () => {
+        assert.equal(TAKER_TIERS.peasant.baseCap, 100);
+        assert.equal(TAKER_TIERS.neutral.baseCap, 250);
+        assert.equal(TAKER_TIERS.plus.baseCap, 1000);
+        assert.equal(TAKER_TIERS.pro.baseCap, 2500);
+        assert.equal(TAKER_TIERS.platinum.baseCap, 5000);
+    });
+    it('should have correct cooldown hours', () => {
+        assert.equal(TAKER_TIERS.peasant.cooldownHours, 12);
+        assert.equal(TAKER_TIERS.neutral.cooldownHours, 6);
+        assert.equal(TAKER_TIERS.plus.cooldownHours, 0);
+        assert.equal(TAKER_TIERS.pro.cooldownHours, 0);
+        assert.equal(TAKER_TIERS.platinum.cooldownHours, 0);
+    });
+});
+describe('TIER_ORDER', () => {
+    it('should be ordered from lowest to highest with president at top', () => {
+        assert.deepEqual(TIER_ORDER, [
+            tiers.PEASANT, tiers.NEUTRAL, tiers.PLUS, tiers.PRO, tiers.PLATINUM, tiers.PRESIDENT,
+        ]);
+    });
+    it('should match all keys in TAKER_TIERS', () => {
+        const tierKeys = Object.keys(TAKER_TIERS);
+        assert.equal(TIER_ORDER.length, tierKeys.length);
+        for (const tier of TIER_ORDER) {
+            assert.ok(tierKeys.includes(tier), `${tier} should be in TAKER_TIERS`);
+        }
+    });
+});
+describe('getVolumeRangeDisplay', () => {
+    it('should return correct range strings', () => {
+        assert.equal(getVolumeRangeDisplay('peasant'), '$0 - $500');
+        assert.equal(getVolumeRangeDisplay('neutral'), '$500 - $2k');
+        assert.equal(getVolumeRangeDisplay('plus'), '$2k - $10k');
+        assert.equal(getVolumeRangeDisplay('pro'), '$10k - $25k');
+        assert.equal(getVolumeRangeDisplay('platinum'), '$25k+');
+        assert.equal(getVolumeRangeDisplay('president'), 'VIP');
+    });
+});
+describe('getTierFromVolume', () => {
+    it('should return peasant for 0 volume', () => {
+        assert.equal(getTierFromVolume(0), 'peasant');
+    });
+    it('should return peasant for volume < 500', () => {
+        assert.equal(getTierFromVolume(100), 'peasant');
+        assert.equal(getTierFromVolume(499), 'peasant');
+    });
+    it('should return neutral for volume >= 500', () => {
+        assert.equal(getTierFromVolume(500), 'neutral');
+        assert.equal(getTierFromVolume(1000), 'neutral');
+        assert.equal(getTierFromVolume(1999), 'neutral');
+    });
+    it('should return plus for volume >= 2000', () => {
+        assert.equal(getTierFromVolume(2000), 'plus');
+        assert.equal(getTierFromVolume(5000), 'plus');
+        assert.equal(getTierFromVolume(9999), 'plus');
+    });
+    it('should return pro for volume >= 10000', () => {
+        assert.equal(getTierFromVolume(10000), 'pro');
+        assert.equal(getTierFromVolume(15000), 'pro');
+        assert.equal(getTierFromVolume(24999), 'pro');
+    });
+    it('should return platinum for volume >= 25000', () => {
+        assert.equal(getTierFromVolume(25000), 'platinum');
+        assert.equal(getTierFromVolume(50000), 'platinum');
+        assert.equal(getTierFromVolume(1000000), 'platinum');
+    });
+    it('should never return president (manually assigned only)', () => {
+        assert.notEqual(getTierFromVolume(1_000_000_000), tiers.PRESIDENT);
+    });
+});
+describe('getEffectiveCap', () => {
+    it('should calculate effective cap with multiplier', () => {
+        // Peasant ($100 base) with Revolut (5x) = $500
+        assert.equal(getEffectiveCap({ tier: 'peasant', providerKey: 'revolut' }), 500);
+        // Neutral ($250 base) with Zelle (1.5x) = $375
+        assert.equal(getEffectiveCap({ tier: 'neutral', providerKey: 'zelle' }), 375);
+        // Plus ($1000 base) with Venmo (1x) = $1000
+        assert.equal(getEffectiveCap({ tier: 'plus', providerKey: 'venmo' }), 1000);
+    });
+    it('should calculate effective cap for low-risk platforms (5x)', () => {
+        // Peasant ($100 base) with Monzo (5x) = $500
+        assert.equal(getEffectiveCap({ tier: 'peasant', providerKey: 'monzo' }), 500);
+        // Neutral ($250 base) with MercadoPago (5x) = $1250
+        assert.equal(getEffectiveCap({ tier: 'neutral', providerKey: 'mercadopago' }), 1250);
+    });
+    // PayPal tests removed — provider disabled until maker liquidity is established
+    it('should return Infinity for president on all platforms (VIP — no cap)', () => {
+        assert.equal(getEffectiveCap({ tier: tiers.PRESIDENT, providerKey: 'venmo' }), Infinity);
+        assert.equal(getEffectiveCap({ tier: tiers.PRESIDENT, providerKey: 'revolut' }), Infinity);
+    });
+});
+describe('getCooldownHours', () => {
+    it('should return 0 for low-risk platforms', () => {
+        assert.equal(getCooldownHours({ tier: 'peasant', providerKey: 'revolut' }), 0);
+        assert.equal(getCooldownHours({ tier: 'neutral', providerKey: 'wise' }), 0);
+        assert.equal(getCooldownHours({ tier: 'peasant', providerKey: 'monzo' }), 0);
+        assert.equal(getCooldownHours({ tier: 'neutral', providerKey: 'mercadopago' }), 0);
+    });
+    it('should return tier cooldown for high-risk platforms', () => {
+        // Peasant = 12h cooldown
+        assert.equal(getCooldownHours({ tier: 'peasant', providerKey: 'zelle' }), 12);
+        assert.equal(getCooldownHours({ tier: 'peasant', providerKey: 'venmo' }), 12);
+        // Neutral = 6h cooldown
+        assert.equal(getCooldownHours({ tier: 'neutral', providerKey: 'zelle' }), 6);
+        assert.equal(getCooldownHours({ tier: 'neutral', providerKey: 'cashapp' }), 6);
+    });
+    it('should return 0 for higher tiers', () => {
+        assert.equal(getCooldownHours({ tier: 'plus', providerKey: 'zelle' }), 0);
+        assert.equal(getCooldownHours({ tier: 'pro', providerKey: 'venmo' }), 0);
+        assert.equal(getCooldownHours({ tier: 'platinum', providerKey: 'monzo' }), 0);
+    });
+    it('should return 0 for president on all platforms (VIP — no cooldown)', () => {
+        assert.equal(getCooldownHours({ tier: tiers.PRESIDENT, providerKey: 'venmo' }), 0);
+        assert.equal(getCooldownHours({ tier: tiers.PRESIDENT, providerKey: 'zelle' }), 0);
+        assert.equal(getCooldownHours({ tier: tiers.PRESIDENT, providerKey: 'monzo' }), 0);
+    });
+});
+describe('formatCooldown', () => {
+    it('should format 0 hours as "No cooldown"', () => {
+        assert.equal(formatCooldown(0), 'No cooldown');
+    });
+    it('should format hours correctly', () => {
+        assert.equal(formatCooldown(6), '6h cooldown');
+        assert.equal(formatCooldown(12), '12h cooldown');
+    });
+});
+describe('formatCap', () => {
+    it('should format null as "Locked"', () => {
+        assert.equal(formatCap(null), 'Locked');
+    });
+    it('should format cap with dollar sign', () => {
+        assert.equal(formatCap(100), '$100 max');
+        assert.equal(formatCap(1000), '$1,000 max');
+        assert.equal(formatCap(5000), '$5,000 max');
+    });
+});

package/dist/src/sort.d.ts

@@ -1,17 +1,56 @@
+/**
+ * @fileoverview Generic sorting utilities for consistent ordering of data.
+ *
+ * Provides type-safe comparison functions that work with strings, numbers,
+ * and bigints, with support for ascending/descending order.
+ */
+/**
+ * Sort direction for ordering queries and displays.
+ * - 'asc': Ascending order (oldest first, lowest first)
+ * - 'desc': Descending order (newest first, highest first)
+ */
 export type SortDirection = 'asc' | 'desc';
+/**
+ * Types that can be sorted using orderedSort.
+ */
 export type Sortable = string | number | bigint;
 /**
- * Ordered sort
- * @param aVal - The first value
- * @param bVal - The second value
- * @param orderDirection - The order direction
- * @returns The sorted value
+ * Compare two values for sorting with configurable direction.
+ * Handles bigint, string, and number types with appropriate comparison logic.
+ *
+ * @param aVal - First value to compare
+ * @param bVal - Second value to compare
+ * @param orderDirection - Sort direction ('asc' or 'desc')
+ * @returns Negative if a < b, positive if a > b, zero if equal (adjusted for direction)
+ *
+ * @example
+ * ```ts
+ * // Sort numbers ascending
+ * [3, 1, 2].sort((a, b) => orderedSort(a, b, 'asc'))
+ * // [1, 2, 3]
+ *
+ * // Sort bigints descending
+ * [1n, 3n, 2n].sort((a, b) => orderedSort(a, b, 'desc'))
+ * // [3n, 2n, 1n]
+ * ```
  */
 export declare const orderedSort: (aVal: Sortable, bVal: Sortable, orderDirection: SortDirection) => number;
 /**
- * Ordered sort then by deposit ID
- * @param param0 - The parameters
- * @returns The sorted value
+ * Sort by a primary value, then by timestamp and deposit ID as tiebreakers.
+ * Ensures consistent ordering when primary sort values are equal.
+ *
+ * @param params - Sort parameters including primary values and entity metadata
+ * @returns Comparison result for Array.sort()
+ *
+ * @example
+ * ```ts
+ * deposits.sort((a, b) => orderedSortThenById({
+ *   aVal: a.amount,
+ *   bVal: b.amount,
+ *   orderDirection: 'desc',
+ *   a, b
+ * }))
+ * ```
  */
 export declare const orderedSortThenById: ({ aVal, bVal, orderDirection, a, b, }: {
     aVal: Sortable;
@@ -21,7 +60,7 @@ export declare const orderedSortThenById: ({ aVal, bVal, orderDirection, a, b, }
         depositId: bigint;
         transaction: {
             block: {
-                timestamp: string;
+                timestamp: bigint;
             };
         };
     };
@@ -29,7 +68,7 @@ export declare const orderedSortThenById: ({ aVal, bVal, orderDirection, a, b, }
         depositId: bigint;
         transaction: {
             block: {
-                timestamp: string;
+                timestamp: bigint;
             };
         };
     };

package/dist/src/sort.js

@@ -1,9 +1,28 @@
 /**
- * Ordered sort
- * @param aVal - The first value
- * @param bVal - The second value
- * @param orderDirection - The order direction
- * @returns The sorted value
+ * @fileoverview Generic sorting utilities for consistent ordering of data.
+ *
+ * Provides type-safe comparison functions that work with strings, numbers,
+ * and bigints, with support for ascending/descending order.
+ */
+/**
+ * Compare two values for sorting with configurable direction.
+ * Handles bigint, string, and number types with appropriate comparison logic.
+ *
+ * @param aVal - First value to compare
+ * @param bVal - Second value to compare
+ * @param orderDirection - Sort direction ('asc' or 'desc')
+ * @returns Negative if a < b, positive if a > b, zero if equal (adjusted for direction)
+ *
+ * @example
+ * ```ts
+ * // Sort numbers ascending
+ * [3, 1, 2].sort((a, b) => orderedSort(a, b, 'asc'))
+ * // [1, 2, 3]
+ *
+ * // Sort bigints descending
+ * [1n, 3n, 2n].sort((a, b) => orderedSort(a, b, 'desc'))
+ * // [3n, 2n, 1n]
+ * ```
  */
 export const orderedSort = (aVal, bVal, orderDirection) => {
     if (typeof aVal === 'bigint' && typeof bVal === 'bigint') {
@@ -24,15 +43,27 @@ export const orderedSort = (aVal, bVal, orderDirection) => {
     }
 };
 /**
- * Ordered sort then by deposit ID
- * @param param0 - The parameters
- * @returns The sorted value
+ * Sort by a primary value, then by timestamp and deposit ID as tiebreakers.
+ * Ensures consistent ordering when primary sort values are equal.
+ *
+ * @param params - Sort parameters including primary values and entity metadata
+ * @returns Comparison result for Array.sort()
+ *
+ * @example
+ * ```ts
+ * deposits.sort((a, b) => orderedSortThenById({
+ *   aVal: a.amount,
+ *   bVal: b.amount,
+ *   orderDirection: 'desc',
+ *   a, b
+ * }))
+ * ```
  */
 export const orderedSortThenById = ({ aVal, bVal, orderDirection, a, b, }) => {
     let result = orderedSort(aVal, bVal, orderDirection);
     if (result !== 0)
         return result;
-    result = orderedSort(BigInt(a.transaction.block.timestamp), BigInt(b.transaction.block.timestamp), 'asc');
+    result = orderedSort(a.transaction.block.timestamp, b.transaction.block.timestamp, 'asc');
     if (result !== 0)
         return result;
     return orderedSort(a.depositId, b.depositId, 'asc');

package/dist/src/sort.test.d.ts

@@ -0,0 +1 @@
+export {};