@augustdigital/sdk 9.4.0 → 9.6.0

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

@@ -28,7 +28,7 @@ declare class EVMAdapter {
      * Get the normalized ethers-compatible signer
      * Converts viem WalletClient to ethers Signer if needed
      */
-    private getSigner;
+    private _getSigner;
     vaultApprove(options: IContractWriteOptions): Promise<string>;
     /**
      * Approve a vault to spend a deposit token, returning a discriminated

package/lib/adapters/evm/index.js

@@ -49,7 +49,7 @@ class EVMAdapter {
      * Get the normalized ethers-compatible signer
      * Converts viem WalletClient to ethers Signer if needed
      */
-    async getSigner() {
+    async _getSigner() {
         if (!this.rawSigner) {
             throw new Error('No signer provided');
         }
@@ -65,7 +65,7 @@ class EVMAdapter {
     }
     // Core EVM operations
     async vaultApprove(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, write_actions_1.vaultApprove)(signer, options);
     }
     /**
@@ -86,7 +86,7 @@ class EVMAdapter {
      * ```
      */
     async approve(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, write_actions_1.approve)(signer, options);
     }
     /**
@@ -112,7 +112,7 @@ class EVMAdapter {
      * ```
      */
     async vaultAllowance(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, read_actions_1.vaultAllowance)(signer, options);
     }
     // Vault operations (delegate to modules)
@@ -143,7 +143,7 @@ class EVMAdapter {
      * ```
      */
     async vaultDeposit(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, write_actions_1.vaultDeposit)(signer, options);
     }
     /**
@@ -171,7 +171,7 @@ class EVMAdapter {
      * ```
      */
     async vaultRequestRedeem(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, write_actions_1.vaultRequestRedeem)(signer, options);
     }
     /**
@@ -197,7 +197,7 @@ class EVMAdapter {
      * ```
      */
     async depositNative(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, write_actions_1.depositNative)(signer, options);
     }
     /**
@@ -227,7 +227,7 @@ class EVMAdapter {
      * ```
      */
     async swapAndDeposit(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, write_actions_1.swapAndDeposit)(signer, options);
     }
     /**
@@ -239,7 +239,7 @@ class EVMAdapter {
      * @returns The transaction hash of the `deposit` call.
      */
     async depositViaSwapRouter(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, write_actions_1.depositViaSwapRouter)(signer, options);
     }
     /**
@@ -251,7 +251,7 @@ class EVMAdapter {
      * @returns The transaction hash of the `depositNativeToken` call.
      */
     async depositNativeViaSwapRouter(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, write_actions_1.depositNativeViaSwapRouter)(signer, options);
     }
     /**
@@ -277,7 +277,7 @@ class EVMAdapter {
      * ```
      */
     async swapRouterDeposit(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, write_actions_1.swapRouterDeposit)(signer, options);
     }
     /**
@@ -296,7 +296,7 @@ class EVMAdapter {
      * ```
      */
     async getSwapRouterDepositResult(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, swap_router_1.getSwapRouterDepositResult)(signer, options);
     }
     /**
@@ -329,7 +329,7 @@ class EVMAdapter {
      * ```
      */
     async vaultRedeem(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, write_actions_1.vaultRedeem)(signer, options);
     }
     /**
@@ -362,23 +362,23 @@ class EVMAdapter {
      * ```
      */
     async claimWithdrawal(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, write_actions_1.claimWithdrawal)(signer, options);
     }
     async sendersWhitelistAddress(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, read_actions_1.sendersWhitelistAddress)(signer, options);
     }
     async isWhitelisted(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, read_actions_1.isWhitelisted)(signer, options);
     }
     async getDeposited(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, read_actions_1.getDeposited)(signer, options);
     }
     async getRemainingAllocations(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, read_actions_1.getRemainingAllocations)(signer, options);
     }
     /**
@@ -397,7 +397,7 @@ class EVMAdapter {
      * ```
      */
     async previewDeposit(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, read_actions_1.previewDeposit)(signer, options);
     }
     /**
@@ -415,7 +415,7 @@ class EVMAdapter {
      * ```
      */
     async previewRedeem(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, read_actions_1.previewRedeem)(signer, options);
     }
     /**
@@ -430,7 +430,7 @@ class EVMAdapter {
      * ```
      */
     async allowance(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, read_actions_1.allowance)(signer, options);
     }
     /**
@@ -444,7 +444,7 @@ class EVMAdapter {
      * ```
      */
     async balanceOf(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, read_actions_1.balanceOf)(signer, options);
     }
     /**
@@ -459,7 +459,7 @@ class EVMAdapter {
      * ```
      */
     async maxDeposit(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, read_actions_1.maxDeposit)(signer, options);
     }
     /**
@@ -475,7 +475,7 @@ class EVMAdapter {
      * ```
      */
     async getIdleLiquidity(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, read_actions_1.getIdleLiquidity)(signer, options);
     }
     /**
@@ -489,7 +489,7 @@ class EVMAdapter {
      * ```
      */
     async lagDuration(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, read_actions_1.lagDuration)(signer, options);
     }
     /**
@@ -504,7 +504,7 @@ class EVMAdapter {
      * ```
      */
     async getWithdrawalEpoch(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, read_actions_1.getWithdrawalEpoch)(signer, options);
     }
     /**
@@ -521,7 +521,7 @@ class EVMAdapter {
      * ```
      */
     async getBurnableAmountByReceiver(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, read_actions_1.getBurnableAmountByReceiver)(signer, options);
     }
     /**
@@ -536,7 +536,7 @@ class EVMAdapter {
      * ```
      */
     async getRequirementByDate(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, read_actions_1.getRequirementByDate)(signer, options);
     }
     /**
@@ -551,7 +551,7 @@ class EVMAdapter {
      * ```
      */
     async getScheduledTransactionsByDate(options) {
-        const signer = await this.getSigner();
+        const signer = await this._getSigner();
         return (0, read_actions_1.getScheduledTransactionsByDate)(signer, options);
     }
 }

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

@@ -29,7 +29,7 @@ const errors_1 = require("../errors");
  *   characters, or is shaped like an EVM address.
  */
 function validateAppName(value) {
-    const docsHint = 'See https://docs.augustdigital.io/developers/typescript-sdk#app-name';
+    const docsHint = 'See https://docs.augustdigital.io/developers/typescript-sdk/javascript-sdk#app-name';
     if (typeof value !== 'string' || value.trim().length === 0) {
         throw new errors_1.AugustValidationError('INVALID_INPUT', `August SDK: \`appName\` is required. Pass a stable kebab-case slug identifying your application (e.g. "acme-trader"). ${docsHint}`);
     }

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

@@ -3,3 +3,13 @@
  * This is an internal constant - not exposed to SDK users.
  */
 export declare const SENTRY_DSN = "https://ca39246016d0b43154f0640314cbd3b5@o4507215496609792.ingest.de.sentry.io/4511864614813776";
+/**
+ * `appName` slugs of applications August/Upshift operate themselves.
+ *
+ * Traffic from these is tagged `partner.tier: 'internal'` so that
+ * `partner.tier:unverified` in Sentry already means "external integrator"
+ * before the backend verification endpoint exists. Anything not listed stays
+ * `unverified`; the future verified flow adds a `verified` tier alongside
+ * rather than replacing this list.
+ */
+export declare const FIRST_PARTY_APP_NAMES: ReadonlySet<string>;

package/lib/core/analytics/constants.js

@@ -1,9 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SENTRY_DSN = void 0;
+exports.FIRST_PARTY_APP_NAMES = exports.SENTRY_DSN = void 0;
 /**
  * Sentry DSN for SDK analytics.
  * This is an internal constant - not exposed to SDK users.
  */
 exports.SENTRY_DSN = 'https://ca39246016d0b43154f0640314cbd3b5@o4507215496609792.ingest.de.sentry.io/4511864614813776';
+/**
+ * `appName` slugs of applications August/Upshift operate themselves.
+ *
+ * Traffic from these is tagged `partner.tier: 'internal'` so that
+ * `partner.tier:unverified` in Sentry already means "external integrator"
+ * before the backend verification endpoint exists. Anything not listed stays
+ * `unverified`; the future verified flow adds a `verified` tier alongside
+ * rather than replacing this list.
+ */
+exports.FIRST_PARTY_APP_NAMES = new Set([
+    'upshift-web-app',
+    'upshift-earn',
+    'upshift-prime',
+    'august-cli',
+    'august-mcp',
+]);
 //# sourceMappingURL=constants.js.map

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

@@ -2,9 +2,10 @@
  * Analytics module for SDK usage tracking via Sentry.
  *
  * Features:
- * - User identification (API key hash, wallet, fingerprint, session)
- * - Method call tracking with timing
- * - Cache hit/miss rate monitoring
+ * - User identification (API key hash, wallet, domain, fingerprint, session)
+ * - Method call tracking with timing, classified by {@link METHOD_CATEGORIES}
+ * - Application attribution (`app.name`, `partner.id`, `partner.tier`,
+ *   `sdk.surface`) on every event and span
  * - API response time tracking
  * - Chain/network usage distribution
  *
@@ -12,12 +13,14 @@
  * ```typescript
  * // Analytics enabled by default
  * const sdk = new AugustSDK({
+ *   appName: 'acme-trader',
  *   providers: { 1: 'https://...' },
  *   keys: { august: '...' },
  * });
  *
  * // Opt-out of analytics
  * const sdk = new AugustSDK({
+ *   appName: 'acme-trader',
  *   providers: { 1: 'https://...' },
  *   keys: { august: '...' },
  *   analytics: { enabled: false },
@@ -29,7 +32,7 @@ export { hashApiKey, getSessionId, generateFingerprint, createUserIdentity, getU
 export { initializeSentry, updateUser, clearUser, isAnalyticsEnabled, getSentry, resetAnalytics, captureSdkException, } from './sentry';
 export { getSentrySDK, getSentryRuntime } from './sentry-runtime';
 export { readEnv, isAnalyticsDisabledViaEnv, isAnalyticsForcedOnViaEnv, isNodeDevOrTestEnv, } from './env';
-export { trackApiCall, trackNetworkSwitch, getCacheStats, resetCacheStats, } from './metrics';
+export { trackApiCall, trackNetworkSwitch, trackKeyVerification, getCacheStats, resetCacheStats, } from './metrics';
 export { sanitizeArgs, sanitizeObject, computeArgShape } from './sanitize';
 export { withMethodTracking, withSyncMethodTracking, instrumentClass, } from './instrumentation';
 export { METHOD_CATEGORIES, getMethodCategory, type MethodCategory, } from './method-taxonomy';

package/lib/core/analytics/index.js

@@ -3,9 +3,10 @@
  * Analytics module for SDK usage tracking via Sentry.
  *
  * Features:
- * - User identification (API key hash, wallet, fingerprint, session)
- * - Method call tracking with timing
- * - Cache hit/miss rate monitoring
+ * - User identification (API key hash, wallet, domain, fingerprint, session)
+ * - Method call tracking with timing, classified by {@link METHOD_CATEGORIES}
+ * - Application attribution (`app.name`, `partner.id`, `partner.tier`,
+ *   `sdk.surface`) on every event and span
  * - API response time tracking
  * - Chain/network usage distribution
  *
@@ -13,12 +14,14 @@
  * ```typescript
  * // Analytics enabled by default
  * const sdk = new AugustSDK({
+ *   appName: 'acme-trader',
  *   providers: { 1: 'https://...' },
  *   keys: { august: '...' },
  * });
  *
  * // Opt-out of analytics
  * const sdk = new AugustSDK({
+ *   appName: 'acme-trader',
  *   providers: { 1: 'https://...' },
  *   keys: { august: '...' },
  *   analytics: { enabled: false },
@@ -26,7 +29,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.chainIdToTagValue = exports.getMethodCategory = exports.METHOD_CATEGORIES = exports.instrumentClass = exports.withSyncMethodTracking = exports.withMethodTracking = exports.computeArgShape = exports.sanitizeObject = exports.sanitizeArgs = exports.resetCacheStats = exports.getCacheStats = exports.trackNetworkSwitch = exports.trackApiCall = exports.isNodeDevOrTestEnv = exports.isAnalyticsForcedOnViaEnv = exports.isAnalyticsDisabledViaEnv = exports.readEnv = exports.getSentryRuntime = exports.getSentrySDK = exports.captureSdkException = exports.resetAnalytics = exports.getSentry = exports.isAnalyticsEnabled = exports.clearUser = exports.updateUser = exports.initializeSentry = exports.getUserId = exports.createUserIdentity = exports.generateFingerprint = exports.getSessionId = exports.hashApiKey = void 0;
+exports.chainIdToTagValue = exports.getMethodCategory = exports.METHOD_CATEGORIES = exports.instrumentClass = exports.withSyncMethodTracking = exports.withMethodTracking = exports.computeArgShape = exports.sanitizeObject = exports.sanitizeArgs = exports.resetCacheStats = exports.getCacheStats = exports.trackKeyVerification = exports.trackNetworkSwitch = exports.trackApiCall = exports.isNodeDevOrTestEnv = exports.isAnalyticsForcedOnViaEnv = exports.isAnalyticsDisabledViaEnv = exports.readEnv = exports.getSentryRuntime = exports.getSentrySDK = exports.captureSdkException = exports.resetAnalytics = exports.getSentry = exports.isAnalyticsEnabled = exports.clearUser = exports.updateUser = exports.initializeSentry = exports.getUserId = exports.createUserIdentity = exports.generateFingerprint = exports.getSessionId = exports.hashApiKey = void 0;
 // User identity utilities
 var user_identity_1 = require("./user-identity");
 Object.defineProperty(exports, "hashApiKey", { enumerable: true, get: function () { return user_identity_1.hashApiKey; } });
@@ -57,6 +60,7 @@ Object.defineProperty(exports, "isNodeDevOrTestEnv", { enumerable: true, get: fu
 var metrics_1 = require("./metrics");
 Object.defineProperty(exports, "trackApiCall", { enumerable: true, get: function () { return metrics_1.trackApiCall; } });
 Object.defineProperty(exports, "trackNetworkSwitch", { enumerable: true, get: function () { return metrics_1.trackNetworkSwitch; } });
+Object.defineProperty(exports, "trackKeyVerification", { enumerable: true, get: function () { return metrics_1.trackKeyVerification; } });
 Object.defineProperty(exports, "getCacheStats", { enumerable: true, get: function () { return metrics_1.getCacheStats; } });
 Object.defineProperty(exports, "resetCacheStats", { enumerable: true, get: function () { return metrics_1.resetCacheStats; } });
 // Sanitization utilities

package/lib/core/analytics/instrumentation.js

@@ -40,6 +40,10 @@ function withMethodTracking(methodName, method, getChainId) {
                 op: 'sdk.method',
                 name: methodName,
                 attributes: {
+                    // Scope tags only reach the root span in Sentry's span dataset;
+                    // child spans need the identity copied on as attributes or they
+                    // cannot be filtered by app or partner.
+                    ...(0, sentry_1.getSpanAttributes)(),
                     chainId: chainId?.toString() || 'unknown',
                     'sdk.chain': (0, chain_name_1.chainIdToTagValue)(chainId),
                     'sdk.category': category,
@@ -222,12 +226,12 @@ function trackSyncMethodCall(methodName, metrics, args) {
         // Measurements omitted: sync methods have no span of their own, so setMeasurement
         // would attach to whatever parent transaction happens to be active on the scope,
         // overwriting its counters. The breadcrumb above already captures success/failure.
+        // `sdk.category` and `sdk.chain` stay off the global scope: concurrent sync
+        // calls would race on them and stamp stale values onto unrelated events (the
+        // breadcrumb above carries both per call). `sdk.last_chainId` stays because
+        // `isMutedChainEvent` in sentry.ts reads it to drop muted-chain events.
         sdk.setTag('sdk.last_sync_method', methodName);
-        if (metrics.category) {
-            sdk.setTag('sdk.category', metrics.category);
-        }
         if (metrics.chainId !== undefined) {
-            sdk.setTag('sdk.chain', (0, chain_name_1.chainIdToTagValue)(metrics.chainId));
             sdk.setTag('sdk.last_chainId', metrics.chainId.toString());
         }
     }

package/lib/core/analytics/method-taxonomy.js

@@ -64,6 +64,7 @@ exports.METHOD_CATEGORIES = {
     getVaultWithdrawals: 'read.redemption',
     getWithdrawalRequestsWithStatus: 'read.redemption',
     previewRedemption: 'read.redemption',
+    previewRwaRedemption: 'read.redemption',
     getBurnableAmountByReceiver: 'read.redemption',
     getRequirementByDate: 'read.redemption',
     getScheduledTransactionsByDate: 'read.redemption',
@@ -94,6 +95,7 @@ exports.METHOD_CATEGORIES = {
     // sees program-targeting calls instead of dropping them into 'unknown'.
     getProgram: 'read.solana',
     getProgramId: 'read.solana',
+    setWalletProvider: 'network',
     // submitTransaction broadcasts a signed Soroban tx — it mutates on-chain
     // state and belongs in the write bucket even though Stellar adapter call
     // shape mirrors the read helpers (returns a hash, takes signed XDR).
@@ -102,8 +104,19 @@ exports.METHOD_CATEGORIES = {
     // convertToShares is a read-only Soroban simulation despite its mutative-
     // sounding name — runs through queryContract, no broadcast.
     convertToShares: 'read.stellar',
+    // Offline helpers on the public adapter surface, classified under the
+    // chain's read bucket like getProgram/getProgramId above rather than
+    // leaking into 'unknown'.
+    isStellarAddress: 'read.stellar',
+    getExplorerLink: 'read.stellar',
     getEmberVaults: 'read.sui',
     getEmberTVL: 'read.sui',
+    convertFromE9: 'read.sui',
+    calculateUtilization: 'read.sui',
+    isSuiAddress: 'read.sui',
+    isSuiVault: 'read.sui',
+    transformEmberVaultToIVault: 'read.sui',
+    transformEmberVaultsToIVaults: 'read.sui',
     vaultAllowance: 'read.evm',
     sendersWhitelistAddress: 'read.evm',
     isWhitelisted: 'read.evm',

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

@@ -1,11 +1,3 @@
-/**
- * Aggregated cache statistics for monitoring.
- */
-declare let cacheStats: {
-    hits: number;
-    misses: number;
-    sets: number;
-};
 /**
  * Track API response times and status.
  *
@@ -23,11 +15,34 @@ export declare function trackApiCall(endpoint: string, method: string, startTime
  */
 export declare function trackNetworkSwitch(chainId: number): void;
 /**
- * Get current cache statistics.
+ * Track the outcome of an API-key verification check (e.g. `verifyAugustKey`).
+ * Records success/failure as a breadcrumb and a low-cardinality tag so
+ * verification failures are visible in the dashboard without leaking the key
+ * itself — callers must never pass the raw key value.
+ *
+ * @param keyType - Which key was verified (e.g. `'august'`)
+ * @param success - Whether the key was accepted
+ */
+export declare function trackKeyVerification(keyType: string, success: boolean): void;
+declare let cacheStats: {
+    hits: number;
+    misses: number;
+    sets: number;
+};
+/**
+ * Cache statistics snapshot. The SDK never recorded cache hits, misses, or
+ * sets, so every field is always `0`.
+ *
+ * @deprecated Always returns zeros. Kept only for API compatibility and will
+ * be removed in the next major release; there is no replacement.
  */
 export declare function getCacheStats(): typeof cacheStats;
 /**
- * Reset cache statistics (useful for testing).
+ * Reset the cache statistics snapshot to zeros. The SDK never records any, so
+ * this has no observable effect.
+ *
+ * @deprecated Has no effect. Kept only for API compatibility and will be
+ * removed in the next major release; there is no replacement.
  */
 export declare function resetCacheStats(): void;
 export {};

package/lib/core/analytics/metrics.js

@@ -2,19 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.trackApiCall = trackApiCall;
 exports.trackNetworkSwitch = trackNetworkSwitch;
+exports.trackKeyVerification = trackKeyVerification;
 exports.getCacheStats = getCacheStats;
 exports.resetCacheStats = resetCacheStats;
 const chain_name_1 = require("./chain-name");
 const sentry_runtime_1 = require("./sentry-runtime");
 const sentry_1 = require("./sentry");
-/**
- * Aggregated cache statistics for monitoring.
- */
-let cacheStats = {
-    hits: 0,
-    misses: 0,
-    sets: 0,
-};
 /**
  * Track API response times and status.
  *
@@ -47,11 +40,7 @@ function trackApiCall(endpoint, method, startTime, status, server) {
                 server,
             },
         });
-        // Set measurement for performance tracking
         sdk.setMeasurement('api.duration', duration, 'millisecond');
-        // Update tags for filtering
-        sdk.setTag('api.last_endpoint', normalizedEndpoint);
-        sdk.setTag('api.server', server);
     }
     catch {
         // Silently fail - analytics should never break SDK
@@ -76,13 +65,41 @@ function trackNetworkSwitch(chainId) {
             level: 'info',
             data: { chainId, chain: chainLabel },
         });
-        sdk.setTag('active.chainId', chainId.toString());
         sdk.setTag('sdk.chain', chainLabel);
     }
     catch {
         // Silently fail - analytics should never break SDK
     }
 }
+/**
+ * Track the outcome of an API-key verification check (e.g. `verifyAugustKey`).
+ * Records success/failure as a breadcrumb and a low-cardinality tag so
+ * verification failures are visible in the dashboard without leaking the key
+ * itself — callers must never pass the raw key value.
+ *
+ * @param keyType - Which key was verified (e.g. `'august'`)
+ * @param success - Whether the key was accepted
+ */
+function trackKeyVerification(keyType, success) {
+    if (!(0, sentry_1.isAnalyticsEnabled)())
+        return;
+    try {
+        const sdk = (0, sentry_runtime_1.getSentrySDK)();
+        if (!sdk)
+            return;
+        sdk.addBreadcrumb({
+            category: 'auth.verify',
+            message: `${keyType} key verification ${success ? 'succeeded' : 'failed'}`,
+            level: success ? 'info' : 'warning',
+            data: { keyType, success },
+        });
+        sdk.setTag('auth.last_verified_key_type', keyType);
+        sdk.setTag('auth.last_verification_result', success ? 'success' : 'failure');
+    }
+    catch {
+        // Silently fail - analytics should never break SDK
+    }
+}
 /**
  * Normalize endpoint URLs for aggregation.
  * Replaces dynamic segments (addresses, IDs) with placeholders.
@@ -101,14 +118,23 @@ function normalizeEndpoint(endpoint) {
         // Replace numeric IDs in paths
         .replace(/\/\d+(?=\/|$)/g, '/:id'));
 }
+let cacheStats = { hits: 0, misses: 0, sets: 0 };
 /**
- * Get current cache statistics.
+ * Cache statistics snapshot. The SDK never recorded cache hits, misses, or
+ * sets, so every field is always `0`.
+ *
+ * @deprecated Always returns zeros. Kept only for API compatibility and will
+ * be removed in the next major release; there is no replacement.
  */
 function getCacheStats() {
     return { ...cacheStats };
 }
 /**
- * Reset cache statistics (useful for testing).
+ * Reset the cache statistics snapshot to zeros. The SDK never records any, so
+ * this has no observable effect.
+ *
+ * @deprecated Has no effect. Kept only for API compatibility and will be
+ * removed in the next major release; there is no replacement.
  */
 function resetCacheStats() {
     cacheStats = { hits: 0, misses: 0, sets: 0 };

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

@@ -1,6 +1,15 @@
 import type * as Sentry from '@sentry/browser';
 import type { IEnv } from '../../types';
 import type { IAnalyticsConfig } from './types';
+/**
+ * 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
+ */
+export declare function getSDKVersion(): string;
 /**
  * Clear the error dedupe bookkeeping. Test-only — the rate limiter is process
  * lifetime state and would otherwise leak between test cases.
@@ -19,7 +28,8 @@ export declare function resetErrorDedupe(): void;
  * 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:
@@ -51,6 +61,16 @@ export declare function clearUser(): void;
  * Check if analytics is enabled and initialized.
  */
 export declare function isAnalyticsEnabled(): boolean;
+/**
+ * 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
+ */
+export declare function getSpanAttributes(): Readonly<Record<string, string>>;
 /**
  * Get the current Sentry instance for advanced usage.
  * Returns null if analytics is disabled.
@@ -67,12 +87,13 @@ export declare function resetAnalytics(): void;
  * 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).
  */
 export declare function captureSdkException(error: unknown, options?: {
-    surface?: 'cli' | 'sdk' | 'react' | string;
+    surface?: 'cli' | 'mcp' | 'sdk' | 'react' | string;
     tags?: Record<string, string>;
     extra?: Record<string, unknown>;
     flushTimeoutMs?: number;