@augustdigital/sdk 8.3.2 → 8.5.0

package/lib/core/helpers/web3.d.ts

@@ -2,31 +2,183 @@ import { ethers, Interface, InterfaceAbi, JsonRpcProvider } from 'ethers';
 import type { Abi } from 'abitype';
 import type { TypedContract } from '../../types/typed-contract';
 import { IAddress, IContractRunner, IInfuraOptions } from '../../types';
+/**
+ * Web3 Helper Utilities
+ *
+ * Core utilities for blockchain interaction:
+ * - Provider Management: createProvider, getInfuraProvider, getChainId
+ * - Contract Helpers: createContract, getDecimals, getSymbol, getTokenMetadata
+ * - Transaction Utilities: simulateTransaction, checkAddress
+ * - Historical Queries: getHistoricalContractData, getHistoricalContractDataByDate
+ * - Oracle Integration: getLoanOracleFeeRate
+ * - Block Utilities: determineBlockCutoff, determineBlockSkipInternal
+ */
+/**
+ * Get maximum block range for historical queries per chain.
+ * Prevents RPC timeouts by limiting lookback window.
+ * @param chain Chain ID
+ * @returns Maximum number of blocks to query
+ */
 export declare const determineBlockCutoff: (chain: number) => 120000 | 3456000 | 150000;
+/**
+ * Approximate block time in seconds per chain.
+ * Used to estimate time ranges from block counts.
+ * @param chain - Chain ID
+ * @returns Seconds per block
+ */
 export declare const determineSecondsPerBlock: (chain: number) => number;
+/**
+ * Get block interval for paginated historical queries per chain.
+ * Respects RPC eth_getLogs range limits.
+ * @param chain Chain ID
+ * @returns Block interval for pagination
+ */
 export declare const determineBlockSkipInternal: (chain: number) => 1000 | 8000 | 50000;
+/**
+ * Retrieve chain ID from web3 provider.
+ * Handles both initialized and uninitialized provider states.
+ * @param provider Web3 provider instance
+ * @returns Numeric chain ID
+ */
 export declare const getChainId: (provider: IContractRunner) => Promise<number>;
+/**
+ * Create ethers contract instance with address validation.
+ * @param provider Web3 provider for contract calls
+ * @param address Contract address (must be checksummed)
+ * @param abi Contract ABI (must be declared with `as const`)
+ * @returns Strongly-typed contract instance or undefined if address invalid
+ */
 export declare function createContract<const TAbi extends Abi>({ provider, address, abi, }: {
     address: string;
     provider: IContractRunner;
     abi: TAbi;
 }): TypedContract<TAbi> | undefined;
+/**
+ * Create or reuse a cached JSON-RPC provider.
+ * Passing `chainId` enables ethers' `staticNetwork` to skip the `eth_chainId`
+ * round-trip on first use.
+ *
+ * @param rpcUrl RPC endpoint URL — must be a non-empty string.
+ * @param chainId Optional chain ID — enables staticNetwork
+ * @throws Error with a clear, remediable message when `rpcUrl` is missing or
+ *   empty. Without this guard, ethers v6 silently defaults to
+ *   `http://localhost:8545` and surfaces a cryptic
+ *   `network is not available yet (NETWORK_ERROR)` on the first RPC call.
+ */
 export declare const createProvider: (rpcUrl: string, chainId?: number) => JsonRpcProvider;
+/**
+ * Create or reuse a cached Infura provider for the specified chain.
+ * @param infura Configuration with chain ID and API key
+ */
 export declare const getInfuraProvider: (infura: IInfuraOptions) => JsonRpcProvider;
 export { explorerLink } from './explorer-link';
+/**
+ * Fetch token decimals from contract or Solana mint.
+ * Results are cached to minimize RPC calls.
+ * @param provider Web3 provider
+ * @param address Token contract address or Solana mint
+ * @returns Number of decimals for the token
+ */
 export declare const getDecimals: (provider: IContractRunner, address: IAddress, isVault?: boolean) => Promise<number>;
+/**
+ * Fetch the whitelisted deposit-asset addresses from a vault's whitelist
+ * contract. Cached with a 5-minute TTL; a fresh fetch fans out into N
+ * decimals/symbol reads downstream.
+ * @internal
+ */
 export declare const getWhitelistedAssets: (provider: IContractRunner, whitelistAddress: IAddress) => Promise<IAddress[]>;
+/**
+ * Fetch receipt token address from tokenized vault contract.
+ * Results are cached to minimize RPC calls.
+ * @param provider Web3 provider
+ * @param address Tokenized vault contract address
+ * @returns Receipt token address
+ */
 export declare const getReceiptTokenAddress: (provider: IContractRunner, address: IAddress) => Promise<`0x${string}`>;
+/**
+ * Fetch token symbol from contract.
+ * Results are cached to minimize RPC calls.
+ * @param provider Web3 provider
+ * @param address Token contract address
+ * @returns Token symbol string
+ */
 export declare const getSymbol: (provider: IContractRunner, address: IAddress | undefined, isVault?: boolean) => Promise<string>;
+/**
+ * Batch fetch multiple token metadata fields in a single call.
+ * Efficiently retrieves name, symbol, decimals, and totalSupply.
+ * @param provider Web3 provider
+ * @param asset Token contract address
+ * @param meta Array of metadata fields to fetch
+ * @returns Array of metadata values in same order as requested
+ */
 export declare function getTokenMetadata(provider: IContractRunner, asset: IAddress, meta: ('symbol' | 'decimals' | 'name' | 'totalSupply')[]): Promise<any[]>;
+/**
+ * Fetch management fee percentage from vault contract.
+ * Performs static call first to check if method exists.
+ * @todo fix so that when lending pool does not have "managementFeePercent", to not break everything
+ * @param provider Web3 provider
+ * @param address Vault contract address
+ * @returns Management fee as percentage or undefined if not supported
+ */
 export declare const getManagementFeePercent: (provider: IContractRunner, address: IAddress) => Promise<number>;
+/**
+ * Simulate contract transaction without executing on-chain.
+ * Useful for testing transaction viability before sending.
+ * @param provider Web3 provider
+ * @param abi Contract ABI
+ * @param functionName Function to simulate
+ * @param options Transaction parameters including args, from, to
+ * @returns Decoded function result or false if simulation fails
+ */
 export declare function simulateTransaction(provider: IContractRunner, abi: string[] | any, functionName: string, options?: {
     args?: (string | number | bigint)[][];
     from?: string;
     to?: string;
 }): Promise<boolean | ethers.Result>;
+/**
+ * Validate Ethereum address format and checksum.
+ * @param address Address string to validate
+ * @param logger Optional logger for error messages
+ * @param type Context type for logging
+ * @returns True if address is valid and checksummed
+ */
 export declare function checkAddress(address: string, logger?: any, type?: 'wallet' | 'contract'): boolean;
 type ILoanOracleFeeCategories = 'LOAN.REPAY.INTERESTS';
+/**
+ * Fetch dynamic fee rate from on-chain oracle contract.
+ * Used for calculating loan interest repayment fees.
+ * @param provider Web3 provider
+ * @param category_id Fee category identifier
+ * @param address Context address for fee calculation
+ * @param chainId Optional chain ID (auto-detected if not provided)
+ * @returns Fee rate as decimal number
+ */
 export declare function getLoanOracleFeeRate(provider: IContractRunner, category_id: ILoanOracleFeeCategories, address: IAddress, chainId?: number): Promise<number>;
+/**
+ * Query historical contract state across a block range.
+ * Useful for reconstructing historical data like TVL over time.
+ * @param provider Web3 provider
+ * @param contractAddress Target contract address
+ * @param abi Contract ABI
+ * @param methodName View function to call
+ * @param args Function arguments
+ * @param startBlock Starting block number
+ * @param endBlock Ending block number (current block if not specified)
+ * @param blockInterval Blocks between each query
+ * @returns Array of results with block numbers and timestamps
+ */
 export declare function getHistoricalContractData(provider: IContractRunner, contractAddress: IAddress, abi: Interface | InterfaceAbi, methodName: string, args: (string | number | bigint | boolean)[], startBlock: number, endBlock: number, blockInterval?: number): Promise<any[]>;
+/**
+ * Query historical contract state at regular time intervals.
+ * Uses binary search to find blocks closest to target timestamps.
+ * @param provider Web3 provider
+ * @param contractAddress Target contract address
+ * @param abi Contract ABI
+ * @param methodName View function to call
+ * @param args Function arguments
+ * @param startDate Start date (string or timestamp)
+ * @param endDate End date (string or timestamp)
+ * @param intervalHours Hours between each query
+ * @returns Array of results with dates, blocks, and values
+ */
 export declare function getHistoricalContractDataByDate(provider: IContractRunner, contractAddress: IAddress, abi: Interface | InterfaceAbi, methodName: string, args: (string | number | bigint | boolean)[], startDate: string | number, endDate: string | number, intervalHours?: number): Promise<any[]>;

package/lib/core/helpers/web3.js

@@ -19,7 +19,25 @@ const constants_1 = require("../../adapters/solana/constants");
 const abis_1 = require("../../abis");
 const TokenizedVaultV2_1 = require("../../abis/TokenizedVaultV2");
 const TokenizedVaultV2WhitelistedAssets_1 = require("../../abis/TokenizedVaultV2WhitelistedAssets");
+//import { getVaultVersion } from './helpers.vaults';
 const vault_version_1 = require("./vault-version");
+/**
+ * Web3 Helper Utilities
+ *
+ * Core utilities for blockchain interaction:
+ * - Provider Management: createProvider, getInfuraProvider, getChainId
+ * - Contract Helpers: createContract, getDecimals, getSymbol, getTokenMetadata
+ * - Transaction Utilities: simulateTransaction, checkAddress
+ * - Historical Queries: getHistoricalContractData, getHistoricalContractDataByDate
+ * - Oracle Integration: getLoanOracleFeeRate
+ * - Block Utilities: determineBlockCutoff, determineBlockSkipInternal
+ */
+/**
+ * Get maximum block range for historical queries per chain.
+ * Prevents RPC timeouts by limiting lookback window.
+ * @param chain Chain ID
+ * @returns Maximum number of blocks to query
+ */
 const determineBlockCutoff = (chain) => {
     switch (chain) {
         case 56:
@@ -33,33 +51,51 @@ const determineBlockCutoff = (chain) => {
     }
 };
 exports.determineBlockCutoff = determineBlockCutoff;
+/**
+ * Approximate block time in seconds per chain.
+ * Used to estimate time ranges from block counts.
+ * @param chain - Chain ID
+ * @returns Seconds per block
+ */
 const determineSecondsPerBlock = (chain) => {
     switch (chain) {
-        case 143:
+        case 143: // Monad ~500ms
             return 0.5;
-        case 56:
-        case 43114:
+        case 56: // BSC ~2s
+        case 43114: // Avalanche ~2s
             return 2;
-        default:
+        default: // Ethereum ~12s
             return 12;
     }
 };
 exports.determineSecondsPerBlock = determineSecondsPerBlock;
+/**
+ * Get block interval for paginated historical queries per chain.
+ * Respects RPC eth_getLogs range limits.
+ * @param chain Chain ID
+ * @returns Block interval for pagination
+ */
 const determineBlockSkipInternal = (chain) => {
     switch (chain) {
         case 43114:
             return 8000;
         case 56:
             return 8000;
-        case 143:
+        case 143: // Monad — Alchemy limits eth_getLogs to 1000 blocks
             return 1000;
-        case 999:
+        case 999: // HyperEVM — rpc.hypurrscan.io limits eth_getLogs to 1000 blocks
             return 1000;
         default:
             return 50000;
     }
 };
 exports.determineBlockSkipInternal = determineBlockSkipInternal;
+/**
+ * Retrieve chain ID from web3 provider.
+ * Handles both initialized and uninitialized provider states.
+ * @param provider Web3 provider instance
+ * @returns Numeric chain ID
+ */
 const getChainId = async (provider) => {
     try {
         if (!provider?._network) {
@@ -74,6 +110,13 @@ const getChainId = async (provider) => {
     }
 };
 exports.getChainId = getChainId;
+/**
+ * Create ethers contract instance with address validation.
+ * @param provider Web3 provider for contract calls
+ * @param address Contract address (must be checksummed)
+ * @param abi Contract ABI (must be declared with `as const`)
+ * @returns Strongly-typed contract instance or undefined if address invalid
+ */
 function createContract({ provider, address, abi, }) {
     const goodAddress = checkAddress(address);
     if (!goodAddress)
@@ -85,6 +128,18 @@ function createContract({ provider, address, abi, }) {
     }
     return contract;
 }
+/**
+ * Create or reuse a cached JSON-RPC provider.
+ * Passing `chainId` enables ethers' `staticNetwork` to skip the `eth_chainId`
+ * round-trip on first use.
+ *
+ * @param rpcUrl RPC endpoint URL — must be a non-empty string.
+ * @param chainId Optional chain ID — enables staticNetwork
+ * @throws Error with a clear, remediable message when `rpcUrl` is missing or
+ *   empty. Without this guard, ethers v6 silently defaults to
+ *   `http://localhost:8545` and surfaces a cryptic
+ *   `network is not available yet (NETWORK_ERROR)` on the first RPC call.
+ */
 const createProvider = (rpcUrl, chainId) => {
     if (typeof rpcUrl !== 'string' || rpcUrl.trim().length === 0) {
         const forChain = chainId ? ` for chain ${chainId}` : '';
@@ -96,6 +151,7 @@ const createProvider = (rpcUrl, chainId) => {
     const cacheKey = chainId ? `${rpcUrl}|${chainId}` : rpcUrl;
     if (cache_1.CACHE.has(cacheKey))
         return cache_1.CACHE.get(cacheKey);
+    // batchMaxCount caps server-side batch limits (e.g. rpc.hypurrscan.io > 20).
     const provider = chainId
         ? new ethers_1.JsonRpcProvider(rpcUrl, ethers_1.Network.from(chainId), {
             staticNetwork: ethers_1.Network.from(chainId),
@@ -108,6 +164,10 @@ const createProvider = (rpcUrl, chainId) => {
     return provider;
 };
 exports.createProvider = createProvider;
+/**
+ * Create or reuse a cached Infura provider for the specified chain.
+ * @param infura Configuration with chain ID and API key
+ */
 const getInfuraProvider = (infura) => {
     let baseUrl = 'https://';
     switch (infura.chainId) {
@@ -138,6 +198,19 @@ const getInfuraProvider = (infura) => {
 exports.getInfuraProvider = getInfuraProvider;
 var explorer_link_1 = require("./explorer-link");
 Object.defineProperty(exports, "explorerLink", { enumerable: true, get: function () { return explorer_link_1.explorerLink; } });
+/**
+ * Stable per-provider identity for cache keys — prevents cross-chain collisions
+ * when the same address represents different tokens on different networks.
+ *
+ * `provider._network` is a *getter* in ethers v6 that throws
+ * `network is not available yet (NETWORK_ERROR)` until the provider has
+ * resolved its network (i.e. before its first successful request, when
+ * `staticNetwork` was not supplied at construction). Accessing it directly
+ * here used to leak that error out of every cached read (`getDecimals`,
+ * `getReceiptTokenAddress`, …) and surface as a confusing TVL failure on
+ * fresh provider instances. We swallow the throw and fall back to the
+ * connection URL — slightly less precise as a cache key but always safe.
+ */
 function providerScope(provider) {
     let chainId;
     try {
@@ -146,6 +219,7 @@ function providerScope(provider) {
         chainId = net?.chainId;
     }
     catch {
+        // ethers v6 throws when the lazy network hasn't been detected yet.
         chainId = undefined;
     }
     if (chainId !== undefined && chainId !== null) {
@@ -156,7 +230,15 @@ function providerScope(provider) {
         return `url:${conn.url}`;
     return 'unknown';
 }
+/** @internal */
 const DECIMALS_REQUESTS = new Map();
+/**
+ * Fetch token decimals from contract or Solana mint.
+ * Results are cached to minimize RPC calls.
+ * @param provider Web3 provider
+ * @param address Token contract address or Solana mint
+ * @returns Number of decimals for the token
+ */
 const getDecimals = async (provider, address, isVault = true) => {
     if (address === ethers_1.ZeroAddress) {
         logger_1.Logger.log.info('getDecimals', 'address is zero address');
@@ -205,7 +287,14 @@ const getDecimals = async (provider, address, isVault = true) => {
     return fetchPromise;
 };
 exports.getDecimals = getDecimals;
+/** @internal */
 const WHITELISTED_ASSETS_REQUESTS = new Map();
+/**
+ * Fetch the whitelisted deposit-asset addresses from a vault's whitelist
+ * contract. Cached with a 5-minute TTL; a fresh fetch fans out into N
+ * decimals/symbol reads downstream.
+ * @internal
+ */
 const getWhitelistedAssets = async (provider, whitelistAddress) => {
     if (!(whitelistAddress && provider)) {
         throw new errors_1.AugustValidationError('INVALID_INPUT', 'getWhitelistedAssets: provider and whitelistAddress are required');
@@ -231,7 +320,15 @@ const getWhitelistedAssets = async (provider, whitelistAddress) => {
     return fetchPromise;
 };
 exports.getWhitelistedAssets = getWhitelistedAssets;
+/** @internal */
 const RECEIPT_TOKEN_REQUESTS = new Map();
+/**
+ * Fetch receipt token address from tokenized vault contract.
+ * Results are cached to minimize RPC calls.
+ * @param provider Web3 provider
+ * @param address Tokenized vault contract address
+ * @returns Receipt token address
+ */
 const getReceiptTokenAddress = async (provider, address) => {
     if (!(address && provider))
         return;
@@ -260,7 +357,15 @@ const getReceiptTokenAddress = async (provider, address) => {
     return fetchPromise;
 };
 exports.getReceiptTokenAddress = getReceiptTokenAddress;
+/** @internal */
 const SYMBOL_REQUESTS = new Map();
+/**
+ * Fetch token symbol from contract.
+ * Results are cached to minimize RPC calls.
+ * @param provider Web3 provider
+ * @param address Token contract address
+ * @returns Token symbol string
+ */
 const getSymbol = async (provider, address, isVault = true) => {
     if (address === ethers_1.ZeroAddress) {
         logger_1.Logger.log.info('getSymbol', 'address is zero address');
@@ -307,6 +412,14 @@ const getSymbol = async (provider, address, isVault = true) => {
     return fetchPromise;
 };
 exports.getSymbol = getSymbol;
+/**
+ * Batch fetch multiple token metadata fields in a single call.
+ * Efficiently retrieves name, symbol, decimals, and totalSupply.
+ * @param provider Web3 provider
+ * @param asset Token contract address
+ * @param meta Array of metadata fields to fetch
+ * @returns Array of metadata values in same order as requested
+ */
 async function getTokenMetadata(provider, asset, meta) {
     if (!asset)
         return [];
@@ -340,9 +453,18 @@ async function getTokenMetadata(provider, asset, meta) {
         return [];
     }
 }
+/**
+ * Fetch management fee percentage from vault contract.
+ * Performs static call first to check if method exists.
+ * @todo fix so that when lending pool does not have "managementFeePercent", to not break everything
+ * @param provider Web3 provider
+ * @param address Vault contract address
+ * @returns Management fee as percentage or undefined if not supported
+ */
 const getManagementFeePercent = async (provider, address) => {
     if (!(address && provider))
         return;
+    // Check if contract supports managementFeePercent method
     try {
         const contract = new ethers_1.Contract(address, [web3_1.MIN_ABIS.managementFeePercent], provider);
         await contract.managementFeePercent.staticCall();
@@ -362,6 +484,15 @@ const getManagementFeePercent = async (provider, address) => {
     }
 };
 exports.getManagementFeePercent = getManagementFeePercent;
+/**
+ * Simulate contract transaction without executing on-chain.
+ * Useful for testing transaction viability before sending.
+ * @param provider Web3 provider
+ * @param abi Contract ABI
+ * @param functionName Function to simulate
+ * @param options Transaction parameters including args, from, to
+ * @returns Decoded function result or false if simulation fails
+ */
 async function simulateTransaction(provider, abi, functionName, options) {
     try {
         const customInterface = new ethers_1.Interface(abi);
@@ -382,6 +513,13 @@ async function simulateTransaction(provider, abi, functionName, options) {
         return false;
     }
 }
+/**
+ * Validate Ethereum address format and checksum.
+ * @param address Address string to validate
+ * @param logger Optional logger for error messages
+ * @param type Context type for logging
+ * @returns True if address is valid and checksummed
+ */
 function checkAddress(address, logger, type = 'contract') {
     const _logger = logger ?? console;
     if (!address) {
@@ -398,6 +536,15 @@ function checkAddress(address, logger, type = 'contract') {
     }
     return true;
 }
+/**
+ * Fetch dynamic fee rate from on-chain oracle contract.
+ * Used for calculating loan interest repayment fees.
+ * @param provider Web3 provider
+ * @param category_id Fee category identifier
+ * @param address Context address for fee calculation
+ * @param chainId Optional chain ID (auto-detected if not provided)
+ * @returns Fee rate as decimal number
+ */
 async function getLoanOracleFeeRate(provider, category_id, address, chainId) {
     if (!(0, ethers_1.isAddress)(address)) {
         logger_1.Logger.log.error('getLoanOracleFee', 'address is undefined or not a valid address');
@@ -421,6 +568,19 @@ async function getLoanOracleFeeRate(provider, category_id, address, chainId) {
     const rawFee = await oracleContract.getContextFeeRate(hashedCategory, (0, ethers_1.getAddress)(address));
     return Number((0, ethers_1.formatUnits)(rawFee, 6));
 }
+/**
+ * Query historical contract state across a block range.
+ * Useful for reconstructing historical data like TVL over time.
+ * @param provider Web3 provider
+ * @param contractAddress Target contract address
+ * @param abi Contract ABI
+ * @param methodName View function to call
+ * @param args Function arguments
+ * @param startBlock Starting block number
+ * @param endBlock Ending block number (current block if not specified)
+ * @param blockInterval Blocks between each query
+ * @returns Array of results with block numbers and timestamps
+ */
 async function getHistoricalContractData(provider, contractAddress, abi, methodName, args = [], startBlock, endBlock, blockInterval = 1000) {
     const contract = new ethers_1.ethers.Contract(contractAddress, abi, provider);
     const results = [];
@@ -446,12 +606,26 @@ async function getHistoricalContractData(provider, contractAddress, abi, methodN
     }
     return results;
 }
+/**
+ * Query historical contract state at regular time intervals.
+ * Uses binary search to find blocks closest to target timestamps.
+ * @param provider Web3 provider
+ * @param contractAddress Target contract address
+ * @param abi Contract ABI
+ * @param methodName View function to call
+ * @param args Function arguments
+ * @param startDate Start date (string or timestamp)
+ * @param endDate End date (string or timestamp)
+ * @param intervalHours Hours between each query
+ * @returns Array of results with dates, blocks, and values
+ */
 async function getHistoricalContractDataByDate(provider, contractAddress, abi, methodName, args = [], startDate, endDate, intervalHours = 24) {
     const contract = new ethers_1.ethers.Contract(contractAddress, abi, provider);
     const startTimestamp = Math.floor(new Date(startDate).getTime() / 1000);
     const endTimestamp = Math.floor(new Date(endDate).getTime() / 1000);
     const intervalSeconds = intervalHours * 3600;
     const results = [];
+    // Binary search to find block closest to timestamp
     async function findBlockByTimestamp(targetTimestamp) {
         let left = 1;
         let right = await provider.getBlockNumber();
@@ -481,12 +655,15 @@ async function getHistoricalContractDataByDate(provider, contractAddress, abi, m
         return closestBlock;
     }
     try {
+        // Loop through time intervals
         for (let timestamp = startTimestamp; timestamp <= endTimestamp; timestamp += intervalSeconds) {
+            // Find closest block to timestamp
             const block = await findBlockByTimestamp(timestamp);
             if (!block) {
                 logger_1.Logger.log.warn('getHistoricalContractDataByDate', `No block found for timestamp ${timestamp}`);
                 continue;
             }
+            // Make the contract call
             const result = await contract[methodName](...args, {
                 blockTag: block.number,
             });

package/lib/core/logger/index.d.ts

@@ -1,17 +1,63 @@
+/**
+ * Sentry-compatible logger shape — `@sentry/browser` can be passed directly.
+ */
 export type SDKLogger = {
     setTag: (key: string, value: string) => void;
     captureException: (err: unknown, context?: Record<string, any>) => void;
 };
+/**
+ * Minimal breadcrumb shape forwarded to the internal Sentry sink. Mirrors the
+ * subset of Sentry's `Breadcrumb` the SDK populates, kept local so the logger
+ * stays decoupled from `@sentry/*` — and, more importantly, so it never has to
+ * import the analytics layer (which imports the logger, and would otherwise
+ * form a cycle; see CLAUDE.md §9).
+ *
+ * @internal
+ */
 export interface SDKBreadcrumb {
+    /** Breadcrumb grouping key. Always `'sdk.logger'` for logger-sourced crumbs. */
     category: string;
+    /** Short, low-cardinality label — the call-site tag passed to `Logger.log.*`. */
     message: string;
+    /** Severity. Logger warnings map to `'warning'`. */
     level: 'info' | 'warning' | 'error';
+    /** Already-sanitized structured context. */
     data?: Record<string, unknown>;
 }
+/**
+ * The SDK's own always-on Sentry sink, wired by `initializeSentry` when
+ * analytics is enabled and cleared by `resetAnalytics`. This is deliberately
+ * distinct from the integrator-pluggable {@link SDKLogger} / {@link ILogger}
+ * slots: those belong to the consuming application, this one is the SDK's
+ * internal bridge so its diagnostics reach the partner-usage dashboard without
+ * the integrator having to wire anything.
+ *
+ * Severity policy (implemented in `analytics/sentry.ts`): `error` is captured
+ * as a Sentry issue via `captureException`; `warn` becomes a breadcrumb that
+ * rides along with the next captured event. `info` is intentionally not
+ * forwarded — method-call breadcrumbs from `instrumentClass` already cover the
+ * happy path, and forwarding every info line would only add noise/cost.
+ *
+ * @internal
+ */
 export interface SDKSentrySink {
+    /** Forward a (pre-sanitized) error to Sentry as an issue. */
     captureException: (error: unknown, context?: Record<string, unknown>) => void;
+    /** Forward a (pre-sanitized) breadcrumb to the active Sentry scope. */
     addBreadcrumb: (breadcrumb: SDKBreadcrumb) => void;
 }
+/**
+ * Structured logger interface (debug/info/warn/error). Sanitization runs
+ * before any method here is invoked, so implementations needn't scrub secrets.
+ *
+ * ```ts
+ * Logger.setStructuredLogger({
+ *   info:  (tag, ctx) => pino.info({ tag, ...ctx }),
+ *   warn:  (tag, ctx) => pino.warn({ tag, ...ctx }),
+ *   error: (tag, err, ctx) => pino.error({ tag, err, ...ctx }),
+ * });
+ * ```
+ */
 export interface ILogger {
     debug?: (tag: string, context?: Record<string, unknown>) => void;
     info?: (tag: string, context?: Record<string, unknown>) => void;
@@ -19,9 +65,18 @@ export interface ILogger {
     error: (tag: string, error: unknown, context?: Record<string, unknown>) => void;
 }
 declare function setLogger(customLogger: SDKLogger): void;
+/** Plug in an `ILogger`. Independent of `setLogger`; pass `null` to clear. */
 declare function setStructuredLogger(custom: ILogger | null): void;
 declare function getLogger(): SDKLogger | null;
 declare function getStructuredLogger(): ILogger | null;
+/**
+ * Wire (or clear, with `null`) the SDK's internal Sentry sink. Called by
+ * `initializeSentry` after a successful Sentry init, and reset by
+ * `resetAnalytics`. Not part of the integrator-facing API — applications wire
+ * their own logging through {@link setLogger} / {@link setStructuredLogger}.
+ *
+ * @internal
+ */
 declare function setSentrySink(sink: SDKSentrySink | null): void;
 declare function setDevMode(devMode: boolean): void;
 declare function isDevMode(): boolean;

package/lib/core/logger/index.js

@@ -42,6 +42,7 @@ let isDev = false;
 function setLogger(customLogger) {
     logger = customLogger;
 }
+/** Plug in an `ILogger`. Independent of `setLogger`; pass `null` to clear. */
 function setStructuredLogger(custom) {
     structuredLogger = custom;
 }
@@ -51,6 +52,14 @@ function getLogger() {
 function getStructuredLogger() {
     return structuredLogger;
 }
+/**
+ * Wire (or clear, with `null`) the SDK's internal Sentry sink. Called by
+ * `initializeSentry` after a successful Sentry init, and reset by
+ * `resetAnalytics`. Not part of the integrator-facing API — applications wire
+ * their own logging through {@link setLogger} / {@link setStructuredLogger}.
+ *
+ * @internal
+ */
 function setSentrySink(sink) {
     sentrySink = sink;
 }
@@ -60,6 +69,7 @@ function setDevMode(devMode) {
 function isDevMode() {
     return isDev;
 }
+/** Internal logger: DEV mode → console; production → SDKLogger. Sanitized either way. */
 const log = {
     info: (tag, ...args) => {
         const safeArgs = args.map((a) => (0, sanitize_1.sanitizeForLogging)(a));
@@ -75,6 +85,9 @@ const log = {
         }
         logger?.setTag('warning', tag);
         structuredLogger?.warn?.(tag, structuredContext(safeArgs));
+        // Warnings ride along as breadcrumbs on the next captured event rather
+        // than becoming standalone issues — keeps Sentry volume bounded (see the
+        // severity policy on SDKSentrySink).
         sentrySink?.addBreadcrumb({
             category: 'sdk.logger',
             level: 'warning',
@@ -92,9 +105,15 @@ const log = {
         }
         logger?.captureException(safeError, { tag, ...safeContext });
         structuredLogger?.error(tag, safeError, safeContext);
+        // The SDK's own bridge to Sentry: errors become issues. `safeError` /
+        // `safeContext` are already sanitized above, so the sink forwards as-is.
         sentrySink?.captureException(safeError, { tag, ...safeContext });
     },
 };
+/**
+ * Pino-friendly shape: if the first arg is a plain object, pass it through
+ * (with subsequent args as `extras`); otherwise wrap as `{ args }`.
+ */
 function structuredContext(args) {
     if (args.length === 0)
         return undefined;