@augustdigital/sdk 8.3.1 → 8.5.0

package/lib/adapters/stellar/index.js

@@ -1,4 +1,12 @@
 "use strict";
+/**
+ * Stellar Adapter for August SDK
+ *
+ * Provides Stellar vault operations: deposit, redeem, position queries,
+ * and on-chain data fetching via Soroban RPC.
+ *
+ * @module StellarAdapter
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -46,6 +54,20 @@ exports.Stellar = {
     submit: StellarSubmit,
     getters: StellarGetters,
 };
+/**
+ * Stellar Adapter for August SDK
+ *
+ * @example
+ * ```
+ * const adapter = new StellarAdapter('testnet');
+ * const xdr = await adapter.vaultDeposit({
+ *   contractId: 'CBGWW5...',
+ *   amount: '1000000',
+ *   senderAddress: 'GDLZ...',
+ * });
+ * // Sign xdr with wallet (e.g. Freighter), then submit via adapter.submitTransaction()
+ * ```
+ */
 class StellarAdapter {
     constructor(network = 'mainnet') {
         this._network = network;
@@ -59,24 +81,50 @@ class StellarAdapter {
     getExplorerLink(id, type) {
         return utils_1.StellarUtils.getExplorerLink({ id, type, network: this._network });
     }
+    /**
+     * Build an unsigned deposit transaction for a Stellar vault.
+     * @returns Base64-encoded XDR of the unsigned transaction.
+     */
     async vaultDeposit(params) {
         return StellarActions.handleStellarDeposit({
             ...params,
             network: this._network,
         });
     }
+    /**
+     * Build an unsigned redeem transaction for a Stellar vault.
+     * @returns Base64-encoded XDR of the unsigned transaction.
+     */
     async vaultRedeem(params) {
         return StellarActions.handleStellarRedeem({
             ...params,
             network: this._network,
         });
     }
+    /**
+     * Submit a signed Soroban transaction and poll until confirmed.
+     * @returns Transaction hash on success
+     */
     async submitTransaction(signedXdr) {
         return StellarSubmit.submitStellarTransaction(signedXdr, this._network);
     }
+    /**
+     * Get user's vault share balance.
+     *
+     * @returns The position `{ shares, decimals, decimalsFromFallback }`, or null
+     * if the balance read fails. When `decimalsFromFallback` is `true` the
+     * `decimals()` read failed and `decimals` is the fallback (7) — callers sizing
+     * a redeem MUST refuse rather than trust it (see AUGUST-6381).
+     */
     async getUserPosition(vaultAddress, walletAddress) {
         return StellarGetters.getStellarUserPosition(vaultAddress, walletAddress, this._network);
     }
+    /**
+     * Preview how many vault shares a deposit amount would yield.
+     * @param vaultAddress  Stellar contract ID (C… address)
+     * @param rawAmount     Deposit amount in the deposit token's smallest unit
+     * @returns Raw share amount as a string, or null if query fails.
+     */
     async convertToShares(vaultAddress, rawAmount) {
         return StellarGetters.convertToShares(vaultAddress, rawAmount, this._network);
     }

package/lib/adapters/stellar/soroban.d.ts

@@ -1,11 +1,31 @@
+/**
+ * Shared Soroban RPC utilities
+ *
+ * Common transaction building and read-only query helpers used by
+ * actions, submit, and getters modules.
+ */
 import { xdr, rpc } from '@stellar/stellar-sdk';
 import type { IStellarNetwork } from './types';
+/** Resolved network configuration for Soroban RPC calls. */
 export interface ISorobanNetworkConfig {
     rpcUrl: string;
     passphrase: string;
 }
 export declare function createServer(rpcUrl: string): rpc.Server;
+/**
+ * Resolve RPC URL and network passphrase for a Stellar network.
+ */
 export declare function resolveNetworkConfig(network: IStellarNetwork): ISorobanNetworkConfig;
+/**
+ * Validate and convert a string amount to a non-negative BigInt.
+ * Throws a descriptive error if the value is not a valid non-negative integer string.
+ */
 export declare function toBigIntAmount(value: string, label: string): bigint;
 export declare function queryContract(config: ISorobanNetworkConfig, contractId: string, method: string, args?: xdr.ScVal[]): Promise<xdr.ScVal | null>;
+/**
+ * Build an unsigned Soroban contract invocation transaction.
+ * Fetches the real source account from the network (the account must exist and be funded).
+ * Simulates via Soroban RPC to attach resource footprint and auth entries,
+ * using MAX_FEE_STROOPS as the fee ceiling and incorporating the simulated resource fee.
+ */
 export declare function buildSorobanTx(config: ISorobanNetworkConfig, sourceAddress: string, contractId: string, method: string, args: xdr.ScVal[]): Promise<string>;

package/lib/adapters/stellar/soroban.js

@@ -1,4 +1,10 @@
 "use strict";
+/**
+ * Shared Soroban RPC utilities
+ *
+ * Common transaction building and read-only query helpers used by
+ * actions, submit, and getters modules.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createServer = createServer;
 exports.resolveNetworkConfig = resolveNetworkConfig;
@@ -13,12 +19,19 @@ function createServer(rpcUrl) {
         allowHttp: rpcUrl.startsWith('http://'),
     });
 }
+/**
+ * Resolve RPC URL and network passphrase for a Stellar network.
+ */
 function resolveNetworkConfig(network) {
     return {
         rpcUrl: constants_1.SOROBAN_RPC_URLS[network],
         passphrase: constants_1.NETWORK_PASSPHRASES[network],
     };
 }
+/**
+ * Validate and convert a string amount to a non-negative BigInt.
+ * Throws a descriptive error if the value is not a valid non-negative integer string.
+ */
 function toBigIntAmount(value, label) {
     if (value === '') {
         throw new core_1.AugustValidationError('INVALID_INPUT', `Invalid ${label}: value must not be empty`);
@@ -35,6 +48,11 @@ function toBigIntAmount(value, label) {
     }
     return result;
 }
+/**
+ * Query a read-only Soroban contract function via simulation.
+ * Uses a throwaway source account — simulation is off-chain and has no on-chain side effects.
+ * Returns the ScVal result, or null if the call fails.
+ */
 function extractSimulationError(simulated) {
     return 'error' in simulated
         ? String(simulated.error)
@@ -46,6 +64,8 @@ async function queryContract(config, contractId, method, args = []) {
         const contract = new stellar_sdk_1.Contract(contractId);
         const sourceKeypair = stellar_sdk_1.Keypair.random();
         const account = new stellar_sdk_1.Account(sourceKeypair.publicKey(), '0');
+        // Minimal fee — simulation is off-chain; these values don't affect execution cost.
+        // Short timeout to avoid blocking vault listing if Soroban RPC is slow.
         const tx = new stellar_sdk_1.TransactionBuilder(account, {
             fee: '100',
             networkPassphrase: config.passphrase,
@@ -76,9 +96,22 @@ async function queryContract(config, contractId, method, args = []) {
         return null;
     }
 }
+/**
+ * Read the network's wall-clock time (unix seconds) from the latest closed
+ * ledger, or null if the RPC can't report it.
+ *
+ * Soroban validators reject a transaction whose `maxTime` precedes the ledger
+ * close time (`txTOO_LATE`). Anchoring `maxTime` to the *network* clock instead
+ * of the signer's `Date.now()` immunises the deadline against a skewed device
+ * clock — a machine lagging behind real time was silently building
+ * already-expired transactions. Best-effort: on any RPC failure the caller
+ * falls back to the local clock, so this never regresses the prior behaviour.
+ */
 async function getNetworkCloseTime(server) {
     try {
         const { sequence } = await server.getLatestLedger();
+        // `latestLedgerCloseTime` on the response envelope is the freshest network
+        // time; the single-ledger page is just the cheapest valid request shape.
         const page = await server.getLedgers({
             startLedger: sequence,
             pagination: { limit: 1 },
@@ -92,14 +125,25 @@ async function getNetworkCloseTime(server) {
         return null;
     }
 }
+/**
+ * Build an unsigned Soroban contract invocation transaction.
+ * Fetches the real source account from the network (the account must exist and be funded).
+ * Simulates via Soroban RPC to attach resource footprint and auth entries,
+ * using MAX_FEE_STROOPS as the fee ceiling and incorporating the simulated resource fee.
+ */
 async function buildSorobanTx(config, sourceAddress, contractId, method, args) {
     const server = createServer(config.rpcUrl);
+    // Read the network clock in parallel with the account fetch — it overlaps the
+    // account round-trip, so it adds no latency on the happy path.
     const networkCloseTimePromise = getNetworkCloseTime(server);
     let account;
     try {
         account = await server.getAccount(sourceAddress);
     }
     catch (err) {
+        // Soroban rpc currently throws plain `Error("Account not found: ...")`
+        // for unfunded accounts; check `NotFoundError` too so this survives an
+        // SDK refactor to typed errors.
         const msg = err instanceof Error ? err.message : String(err);
         const isAccountNotFound = err instanceof stellar_sdk_1.NotFoundError || /Account not found/.test(msg);
         if (isAccountNotFound) {
@@ -114,9 +158,11 @@ async function buildSorobanTx(config, sourceAddress, contractId, method, args) {
     }).addOperation(contract.call(method, ...args));
     const networkCloseTime = await networkCloseTimePromise;
     if (networkCloseTime !== null) {
+        // Absolute deadline anchored to the network clock — survives signer skew.
         builder.setTimebounds(0, networkCloseTime + constants_1.TX_TIMEOUT_SECONDS);
     }
     else {
+        // RPC couldn't report network time; fall back to the local-clock window.
         builder.setTimeout(constants_1.TX_TIMEOUT_SECONDS);
     }
     const tx = builder.build();

package/lib/adapters/stellar/submit.d.ts

@@ -1,2 +1,14 @@
+/**
+ * Stellar Transaction Submission
+ *
+ * Submits signed Soroban transactions and polls for confirmation.
+ */
 import type { IStellarNetwork } from './types';
+/**
+ * Submit a signed Soroban transaction and poll until confirmed.
+ *
+ * @param signedXdr Base64-encoded XDR of the signed transaction
+ * @param network Stellar network name
+ * @returns Transaction hash on success
+ */
 export declare function submitStellarTransaction(signedXdr: string, network: IStellarNetwork): Promise<string>;

package/lib/adapters/stellar/submit.js

@@ -1,10 +1,22 @@
 "use strict";
+/**
+ * Stellar Transaction Submission
+ *
+ * Submits signed Soroban transactions and polls for confirmation.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.submitStellarTransaction = submitStellarTransaction;
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const core_1 = require("../../core");
 const soroban_1 = require("./soroban");
 const constants_1 = require("./constants");
+/**
+ * Submit a signed Soroban transaction and poll until confirmed.
+ *
+ * @param signedXdr Base64-encoded XDR of the signed transaction
+ * @param network Stellar network name
+ * @returns Transaction hash on success
+ */
 async function submitStellarTransaction(signedXdr, network) {
     const { rpcUrl, passphrase } = (0, soroban_1.resolveNetworkConfig)(network);
     const server = (0, soroban_1.createServer)(rpcUrl);
@@ -18,6 +30,11 @@ async function submitStellarTransaction(signedXdr, network) {
             context: { network, status: sendResult.status },
         });
     }
+    // Only PENDING (and DUPLICATE) mean the tx was accepted by the RPC.
+    // DUPLICATE means this exact transaction was already submitted — it may
+    // already be confirmed or still pending from a prior submission.
+    // TRY_AGAIN_LATER and any other status should be surfaced immediately
+    // so callers can retry submission instead of waiting for a poll timeout.
     if (sendResult.status !== 'PENDING' && sendResult.status !== 'DUPLICATE') {
         const msg = `Transaction not accepted by RPC (status: ${sendResult.status}). ` +
             'This may be retryable — the RPC node could be overloaded.';
@@ -26,6 +43,8 @@ async function submitStellarTransaction(signedXdr, network) {
             context: { network, status: sendResult.status },
         });
     }
+    // Geometric backoff (start POLL_INTERVAL_MS, ×POLL_INTERVAL_BACKOFF up to
+    // POLL_INTERVAL_MAX_MS) — fast on the happy path, gentler on slow ledgers.
     let getResult = await server.getTransaction(sendResult.hash);
     let polls = 0;
     let nextDelay = constants_1.POLL_INTERVAL_MS;

package/lib/adapters/stellar/types.d.ts

@@ -1,19 +1,46 @@
+/**
+ * Stellar Vault Types
+ */
 import type { IStellarNetwork } from '../../types/web3';
 export type { IStellarNetwork };
+/** Parameters for building an unsigned Stellar vault deposit transaction. */
 export interface IStellarDepositParams {
     contractId: string;
     amount: string;
     senderAddress: string;
     network: IStellarNetwork;
 }
+/** Parameters for building an unsigned Stellar vault redeem transaction. */
 export interface IStellarRedeemParams {
     contractId: string;
     shares: string;
     receiverAddress: string;
     network: IStellarNetwork;
 }
+/**
+ * User vault position returned by on-chain balance queries.
+ *
+ * `decimals` carries the share-token scale used to interpret `shares`. When the
+ * on-chain `decimals()` read fails, it falls back to STELLAR_FALLBACK_DECIMALS
+ * (7) and `decimalsFromFallback` is set to `true`. Callers that size a redeem
+ * from this position MUST check `decimalsFromFallback` and refuse to settle
+ * when it is `true` — trusting a fabricated 7 against an ERC4626 offset vault
+ * (share decimals = asset + offset) under-redeems by `10^offset`. See
+ * AUGUST-6381.
+ */
 export interface IStellarUserPosition {
+    /** Raw share balance in smallest unit, as a non-negative integer string */
     shares: string;
+    /** Share-token decimals; may be the fallback — see `decimalsFromFallback`. */
     decimals: number;
+    /**
+     * `true` when `decimals` is the fallback (the on-chain `decimals()` read
+     * failed), `false` when it is the authoritative on-chain value. Treat `true`
+     * as a decimals read failure: do not trust `decimals` to scale or redeem.
+     *
+     * Optional for source back-compat (a consumer's existing object literal still
+     * compiles), but `getStellarUserPosition` always populates it — so a position
+     * obtained from the SDK never omits it.
+     */
     decimalsFromFallback?: boolean;
 }

package/lib/adapters/stellar/types.js

@@ -1,3 +1,6 @@
 "use strict";
+/**
+ * Stellar Vault Types
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 //# sourceMappingURL=types.js.map

package/lib/adapters/stellar/utils.d.ts

@@ -1,11 +1,21 @@
+/**
+ * Stellar Utilities
+ */
 import type { IStellarNetwork } from './types';
 import { isStellarAddress } from '../../core/helpers/chain-address';
 export { isStellarAddress };
+/**
+ * Get the Stellar explorer URL for a given address or transaction.
+ */
 export declare function getExplorerLink({ id, type, network, }: {
     id: string;
     type?: 'contract' | 'account' | 'tx';
     network?: IStellarNetwork;
 }): string;
+/**
+ * Throw if the given address is a Stellar address.
+ * Used as a guard in vault operations that don't yet support Stellar.
+ */
 export declare function assertNotStellar(address: string, operation: string): void;
 export declare const StellarUtils: {
     isStellarAddress: typeof isStellarAddress;

package/lib/adapters/stellar/utils.js

@@ -1,4 +1,7 @@
 "use strict";
+/**
+ * Stellar Utilities
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StellarUtils = exports.isStellarAddress = void 0;
 exports.getExplorerLink = getExplorerLink;
@@ -6,11 +9,18 @@ exports.assertNotStellar = assertNotStellar;
 const core_1 = require("../../core");
 const chain_address_1 = require("../../core/helpers/chain-address");
 Object.defineProperty(exports, "isStellarAddress", { enumerable: true, get: function () { return chain_address_1.isStellarAddress; } });
+/**
+ * Get the Stellar explorer URL for a given address or transaction.
+ */
 function getExplorerLink({ id, type = 'contract', network = 'mainnet', }) {
     const baseUrl = 'https://stellar.expert/explorer';
     const net = network === 'mainnet' ? 'public' : 'testnet';
     return `${baseUrl}/${net}/${type}/${id}`;
 }
+/**
+ * Throw if the given address is a Stellar address.
+ * Used as a guard in vault operations that don't yet support Stellar.
+ */
 function assertNotStellar(address, operation) {
     if ((0, chain_address_1.isStellarAddress)(address)) {
         throw new core_1.AugustValidationError('INVALID_CHAIN', `${operation} is not yet supported for Stellar vaults: ${address}`);

package/lib/adapters/sui/getters.d.ts

@@ -1,3 +1,9 @@
 import { IEmberVault, IFetchEmberVaultsOptions } from './types';
+/**
+ * Fetch Ember vaults from API
+ */
 export declare function getEmberVaults(options?: IFetchEmberVaultsOptions): Promise<IEmberVault[]>;
+/**
+ * Fetch Ember TVL data
+ */
 export declare function getEmberTVL(limit?: number): Promise<number>;

package/lib/adapters/sui/getters.js

@@ -5,6 +5,9 @@ exports.getEmberTVL = getEmberTVL;
 const constants_1 = require("./constants");
 const core_1 = require("../../core");
 const logger_1 = require("../../core/logger");
+/**
+ * Fetch Ember vaults from API
+ */
 async function getEmberVaults(options) {
     try {
         const params = new URLSearchParams();
@@ -28,6 +31,9 @@ async function getEmberVaults(options) {
         return [];
     }
 }
+/**
+ * Fetch Ember TVL data
+ */
 async function getEmberTVL(limit = 1) {
     try {
         const params = new URLSearchParams();

package/lib/adapters/sui/index.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Sui Adapter for August SDK
+ *
+ * @module SuiAdapter
+ */
 import * as SuiConstants from './constants';
 import * as SuiGetters from './getters';
 import * as SuiUtils from './utils';
@@ -12,6 +17,16 @@ export declare const Sui: {
         transformEmberVaultsToIVaults: typeof transformEmberVaultsToIVaults;
     };
 };
+/**
+ * Sui Adapter for August SDK
+ *
+ * @example
+ * To access the Sui adapter instance
+ * ```
+ * const sdk = new AugustSDK()
+ * sdk.sui.getEmberVaults()
+ * ```
+ */
 declare class SuiAdapter {
     private _apiBaseUrl;
     private _chainId;

package/lib/adapters/sui/index.js

@@ -34,6 +34,11 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Sui = void 0;
+/**
+ * Sui Adapter for August SDK
+ *
+ * @module SuiAdapter
+ */
 const SuiConstants = __importStar(require("./constants"));
 const SuiGetters = __importStar(require("./getters"));
 const SuiUtils = __importStar(require("./utils"));
@@ -44,6 +49,16 @@ exports.Sui = {
     getters: SuiGetters,
     transformer: { transformEmberVaultToIVault: transformer_1.transformEmberVaultToIVault, transformEmberVaultsToIVaults: transformer_1.transformEmberVaultsToIVaults },
 };
+/**
+ * Sui Adapter for August SDK
+ *
+ * @example
+ * To access the Sui adapter instance
+ * ```
+ * const sdk = new AugustSDK()
+ * sdk.sui.getEmberVaults()
+ * ```
+ */
 class SuiAdapter {
     constructor(apiBaseUrl = SuiConstants.EMBER_API_BASE_URL, chainId = SuiConstants.SUI_CHAIN_ID) {
         this._apiBaseUrl = apiBaseUrl;

package/lib/adapters/sui/transformer.d.ts

@@ -1,4 +1,10 @@
 import { IVault } from '../../types';
 import { IEmberVault } from './types';
+/**
+ * Transform Ember vault to IVault format
+ */
 export declare function transformEmberVaultToIVault(emberVault: IEmberVault): IVault;
+/**
+ * Transform multiple Ember vaults
+ */
 export declare function transformEmberVaultsToIVaults(emberVaults: IEmberVault[]): IVault[];

package/lib/adapters/sui/transformer.js

@@ -5,6 +5,9 @@ exports.transformEmberVaultsToIVaults = transformEmberVaultsToIVaults;
 const core_1 = require("../../core");
 const constants_1 = require("./constants");
 const utils_1 = require("./utils");
+/**
+ * Transform Ember vault to IVault format
+ */
 function transformEmberVaultToIVault(emberVault) {
     const depositTokenDecimals = emberVault.depositCoin?.decimals || constants_1.EMBER_DEFAULTS.DECIMALS;
     const receiptTokenDecimals = emberVault.receiptCoin?.decimals || constants_1.EMBER_DEFAULTS.DECIMALS;
@@ -38,6 +41,7 @@ function transformEmberVaultToIVault(emberVault) {
                 ? 'Gamma Research'
                 : manager?.name || 'Unknown',
             type: 'subaccount',
+            website_url: null,
         })),
         fees: {
             performance: (0, utils_1.convertFromE9)(emberVault.weeklyPerformanceFeeBpsE9 || 0) /
@@ -93,6 +97,9 @@ function transformEmberVaultToIVault(emberVault) {
     };
     return returnObj;
 }
+/**
+ * Transform multiple Ember vaults
+ */
 function transformEmberVaultsToIVaults(emberVaults) {
     return emberVaults.map(transformEmberVaultToIVault);
 }

package/lib/adapters/sui/utils.d.ts

@@ -1,4 +1,10 @@
+/**
+ * Convert E9 format to regular number
+ */
 export declare function convertFromE9(value: string | number): number;
+/**
+ * Calculate capacity utilization percentage
+ */
 export declare function calculateUtilization(current: string | number, maximum: string | number): number;
 export { isSuiAddress } from '../../core/helpers/chain-address';
 export declare function isSuiVault(chainId: number): boolean;

package/lib/adapters/sui/utils.js

@@ -5,9 +5,15 @@ exports.convertFromE9 = convertFromE9;
 exports.calculateUtilization = calculateUtilization;
 exports.isSuiVault = isSuiVault;
 const constants_1 = require("./constants");
+/**
+ * Convert E9 format to regular number
+ */
 function convertFromE9(value) {
     return Number(value) / constants_1.EMBER_DEFAULTS.E9_DIVISOR;
 }
+/**
+ * Calculate capacity utilization percentage
+ */
 function calculateUtilization(current, maximum) {
     const currentValue = Number(current) || 0;
     const maxValue = Number(maximum) || 0;

package/lib/core/analytics/chain-name.d.ts

@@ -1 +1,9 @@
+/**
+ * Map a numeric `chainId` to a stable lowercase slug for use as a Sentry tag
+ * value. Resolves both EVM chains ({@link NETWORKS}) and synthetic non-EVM
+ * chain IDs ({@link SPECIAL_CHAINS}); unknown IDs return `'unknown:<id>'`.
+ *
+ * @param chainId - Numeric chain ID, including negative IDs for non-EVM chains.
+ * @returns Slugified chain label (e.g. `'ethereum'`, `'arbitrum-one'`, `'solana'`).
+ */
 export declare function chainIdToTagValue(chainId: number | undefined): string;

package/lib/core/analytics/chain-name.js

@@ -2,6 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.chainIdToTagValue = chainIdToTagValue;
 const web3_1 = require("../constants/web3");
+/**
+ * Map a numeric `chainId` to a stable lowercase slug for use as a Sentry tag
+ * value. Resolves both EVM chains ({@link NETWORKS}) and synthetic non-EVM
+ * chain IDs ({@link SPECIAL_CHAINS}); unknown IDs return `'unknown:<id>'`.
+ *
+ * @param chainId - Numeric chain ID, including negative IDs for non-EVM chains.
+ * @returns Slugified chain label (e.g. `'ethereum'`, `'arbitrum-one'`, `'solana'`).
+ */
 function chainIdToTagValue(chainId) {
     if (chainId === undefined || chainId === null || Number.isNaN(chainId)) {
         return 'unknown';

package/lib/core/analytics/constants.d.ts

@@ -1 +1,5 @@
+/**
+ * Sentry DSN for SDK analytics.
+ * This is an internal constant - not exposed to SDK users.
+ */
 export declare const SENTRY_DSN = "https://d73b6a85fe14960b8dac8ac61a743a94@o4507215496609792.ingest.de.sentry.io/4510699327389776";

package/lib/core/analytics/constants.js

@@ -1,5 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SENTRY_DSN = void 0;
+/**
+ * Sentry DSN for SDK analytics.
+ * This is an internal constant - not exposed to SDK users.
+ */
 exports.SENTRY_DSN = 'https://d73b6a85fe14960b8dac8ac61a743a94@o4507215496609792.ingest.de.sentry.io/4510699327389776';
 //# sourceMappingURL=constants.js.map

package/lib/core/analytics/env.d.ts

@@ -1,4 +1,29 @@
+/**
+ * Environment-variable gates for analytics. Pure functions — safe to import
+ * anywhere, no Sentry side effects. Tested directly in `analytics.test.js`.
+ */
+/**
+ * Read a process env var without crashing in browsers or in bundles where
+ * `process.env` is a frozen / proxied object that throws on missing keys.
+ */
 export declare function readEnv(name: string): string | undefined;
+/**
+ * `AUGUST_SDK_FORCE_ANALYTICS=1` bypasses the dev/test and localhost gates.
+ * Used by our own smoke-test script and by partners deliberately exercising
+ * telemetry in a non-prod environment.
+ */
 export declare function isAnalyticsForcedOnViaEnv(): boolean;
+/**
+ * `AUGUST_SDK_DISABLE_ANALYTICS=1` is the env equivalent of passing
+ * `analytics: { enabled: false }`. Useful when partners can't easily plumb
+ * config through (CI runners, ops scripts).
+ */
 export declare function isAnalyticsDisabledViaEnv(): boolean;
+/**
+ * True when `NODE_ENV` is `'development'` or `'test'`. The SDK auto-disables
+ * analytics in these environments so partners' local dev runs and Jest suites
+ * don't pollute the production Sentry project.
+ *
+ * `NODE_ENV` undefined / `'production'` / `'staging'` / anything else → false.
+ */
 export declare function isNodeDevOrTestEnv(): boolean;