@augustdigital/sdk 8.3.1 → 8.5.0

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

@@ -1,3 +1,6 @@
+/**
+ * The default Slack webhook URL for logging errors.
+ */
 export declare const DEFAULT_SLACK_WEBHOOK_URL = "T04CM84GAV6/B0A2DS3ST8C/FLtOA3Jna3FN7UO4DoGxHfhG";
 declare function error(options: {
     title: string;

package/lib/core/logger/slack.js

@@ -4,6 +4,9 @@ exports.SLACK = exports.DEFAULT_SLACK_WEBHOOK_URL = void 0;
 const core_1 = require("../helpers/core");
 const explorer_link_1 = require("../helpers/explorer-link");
 const sanitize_1 = require("../analytics/sanitize");
+/**
+ * The default Slack webhook URL for logging errors.
+ */
 exports.DEFAULT_SLACK_WEBHOOK_URL = 'T04CM84GAV6/B0A2DS3ST8C/FLtOA3Jna3FN7UO4DoGxHfhG';
 function error(options) {
     const { title, error, poolAddress, chainId, slackWebookUrl, address } = options;

package/lib/core/vault-metadata.d.ts

@@ -1,4 +1,10 @@
 import { IVaultMetadata } from '../types';
+/**
+ * Fetch vault metadata from the upshift API.
+ * Returns metadata including symbol, subgraph URL, and address for all vaults.
+ * @param options Request options including headers
+ * @returns Vault metadata object keyed by lowercase symbol
+ */
 export declare function fetchVaultMetadata(opts?: {
     options?: {
         headers?: Record<string, string>;

package/lib/core/vault-metadata.js

@@ -4,6 +4,12 @@ exports.fetchVaultMetadata = fetchVaultMetadata;
 const cache_1 = require("./cache");
 const core_1 = require("./constants/core");
 const logger_1 = require("./logger");
+/**
+ * Fetch vault metadata from the upshift API.
+ * Returns metadata including symbol, subgraph URL, and address for all vaults.
+ * @param options Request options including headers
+ * @returns Vault metadata object keyed by lowercase symbol
+ */
 async function fetchVaultMetadata(opts) {
     const { options } = opts || {};
     try {

package/lib/core/version-check.d.ts

@@ -1,6 +1,58 @@
+/**
+ * Best-effort version check that nudges integrators when a newer
+ * `@augustdigital/sdk` is available on npm.
+ *
+ * Design constraints (all kept narrow on purpose):
+ *  - **No network call in production builds.** Most integrators ship the
+ *    SDK to end users in the browser; surprise registry pings on user page
+ *    loads are unacceptable. The check only fires when
+ *    `NODE_ENV !== 'production'` (i.e. local dev / CI environments).
+ *  - **Opt-out is supported in two places.** `AUGUST_SDK_DISABLE_VERSION_CHECK`
+ *    env var (set in CI to silence noise) or `versionCheck: { enabled: false }`
+ *    on the SDK constructor (programmatic opt-out, e.g. in your own libs
+ *    that wrap the SDK).
+ *  - **Fire-and-forget; never blocks construction.** The SDK constructor
+ *    must return synchronously. We schedule the check on the microtask
+ *    queue, abort after 5s, and swallow every error.
+ *  - **Once per session.** A module-level guard prevents repeated registry
+ *    hits when callers spin up multiple `AugustSDK` instances.
+ *  - **No new dependency.** Semver comparison is a tiny hand-rolled helper
+ *    rather than pulling in the `semver` package.
+ */
+/**
+ * Compare two numeric-dotted version strings. Returns:
+ *   - positive integer if `a > b`
+ *   - negative integer if `a < b`
+ *   - 0 if equal
+ *
+ * Pre-release suffixes (`-beta`, `-rc.1`) are stripped before comparison —
+ * we always treat any pre-release as equal to its base version. That keeps
+ * the comparison logic small and avoids false positives where an integrator
+ * on `4.27.4-beta.0` would otherwise be told to upgrade to the stable
+ * `4.27.3` they pre-released past.
+ */
 export declare function compareSemver(a: string, b: string): number;
+/**
+ * Configuration knob exposed on `IAugustBase.versionCheck`. Defaulting to
+ * enabled keeps the nudge in front of integrators who haven't read the docs;
+ * setting `enabled: false` is the explicit opt-out for libraries that wrap
+ * the SDK and want their own update strategy.
+ */
 export interface IVersionCheckConfig {
+    /** Set to `false` to disable the registry check entirely. Default: `true`. */
     enabled?: boolean;
 }
+/**
+ * Kick off a best-effort version check. Always returns synchronously.
+ *
+ * @param config - Optional config from `IAugustBase.versionCheck`
+ */
 export declare function runVersionCheck(config?: IVersionCheckConfig): void;
+/**
+ * Testing hook — resets the module-level guard so the check can run again
+ * in a fresh test case. Not part of the public API surface; kept here so
+ * unit tests don't have to monkey-patch internals.
+ *
+ * @internal
+ */
 export declare function _resetVersionCheckForTests(): void;

package/lib/core/version-check.js

@@ -1,14 +1,46 @@
 "use strict";
+/**
+ * Best-effort version check that nudges integrators when a newer
+ * `@augustdigital/sdk` is available on npm.
+ *
+ * Design constraints (all kept narrow on purpose):
+ *  - **No network call in production builds.** Most integrators ship the
+ *    SDK to end users in the browser; surprise registry pings on user page
+ *    loads are unacceptable. The check only fires when
+ *    `NODE_ENV !== 'production'` (i.e. local dev / CI environments).
+ *  - **Opt-out is supported in two places.** `AUGUST_SDK_DISABLE_VERSION_CHECK`
+ *    env var (set in CI to silence noise) or `versionCheck: { enabled: false }`
+ *    on the SDK constructor (programmatic opt-out, e.g. in your own libs
+ *    that wrap the SDK).
+ *  - **Fire-and-forget; never blocks construction.** The SDK constructor
+ *    must return synchronously. We schedule the check on the microtask
+ *    queue, abort after 5s, and swallow every error.
+ *  - **Once per session.** A module-level guard prevents repeated registry
+ *    hits when callers spin up multiple `AugustSDK` instances.
+ *  - **No new dependency.** Semver comparison is a tiny hand-rolled helper
+ *    rather than pulling in the `semver` package.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.compareSemver = compareSemver;
 exports.runVersionCheck = runVersionCheck;
 exports._resetVersionCheckForTests = _resetVersionCheckForTests;
+/** Module-level guard — flips to true after the first attempt. */
 let hasRunCheck = false;
+/** Public package name on npm — also the registry-API path component. */
 const NPM_PACKAGE = '@augustdigital/sdk';
 const REGISTRY_URL = `https://registry.npmjs.org/${NPM_PACKAGE}/latest`;
+/** Timeout for the registry request. 5s is generous; faster failures stay silent. */
 const REQUEST_TIMEOUT_MS = 5000;
+/**
+ * Read the current installed SDK version from the generated `version.ts`
+ * shim. Returns `null` when running from source (the file is gitignored and
+ * only emitted at publish time) — that's the signal to skip the check, since
+ * we have nothing meaningful to compare against.
+ */
 function getInstalledVersion() {
     try {
+        // The require path is resolved relative to the compiled .js location,
+        // so it picks up `core/analytics/version.js` when it exists.
         const mod = require('./analytics/version');
         const v = mod.SDK_VERSION;
         if (!v || v === 'development')
@@ -19,6 +51,12 @@ function getInstalledVersion() {
         return null;
     }
 }
+/**
+ * Read an environment variable in a way that's safe in both Node and the
+ * browser. `process` is typically undefined in browser bundles; even when
+ * it's stubbed by a bundler, `process.env` may be a frozen object that
+ * throws on missing-key access in some setups — try/catch covers that too.
+ */
 function readEnv(name) {
     try {
         if (typeof process !== 'undefined' && process.env) {
@@ -26,9 +64,22 @@ function readEnv(name) {
         }
     }
     catch {
+        // Bundlers occasionally throw on `process.env` access. Treat as unset.
     }
     return undefined;
 }
+/**
+ * Compare two numeric-dotted version strings. Returns:
+ *   - positive integer if `a > b`
+ *   - negative integer if `a < b`
+ *   - 0 if equal
+ *
+ * Pre-release suffixes (`-beta`, `-rc.1`) are stripped before comparison —
+ * we always treat any pre-release as equal to its base version. That keeps
+ * the comparison logic small and avoids false positives where an integrator
+ * on `4.27.4-beta.0` would otherwise be told to upgrade to the stable
+ * `4.27.3` they pre-released past.
+ */
 function compareSemver(a, b) {
     const stripPre = (v) => v.split('-')[0];
     const parse = (v) => stripPre(v)
@@ -48,25 +99,40 @@ function compareSemver(a, b) {
     }
     return 0;
 }
+/**
+ * Kick off a best-effort version check. Always returns synchronously.
+ *
+ * @param config - Optional config from `IAugustBase.versionCheck`
+ */
 function runVersionCheck(config) {
     if (hasRunCheck)
         return;
     hasRunCheck = true;
     if (config?.enabled === false)
         return;
+    // Skip in production builds. We treat *anything* other than "production"
+    // as eligible (development, test, staging) — those are the envs where a
+    // console warning is helpful, not annoying.
     if (readEnv('NODE_ENV') === 'production')
         return;
+    // Explicit env opt-out (useful in CI where the console output is noise).
     if (readEnv('AUGUST_SDK_DISABLE_VERSION_CHECK'))
         return;
     const installed = getInstalledVersion();
+    // No version file = local development from source. Nothing to compare.
     if (!installed)
         return;
+    // `fetch` is guaranteed in Node 18+ and all modern browsers, but the SDK
+    // supports older Node deployments via the React/Telegram bot integration.
+    // Gracefully no-op when missing.
     if (typeof fetch !== 'function')
         return;
     const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
     const timeoutId = controller
         ? setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS)
         : null;
+    // Run on the microtask queue so construction stays synchronous. The void
+    // expression discards the promise — we explicitly don't await it.
     void (async () => {
         try {
             const res = await fetch(REGISTRY_URL, {
@@ -80,6 +146,11 @@ function runVersionCheck(config) {
             if (!latest)
                 return;
             if (compareSemver(latest, installed) > 0) {
+                // Use console.warn so the message is visible at the default log
+                // level in most setups, but distinguishable from real errors. This is
+                // an integrator-facing nudge — Logger.log.warn would make it a
+                // prod-silent breadcrumb, defeating the purpose.
+                // biome-ignore lint/suspicious/noConsole: integrator-facing version nudge must surface in every environment; Logger.log.warn would make it a prod-silent breadcrumb.
                 console.warn([
                     `[${NPM_PACKAGE}] A newer version is available: ${installed} → ${latest}.`,
                     `Run \`pnpm up ${NPM_PACKAGE}\` (or your package manager's equivalent) to update.`,
@@ -88,6 +159,9 @@ function runVersionCheck(config) {
             }
         }
         catch {
+            // Network failure, aborted request, malformed JSON, frozen
+            // `console.warn`, etc. — every failure path stays silent. The check
+            // is purely an integrator-experience hint; it must never surface.
         }
         finally {
             if (timeoutId)
@@ -95,6 +169,13 @@ function runVersionCheck(config) {
         }
     })();
 }
+/**
+ * Testing hook — resets the module-level guard so the check can run again
+ * in a fresh test case. Not part of the public API surface; kept here so
+ * unit tests don't have to monkey-patch internals.
+ *
+ * @internal
+ */
 function _resetVersionCheckForTests() {
     hasRunCheck = false;
 }

package/lib/evm/methods/crossChainVault.d.ts

@@ -1,11 +1,50 @@
+/**
+ * Cross-Chain Vault Methods
+ *
+ * Implements LayerZero OVault cross-chain deposit and redemption operations.
+ * These functions are generic — callers provide their own ICrossChainVaultConfig
+ * rather than relying on hardcoded vault addresses.
+ *
+ * @module evm/methods/crossChainVault
+ */
 import type { IAddress } from '../../types';
 import type { ICrossChainVaultConfig, ICrossChainBuildRequest, ICrossChainBuildResult, ICrossChainDepositRequest, ICrossChainDepositResult, ICrossChainRedeemRequest, ICrossChainRedeemResult, IQuoteCrossChainDepositRequest, IQuoteCrossChainRedeemRequest, IQuoteCrossChainResult, CrossChainErrorType } from '../types/crossChain';
+/**
+ * Build LayerZero OVault transaction inputs for cross-chain deposits and
+ * redemptions. Does NOT execute the transaction.
+ *
+ * Overridable defaults on `props`: `slippageBps` = 100 (range 1–10000),
+ * `feeBufferPercent` = 50% (added to LZ `nativeFee`),
+ * `hubLzComposeGasLimit` = 2_000_000n (multi-asset composed messages).
+ *
+ * @returns Transaction inputs or `{ success: false, error }`.
+ */
 export declare function buildCrossChainVaultTx(props: ICrossChainBuildRequest): Promise<ICrossChainBuildResult>;
+/**
+ * Estimate fees and expected shares for a cross-chain deposit. The returned
+ * quote carries `quotedAt`/`expiresAt`; re-quote via {@link isQuoteStale}
+ * before submitting.
+ */
 export declare function quoteCrossChainDeposit(props: IQuoteCrossChainDepositRequest): Promise<IQuoteCrossChainResult | null>;
+/**
+ * Estimate fees and expected assets for a cross-chain redeem. The returned
+ * quote carries `quotedAt`/`expiresAt`; re-quote via {@link isQuoteStale}
+ * before submitting.
+ */
 export declare function quoteCrossChainRedeem(props: IQuoteCrossChainRedeemRequest): Promise<IQuoteCrossChainResult | null>;
+/**
+ * Returns `true` when the wallet's ERC-20 allowance is insufficient for the
+ * cross-chain operation. On RPC failure also returns `true` (defensive
+ * default — better a redundant approval than a downstream revert).
+ */
 export declare function needsCrossChainApproval(tokenAddress: IAddress, spenderAddress: IAddress, walletAddress: IAddress, amount: bigint, publicClient: {
     readContract: (args: unknown) => Promise<unknown>;
 }): Promise<boolean>;
+/**
+ * Execute a token approval for a cross-chain operation.
+ *
+ * @returns Transaction hash of the approval
+ */
 export declare function approveCrossChain(tokenAddress: IAddress, spenderAddress: IAddress, amount: bigint, walletClient: {
     account: {
         address: string;
@@ -18,16 +57,67 @@ export declare function approveCrossChain(tokenAddress: IAddress, spenderAddress
         status: string;
     }>;
 }): Promise<string>;
+/**
+ * Execute a cross-chain deposit via LayerZero OVault. Validates the source
+ * chain, ensures approval, estimates gas with a buffer, and waits for the
+ * on-chain receipt. Defaults: `slippageBps` 100, `feeBufferPercent` 50,
+ * `gasBufferPercent` 150 — all overridable on the request.
+ *
+ * @throws Error on unsupported chain, approval revert, gas-estimation
+ *   failure, or on-chain revert.
+ */
 export declare function crossChainVaultDeposit(props: ICrossChainDepositRequest): Promise<ICrossChainDepositResult>;
+/**
+ * Execute a cross-chain redemption via LayerZero OVault. User must be on the
+ * hub chain. Defaults: `slippageBps` 100, `feeBufferPercent` 50,
+ * `gasBufferPercent` 200 (compose calls under-estimate on mainnet),
+ * `minGasLimit` 5_000_000n — all overridable on the request.
+ */
 export declare function crossChainVaultRedeem(props: ICrossChainRedeemRequest): Promise<ICrossChainRedeemResult>;
+/**
+ * Check if an error indicates a missing LayerZero peer configuration.
+ */
 export declare function isNoPeerError(errStr: string): boolean;
+/**
+ * Classify a cross-chain contract error into a known error type.
+ */
 export declare function classifyCrossChainError(error: unknown): CrossChainErrorType;
+/**
+ * Check if a user can deposit from their current chain.
+ */
 export declare function canDepositFromChain(config: ICrossChainVaultConfig, userChainId: number): boolean;
+/**
+ * Check if a user can redeem from their current chain (must be hub).
+ */
 export declare function canRedeemFromChain(config: ICrossChainVaultConfig, userChainId: number): boolean;
+/**
+ * Check if an operation is cross-chain (needs LayerZero).
+ *
+ * An operation is cross-chain when:
+ * - The user's chain differs from the hub chain, OR
+ * - The destination chain differs from the hub chain
+ *   (e.g. deposit from hub but receive shares on a spoke)
+ */
 export declare function isCrossChainOperation(config: ICrossChainVaultConfig, userChainId: number, destinationChainId?: number): boolean;
+/**
+ * Get all chain IDs that a vault supports (hub + all spokes).
+ */
 export declare function getAvailableChains(config: ICrossChainVaultConfig): number[];
+/**
+ * Format a cross-chain error into a user-friendly message.
+ *
+ * Mirrors the `classifyCrossChainDepositError` from upshift-app but is
+ * generic enough for any SDK consumer.
+ */
 export declare function formatCrossChainError(errMsg: string): string;
+/**
+ * Get the LayerZero Scan URL for tracking a cross-chain message.
+ */
 export declare function getLayerZeroScanUrl(txHash: string, testnet?: boolean): string;
+/**
+ * Well-known LayerZero Endpoint IDs for common chains.
+ * SDK consumers can use these when building their ICrossChainVaultConfig.
+ */
 export declare const LAYERZERO_ENDPOINT_IDS: {
     readonly ETHEREUM: 30101;
     readonly ARBITRUM: 30110;