@augustdigital/sdk 9.5.0 → 9.6.0

package/lib/core/analytics/sentry.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSDKVersion = getSDKVersion;
 exports.resetErrorDedupe = resetErrorDedupe;
 exports.initializeSentry = initializeSentry;
 exports.updateUser = updateUser;
 exports.clearUser = clearUser;
 exports.isAnalyticsEnabled = isAnalyticsEnabled;
+exports.getSpanAttributes = getSpanAttributes;
 exports.getSentry = getSentry;
 exports.resetAnalytics = resetAnalytics;
 exports.captureSdkException = captureSdkException;
@@ -22,9 +24,15 @@ let isEnabled = true;
 let currentIdentity = null;
 /** Cached API key for identity updates */
 let cachedApiKey;
+/** Identity tags resolved at init, mirrored onto every `sdk.method` span. */
+let spanAttributes = {};
 /**
- * Get the SDK version from the generated version file.
- * Falls back to 'development' if file doesn't exist (during local dev).
+ * The August SDK build version, read from the generated `version.ts`.
+ * Falls back to `'development'` in an unbuilt checkout, where that file does
+ * not exist. Shared by the Sentry `release` tag and the
+ * `x-august-sdk-version` request header so the two can never disagree.
+ *
+ * @internal
  */
 function getSDKVersion() {
     try {
@@ -326,7 +334,8 @@ function createSentrySink() {
  * error rather than silently anonymous events.
  *
  * @param config - Analytics configuration. Pass `tracesSampleRate` to
- *   override the default of `0.1`.
+ *   override the default of `0.1`, and `surface` to label the emitting
+ *   surface (`sdk.surface` tag; defaults to `'sdk'`).
  * @param environment - Current environment (DEV or PROD).
  * @param appName - App-name slug, required. Set as the global `app.name`
  *   tag on every event and used to derive `partner.id`. Identifier-shaped:
@@ -463,17 +472,6 @@ function initializeSentry(config, environment, appName, walletAddress, apiKey) {
                 }
                 return event;
             },
-            beforeSendTransaction(transaction) {
-                // Sub-sample the high-frequency network bookkeeping category (switchNetwork,
-                // updateWallet, clearWallet, setSigner) to 10% of whatever tracesSampleRate
-                // already passed — these fire on every wallet/chain update and are low signal
-                // for the partner-usage dashboard relative to read/write calls.
-                if (transaction.tags?.['sdk.category'] === 'network' &&
-                    Math.random() > 0.1) {
-                    return null;
-                }
-                return transaction;
-            },
         });
         // Set initial user identity
         updateUser(walletAddress, environment);
@@ -500,13 +498,32 @@ function initializeSentry(config, environment, appName, walletAddress, apiKey) {
          * dashboards, and alert rules keep resolving; remove in the next major.
          */
         safeSetTag('sdk.version', sdkVersion);
-        safeSetTag('sdk.runtime', (0, sentry_runtime_1.getSentryRuntime)());
+        const runtime = (0, sentry_runtime_1.getSentryRuntime)();
+        safeSetTag('sdk.runtime', runtime);
         // `app.name` is the dimension we filter on in Sentry to attribute
         // events to a specific consuming application — see SDK quickstart docs.
         safeSetTag('app.name', validatedAppName);
         // `unverified:` prefix until the backend API-key → partner-id endpoint exists.
-        safeSetTag('partner.id', `unverified:${validatedAppName}`);
-        safeSetTag('partner.tier', 'unverified');
+        const partnerId = `unverified:${validatedAppName}`;
+        safeSetTag('partner.id', partnerId);
+        // First-party apps are labelled so `partner.tier:unverified` already
+        // means "external integrator" before verification exists.
+        const partnerTier = constants_1.FIRST_PARTY_APP_NAMES.has(validatedAppName)
+            ? 'internal'
+            : 'unverified';
+        safeSetTag('partner.tier', partnerTier);
+        const surface = config.surface ?? 'sdk';
+        safeSetTag('sdk.surface', surface);
+        // Scope tags land only on the root span of a trace; child `sdk.method`
+        // spans get these copied on as attributes by `withMethodTracking`.
+        spanAttributes = {
+            'app.name': validatedAppName,
+            'partner.id': partnerId,
+            'partner.tier': partnerTier,
+            'sdk.runtime': runtime,
+            'sdk.surface': surface,
+            'august.sdk_version': sdkVersion,
+        };
         // Bridge the SDK's structured logger into Sentry now that the SDK is live.
         // Without this, Logger.log.error/warn are no-ops in production (no
         // SDKLogger/structured logger is wired by default), so SDK-internal
@@ -594,6 +611,18 @@ function clearUser() {
 function isAnalyticsEnabled() {
     return isEnabled && isInitialized;
 }
+/**
+ * Identity tags resolved by `initializeSentry`, for `withMethodTracking` to
+ * copy onto each span as attributes. Sentry's span dataset carries scope tags
+ * on the root span only, so without this copy child `sdk.method` rows cannot
+ * be filtered by `app.name` or `partner.id`.
+ *
+ * @returns The tag snapshot, or `{}` until analytics has been enabled.
+ * @internal
+ */
+function getSpanAttributes() {
+    return spanAttributes;
+}
 /**
  * Get the current Sentry instance for advanced usage.
  * Returns null if analytics is disabled.
@@ -611,6 +640,7 @@ function resetAnalytics() {
     isEnabled = true;
     currentIdentity = null;
     cachedApiKey = undefined;
+    spanAttributes = {};
     logger_1.Logger.setSentrySink(null);
     (0, sentry_runtime_1.resetSentryRuntime)();
     // The error rate limiter is process-lifetime state; a reset analytics layer
@@ -624,7 +654,8 @@ function resetAnalytics() {
  * surface. No-ops when analytics is disabled.
  *
  * @param error - Thrown value. Non-Error values are wrapped.
- * @param options - `surface` ('cli' | 'sdk' | 'react' | string), extra `tags`,
+ * @param options - `surface` ('cli' | 'mcp' | 'sdk' | 'react' | string)
+ *   overriding the init-time `sdk.surface` tag for this event, extra `tags`,
  *   `extra` data, and a `flushTimeoutMs` to await before resolving (needed
  *   in Node when the process is about to exit).
  */

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

@@ -7,17 +7,24 @@ export interface IAnalyticsConfig {
     /** Set to false to disable analytics. Default: true */
     enabled?: boolean;
     /**
-     * Sentry trace sample rate. Defaults to `1.0` for the Phase 1/2 rollout;
-     * values outside `[0, 1]` are clamped.
+     * Sentry trace sample rate. Defaults to `0.1`; values outside `[0, 1]`
+     * are clamped.
      */
     tracesSampleRate?: number;
+    /**
+     * Which August surface is emitting telemetry, recorded once at init as the
+     * sticky `sdk.surface` tag on every event and span. The CLI passes `'cli'`
+     * and the MCP server `'mcp'`; applications embedding the SDK directly can
+     * leave the default `'sdk'`.
+     */
+    surface?: 'sdk' | 'cli' | 'mcp' | 'react' | string;
 }
 /**
  * User identity for analytics tracking.
- * Multiple identifiers are used with priority: apiKeyHash > wallet > fingerprint > session
+ * Multiple identifiers are used with priority: apiKeyHash \> wallet \> domain \> fingerprint \> session
  */
 export interface IUserIdentity {
-    /** SHA-256 hash prefix of API key (first 16 chars). Never stores raw key. */
+    /** Hex-encoded SHA-256 hash of the API key. Never stores the raw key. */
     apiKeyHash?: string;
     /** User's wallet address (lowercased) */
     walletAddress?: string;

package/lib/core/analytics/user-identity.d.ts

@@ -1,11 +1,19 @@
 import type { IEnv } from '../../types';
 import type { IUserIdentity } from './types';
 /**
- * Mask an API key, keeping only the last 5 characters visible.
- * Example: "abcdefghij12345" -> "**********12345"
+ * Hash an API key with SHA-256 for use as a Sentry-safe identity token.
  *
- * @param apiKey - The raw API key to mask
- * @returns Masked API key with last 5 characters visible
+ * Only the hash is ever returned. The most recently hashed key and its hash
+ * are cached in memory, so a repeat call skips the digest and a different key
+ * replaces the cache instead of returning the previous key's hash.
+ *
+ * When the runtime has no usable `crypto.createHash` (e.g. a browser bundle
+ * without a `crypto` shim) this returns `''` rather than throwing, so the
+ * Sentry identity falls back to the next identifier instead of being dropped.
+ *
+ * @param apiKey - The raw API key to hash
+ * @returns Hex-encoded SHA-256 hash of `apiKey`, or `''` for an empty input or
+ *   when hashing is unavailable
  */
 export declare function hashApiKey(apiKey: string): string;
 /**
@@ -33,7 +41,13 @@ export declare function generateFingerprint(): string | undefined;
 export declare function createUserIdentity(apiKey?: string, walletAddress?: string, environment?: IEnv): IUserIdentity;
 /**
  * Generate a unique user ID for Sentry from identity components.
- * Priority: apiKeyHash > wallet > fingerprint > session
+ * Priority: apiKeyHash \> wallet \> domain \> fingerprint \> session
+ *
+ * An API key identifies the integrator and a wallet identifies the end user,
+ * so both outrank the hosting domain — otherwise every visitor of one web app
+ * collapses into a single Sentry user. `domain` still ranks above the
+ * fingerprint, which nearly every runtime produces, so hostname attribution
+ * is not lost.
  *
  * @param identity - User identity object
  * @returns Prefixed user ID string

package/lib/core/analytics/user-identity.js

@@ -9,31 +9,39 @@ const crypto_1 = require("crypto");
 const uuid_1 = require("uuid");
 /** Session ID persists for SDK instance lifetime */
 let sessionId = null;
-/** Cached masked API key */
-let cachedMaskedApiKey = null;
+/** Raw API key the cached hash below was computed from — lets a key change invalidate the cache. */
+let cachedApiKey = null;
+/** SHA-256 hash of {@link cachedApiKey}. */
+let cachedApiKeyHash = null;
 /**
- * Mask an API key, keeping only the last 5 characters visible.
- * Example: "abcdefghij12345" -> "**********12345"
+ * Hash an API key with SHA-256 for use as a Sentry-safe identity token.
  *
- * @param apiKey - The raw API key to mask
- * @returns Masked API key with last 5 characters visible
+ * Only the hash is ever returned. The most recently hashed key and its hash
+ * are cached in memory, so a repeat call skips the digest and a different key
+ * replaces the cache instead of returning the previous key's hash.
+ *
+ * When the runtime has no usable `crypto.createHash` (e.g. a browser bundle
+ * without a `crypto` shim) this returns `''` rather than throwing, so the
+ * Sentry identity falls back to the next identifier instead of being dropped.
+ *
+ * @param apiKey - The raw API key to hash
+ * @returns Hex-encoded SHA-256 hash of `apiKey`, or `''` for an empty input or
+ *   when hashing is unavailable
  */
 function hashApiKey(apiKey) {
     if (!apiKey)
         return '';
-    // Use cached masked key if available
-    if (cachedMaskedApiKey)
-        return cachedMaskedApiKey;
-    const visibleChars = 5;
-    if (apiKey.length <= visibleChars) {
-        cachedMaskedApiKey = apiKey;
+    if (cachedApiKey === apiKey && cachedApiKeyHash) {
+        return cachedApiKeyHash;
     }
-    else {
-        const masked = '*'.repeat(apiKey.length - visibleChars);
-        const visible = apiKey.slice(-visibleChars);
-        cachedMaskedApiKey = masked + visible;
+    try {
+        cachedApiKeyHash = (0, crypto_1.createHash)('sha256').update(apiKey).digest('hex');
+        cachedApiKey = apiKey;
+        return cachedApiKeyHash;
+    }
+    catch {
+        return '';
     }
-    return cachedMaskedApiKey;
 }
 /**
  * Generate a session ID that persists for the SDK instance lifetime.
@@ -118,21 +126,27 @@ function createUserIdentity(apiKey, walletAddress, environment = 'PROD') {
 }
 /**
  * Generate a unique user ID for Sentry from identity components.
- * Priority: apiKeyHash > wallet > fingerprint > session
+ * Priority: apiKeyHash \> wallet \> domain \> fingerprint \> session
+ *
+ * An API key identifies the integrator and a wallet identifies the end user,
+ * so both outrank the hosting domain — otherwise every visitor of one web app
+ * collapses into a single Sentry user. `domain` still ranks above the
+ * fingerprint, which nearly every runtime produces, so hostname attribution
+ * is not lost.
  *
  * @param identity - User identity object
  * @returns Prefixed user ID string
  */
 function getUserId(identity) {
-    if (identity.domain) {
-        return `domain:${identity.domain}`;
-    }
     if (identity.apiKeyHash) {
         return `apikey:${identity.apiKeyHash}`;
     }
     if (identity.walletAddress) {
         return `wallet:${identity.walletAddress}`;
     }
+    if (identity.domain) {
+        return `domain:${identity.domain}`;
+    }
     if (identity.fingerprint) {
         return `fp:${identity.fingerprint}`;
     }

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

@@ -3,4 +3,4 @@
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-export declare const SDK_VERSION = "9.5.0";
+export declare const SDK_VERSION = "9.6.0";

package/lib/core/analytics/version.js

@@ -6,5 +6,5 @@ exports.SDK_VERSION = void 0;
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-exports.SDK_VERSION = '9.5.0';
+exports.SDK_VERSION = '9.6.0';
 //# sourceMappingURL=version.js.map

package/lib/core/auth/verify.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.verifyInfuraKey = verifyInfuraKey;
 exports.verifyAugustKey = verifyAugustKey;
+const analytics_1 = require("../analytics");
 const core_1 = require("../constants/core");
 const fetcher_1 = require("../fetcher");
 async function verifyInfuraKey(key) {
@@ -20,11 +21,14 @@ async function verifyAugustKey(key) {
         return false;
     try {
         const verify = await (0, fetcher_1.fetchAugustWithKey)(key, core_1.WEBSERVER_ENDPOINTS.auth.verify);
-        return verify.status === 200;
+        const success = verify.status === 200;
+        (0, analytics_1.trackKeyVerification)('august', success);
+        return success;
     }
     catch {
         // Network errors, timeouts, and any future thrown auth errors all
         // resolve to "key not verified" here. Callers handle this as a boolean.
+        (0, analytics_1.trackKeyVerification)('august', false);
         return false;
     }
 }

package/lib/core/base.class.js

@@ -71,6 +71,9 @@ class AugustBase {
         // prior staging instance would leak into a later prod instance in the same
         // process — the inverse of the isolation this option exists to provide.
         (0, fetcher_1.setPublicApiBaseUrl)(publicApiBaseUrl ?? null);
+        // Every backend request from this process now identifies the app
+        // (`x-august-app`) — same last-instance-wins contract as the base URL.
+        (0, fetcher_1.setSdkAppName)(this.appName);
         // ERC-8021 attribution follows the same reset-on-omit contract as
         // `publicApiBaseUrl`: called unconditionally so a prior instance's
         // builder codes never leak into a later instance in the same process.

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

@@ -33,6 +33,7 @@ export declare const WEBSERVER_URL: {
 };
 export declare const WEBSERVER_ENDPOINTS: {
     default: {
+        /** @deprecated No backend route. Removed in the next major release. */
         hello: string;
         protected: string;
     };
@@ -45,6 +46,7 @@ export declare const WEBSERVER_ENDPOINTS: {
     };
     subaccount: {
         list: (offset?: number, limit?: number) => string;
+        /** @deprecated No backend route. Removed in the next major release. */
         rewards: (subaccount: IAddress) => string;
         tokens: (subaccount: IAddress) => string;
         twap: {
@@ -55,6 +57,7 @@ export declare const WEBSERVER_ENDPOINTS: {
         debank: (subaccount: IAddress) => string;
         health_factor: (subaccount: IAddress) => string;
         summary: (subaccount: IAddress) => string;
+        /** @deprecated No backend route. Removed in the next major release. */
         batch: (subaccount: IAddress) => string;
         loans: (subaccount: IAddress, side?: "BORROWER" | "LENDER" | "BOTH", active?: boolean) => string;
         cefi: (subaccount: IAddress) => string;

package/lib/core/constants/core.js

@@ -63,6 +63,7 @@ exports.WEBSERVER_URL = {
 };
 exports.WEBSERVER_ENDPOINTS = {
     default: {
+        /** @deprecated No backend route. Removed in the next major release. */
         hello: '/hello',
         protected: '/protected',
     },
@@ -75,6 +76,7 @@ exports.WEBSERVER_ENDPOINTS = {
     },
     subaccount: {
         list: (offset = 0, limit = 100) => `/subaccount?offset=${offset}&limit=${limit}`,
+        /** @deprecated No backend route. Removed in the next major release. */
         rewards: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/rewards`,
         tokens: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/tokens`,
         twap: {
@@ -85,6 +87,7 @@ exports.WEBSERVER_ENDPOINTS = {
         debank: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/debank`,
         health_factor: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/health_factor`,
         summary: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/summary`,
+        /** @deprecated No backend route. Removed in the next major release. */
         batch: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/tx_batcher_integrations`,
         loans: (subaccount, side = 'BOTH', active = true) => `/subaccount/${subaccountSegment(subaccount)}/loans?side=${side}&active=${active}`,
         cefi: (subaccount) => `/subaccount/${subaccountSegment(subaccount)}/cefi_position`,

package/lib/core/constants/swap-router.d.ts

@@ -108,6 +108,22 @@ export declare const SWAP_ROUTER_MAX_SWAPS = 9;
  * every dispatch. Used to validate that native-token deposits target a
  * vault whose reference asset is the wrapped native — the only configuration
  * the contract's `depositNativeToken` / `swapAndDepositNativeToken` accept.
+ *
+ * **Wrap-only, WETH-vaults-only limitation.** Both payable entry points on the
+ * deployed router (`depositNativeToken` and `swapAndDepositNativeToken`) only
+ * wrap native ETH to this address and deposit — neither has an ETH→other-asset
+ * swap leg. `swapAndDepositNativeToken`'s ABI takes no swap payload, so a DEX
+ * swap is structurally impossible on that path too; its only difference from
+ * `depositNativeToken` is applying the vault swap fee on the pure wrap. The
+ * practical consequence: **native ETH can only be deposited into a vault whose
+ * reference asset is this wrapped-native token** (e.g. a WETH-reference
+ * vault). There is no atomic native-ETH deposit into a non-WETH-reference
+ * vault (e.g. a USDC vault) — deposit the wrapped native token instead
+ * (already whitelisted, and it routes through the swap leg for a vault whose
+ * reference asset differs). True atomic ETH→any-asset support would require a
+ * contract change (a payable `swapAndDeposit` variant), which is out of scope
+ * for this SDK. Use {@link isNativeSwapRouterDepositSupported} to check a
+ * vault's eligibility for the native path before offering it in a UI.
  */
 export declare const SWAP_ROUTER_WRAPPED_NATIVE: Readonly<Record<number, IAddress>>;
 /**

package/lib/core/constants/swap-router.js

@@ -121,6 +121,22 @@ exports.SWAP_ROUTER_MAX_SWAPS = 9;
  * every dispatch. Used to validate that native-token deposits target a
  * vault whose reference asset is the wrapped native — the only configuration
  * the contract's `depositNativeToken` / `swapAndDepositNativeToken` accept.
+ *
+ * **Wrap-only, WETH-vaults-only limitation.** Both payable entry points on the
+ * deployed router (`depositNativeToken` and `swapAndDepositNativeToken`) only
+ * wrap native ETH to this address and deposit — neither has an ETH→other-asset
+ * swap leg. `swapAndDepositNativeToken`'s ABI takes no swap payload, so a DEX
+ * swap is structurally impossible on that path too; its only difference from
+ * `depositNativeToken` is applying the vault swap fee on the pure wrap. The
+ * practical consequence: **native ETH can only be deposited into a vault whose
+ * reference asset is this wrapped-native token** (e.g. a WETH-reference
+ * vault). There is no atomic native-ETH deposit into a non-WETH-reference
+ * vault (e.g. a USDC vault) — deposit the wrapped native token instead
+ * (already whitelisted, and it routes through the swap leg for a vault whose
+ * reference asset differs). True atomic ETH→any-asset support would require a
+ * contract change (a payable `swapAndDeposit` variant), which is out of scope
+ * for this SDK. Use {@link isNativeSwapRouterDepositSupported} to check a
+ * vault's eligibility for the native path before offering it in a UI.
  */
 exports.SWAP_ROUTER_WRAPPED_NATIVE = {
     1: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',

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

@@ -15,7 +15,7 @@
  * ```
  */
 /** Stable error codes attached to SDK errors. */
-export type AugustErrorCode = 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED' | 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'ACCOUNT_NOT_FUNDED' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'HISTORY_UNAVAILABLE' | 'UNKNOWN';
+export type AugustErrorCode = 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED' | 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'ACCOUNT_NOT_FUNDED' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'HISTORY_UNAVAILABLE' | 'PRICE_UNAVAILABLE' | 'UNKNOWN';
 /** Options accepted by every SDK error constructor. */
 export interface AugustErrorOptions {
     /** Original error preserved for stack-trace chaining. */
@@ -110,5 +110,40 @@ export declare class AugustHistoryUnavailableError extends AugustSDKError {
      */
     constructor(message: string, options?: AugustErrorOptions);
 }
+/**
+ * The USD price needed to convert a computed value could not be resolved, so
+ * any USD figure derived from it would be fabricated rather than merely
+ * missing.
+ *
+ * Motivation — `getVaultUserLifetimePnl` used to substitute a price of `1`
+ * whenever the price server returned nothing, which reported every
+ * USD field of a non-dollar vault (lsETH, tETH, BTC) at $1 per asset: a
+ * position worth ~$40k read as ~$13, indistinguishable from a real result.
+ * Throwing this typed error makes a missing price explicit so callers can hide
+ * the USD value instead of displaying a wrong one.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.getVaultUserLifetimePnl({ vault, wallet, chainId });
+ * } catch (err) {
+ *   if (err instanceof AugustPriceUnavailableError) {
+ *     // No USD price for the vault asset — hide the USD figures rather than
+ *     // show a fabricated one.
+ *     hideUsd(err.context);
+ *   } else throw err;
+ * }
+ * ```
+ */
+export declare class AugustPriceUnavailableError extends AugustSDKError {
+    /**
+     * @param message - Human-readable description of the missing price. Callers
+     *   pass the same `#<method>::<vault>::<wallet>` prefix the surrounding getter
+     *   uses so log grouping stays consistent.
+     * @param options - Standard SDK error options. `context` should carry the
+     *   identifiers that scope the failure (e.g. `{ vault, wallet, asset }`).
+     */
+    constructor(message: string, options?: AugustErrorOptions);
+}
 /** Type guard. Works across realms (e.g. Web Worker / VM contexts). */
 export declare function isAugustSDKError(err: unknown): err is AugustSDKError;

package/lib/core/errors/index.js

@@ -16,7 +16,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AugustHistoryUnavailableError = exports.AugustServerError = exports.AugustRateLimitError = exports.AugustValidationError = exports.AugustTimeoutError = exports.AugustNetworkError = exports.AugustAuthError = exports.AugustSDKError = void 0;
+exports.AugustPriceUnavailableError = exports.AugustHistoryUnavailableError = exports.AugustServerError = exports.AugustRateLimitError = exports.AugustValidationError = exports.AugustTimeoutError = exports.AugustNetworkError = exports.AugustAuthError = exports.AugustSDKError = void 0;
 exports.isAugustSDKError = isAugustSDKError;
 /** Base class for all SDK errors. */
 class AugustSDKError extends Error {
@@ -173,6 +173,45 @@ class AugustHistoryUnavailableError extends AugustSDKError {
     }
 }
 exports.AugustHistoryUnavailableError = AugustHistoryUnavailableError;
+/**
+ * The USD price needed to convert a computed value could not be resolved, so
+ * any USD figure derived from it would be fabricated rather than merely
+ * missing.
+ *
+ * Motivation — `getVaultUserLifetimePnl` used to substitute a price of `1`
+ * whenever the price server returned nothing, which reported every
+ * USD field of a non-dollar vault (lsETH, tETH, BTC) at $1 per asset: a
+ * position worth ~$40k read as ~$13, indistinguishable from a real result.
+ * Throwing this typed error makes a missing price explicit so callers can hide
+ * the USD value instead of displaying a wrong one.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.getVaultUserLifetimePnl({ vault, wallet, chainId });
+ * } catch (err) {
+ *   if (err instanceof AugustPriceUnavailableError) {
+ *     // No USD price for the vault asset — hide the USD figures rather than
+ *     // show a fabricated one.
+ *     hideUsd(err.context);
+ *   } else throw err;
+ * }
+ * ```
+ */
+class AugustPriceUnavailableError extends AugustSDKError {
+    /**
+     * @param message - Human-readable description of the missing price. Callers
+     *   pass the same `#<method>::<vault>::<wallet>` prefix the surrounding getter
+     *   uses so log grouping stays consistent.
+     * @param options - Standard SDK error options. `context` should carry the
+     *   identifiers that scope the failure (e.g. `{ vault, wallet, asset }`).
+     */
+    constructor(message, options) {
+        super('PRICE_UNAVAILABLE', message, options);
+        this.name = 'AugustPriceUnavailableError';
+    }
+}
+exports.AugustPriceUnavailableError = AugustPriceUnavailableError;
 /** Type guard. Works across realms (e.g. Web Worker / VM contexts). */
 function isAugustSDKError(err) {
     return (err instanceof AugustSDKError ||

package/lib/core/fetcher.d.ts

@@ -41,6 +41,19 @@ export declare function setSdkRequestTimeout(ms?: number | null): void;
  * otherwise the compiled-in `REQUEST_TIMEOUT_MS`.
  */
 export declare function getSdkRequestTimeout(): number;
+/**
+ * Record the consuming application's `appName` so every request to the
+ * August backend carries it as `x-august-app`, next to
+ * `x-august-sdk-version`. This gives the backend per-integrator request
+ * counts that do not depend on Sentry sampling.
+ *
+ * Process-global, last writer wins — the same contract as
+ * `setSdkRequestTimeout` and `setPublicApiBaseUrl`. The `AugustSDK`
+ * constructor calls this with its validated `appName`.
+ *
+ * @param appName - Validated app-name slug, or `null` to stop sending it.
+ */
+export declare function setSdkAppName(appName?: string | null): void;
 /**
  * Override the base URL used for `WEBSERVER_URL.public` requests — the
  * unauthenticated vault-catalog API that `getVault` / `fetchTokenizedVault`

package/lib/core/fetcher.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.setSafeCache = exports.getSafeCache = exports.CACHE = void 0;
 exports.setSdkRequestTimeout = setSdkRequestTimeout;
 exports.getSdkRequestTimeout = getSdkRequestTimeout;
+exports.setSdkAppName = setSdkAppName;
 exports.setPublicApiBaseUrl = setPublicApiBaseUrl;
 exports.getPublicApiBaseUrl = getPublicApiBaseUrl;
 exports.fetchAugustWithKey = fetchAugustWithKey;
@@ -32,6 +33,7 @@ const core_2 = require("./constants/core");
 const vault_version_1 = require("./helpers/vault-version");
 const analytics_1 = require("./analytics");
 const sanitize_1 = require("./analytics/sanitize");
+const sentry_1 = require("./analytics/sentry");
 const errors_1 = require("./errors");
 /** Map an HTTP status to the appropriate typed SDK error subclass. */
 function errorFromResponseStatus(status, message, options) {
@@ -76,6 +78,34 @@ function setSdkRequestTimeout(ms = null) {
 function getSdkRequestTimeout() {
     return SDK_REQUEST_TIMEOUT_OVERRIDE ?? core_2.REQUEST_TIMEOUT_MS;
 }
+let SDK_APP_NAME = null;
+/**
+ * Record the consuming application's `appName` so every request to the
+ * August backend carries it as `x-august-app`, next to
+ * `x-august-sdk-version`. This gives the backend per-integrator request
+ * counts that do not depend on Sentry sampling.
+ *
+ * Process-global, last writer wins — the same contract as
+ * `setSdkRequestTimeout` and `setPublicApiBaseUrl`. The `AugustSDK`
+ * constructor calls this with its validated `appName`.
+ *
+ * @param appName - Validated app-name slug, or `null` to stop sending it.
+ */
+function setSdkAppName(appName = null) {
+    SDK_APP_NAME = appName;
+}
+/**
+ * Client-identification headers merged into every backend fetcher's
+ * defaults. Both values are low-cardinality slugs, never credentials.
+ */
+function sdkClientHeaders() {
+    const headers = {
+        'x-august-sdk-version': (0, sentry_1.getSDKVersion)(),
+    };
+    if (SDK_APP_NAME)
+        headers['x-august-app'] = SDK_APP_NAME;
+    return headers;
+}
 let PUBLIC_API_BASE_OVERRIDE = null;
 /**
  * Override the base URL used for `WEBSERVER_URL.public` requests — the
@@ -370,6 +400,7 @@ async function fetchAugustWithKey(apiKey, relativeUrl, options) {
         throw new errors_1.AugustAuthError('AUTH_MISSING_KEY', 'fetchAugustWithKey: apiKey is required (set keys.august on the SDK constructor, or pass an explicit apiKey).');
     }
     const defaultHeaders = {
+        ...sdkClientHeaders(),
         'x-api-key': apiKey,
         'content-type': 'application/json',
         accept: 'application/json',
@@ -426,6 +457,7 @@ async function fetchAugustWithKey(apiKey, relativeUrl, options) {
  */
 async function fetchAugustPublic(relativeUrl, options) {
     const defaultHeaders = {
+        ...sdkClientHeaders(),
         'content-type': 'application/json',
         accept: 'application/json',
     };
@@ -480,6 +512,7 @@ async function fetchAugustPublic(relativeUrl, options) {
  */
 async function fetchAugustWithBearer(bearerToken, relativeUrl, options) {
     const defaultHeaders = {
+        ...sdkClientHeaders(),
         authorization: `Bearer ${bearerToken}`,
         'content-type': 'application/json',
         accept: 'application/json',

package/lib/main.d.ts

@@ -355,6 +355,11 @@ export declare class AugustSDK extends AugustBase {
      * Calculates realized and unrealized PnL based on deposit/withdrawal history and current position.
      * @param props - Vault address, wallet address, and optional chain ID
      * @returns Lifetime PnL data including realized and unrealized PnL in both native token and USD
+     * @throws {@link AugustHistoryUnavailableError} (`HISTORY_UNAVAILABLE`) when a
+     *   live position has no indexed deposits or withdrawals.
+     * @throws {@link AugustPriceUnavailableError} (`PRICE_UNAVAILABLE`) when the
+     *   vault's underlying asset has no USD price — the USD fields are never
+     *   computed from a stand-in price.
      */
     getVaultUserLifetimePnl(props: {
         vault: IAddress;