@augustdigital/sdk 9.5.0 → 9.7.0

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;

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.7.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.7.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) {
@@ -14,17 +15,20 @@ async function verifyInfuraKey(key) {
 }
 async function verifyAugustKey(key) {
     // Fast path: no key means no verification possible. Returning false here
-    // preserves the historical contract (`init()` throws a generic "API key is invalid")
-    // and avoids letting an AUTH_MISSING_KEY error bubble up from the fetcher.
+    // preserves the historical contract (`init()` throws a generic "API key is
+    // invalid") and saves a request the backend would reject with a 401.
     if (!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.d.ts

@@ -63,7 +63,13 @@ export interface IAugustBase {
     providers?: IProvidersConfig;
     solana?: ISolanaConfig;
     stellar?: IStellarConfig;
-    keys: IKeys;
+    /**
+     * Provider keys. Optional: vault reads and vault-linked sub-account reads
+     * work without an August key. Supply `august` for admin and curator methods,
+     * for authenticated-user reads such as `getDiscountFactors`, and for
+     * sub-account reads where the subaccount is not linked to a vault.
+     */
+    keys?: IKeys;
     monitoring?: IMonitoring;
     /** Analytics configuration. Enabled by default (opt-out model). */
     analytics?: IAnalyticsConfig;
@@ -149,6 +155,7 @@ export declare class AugustBase {
     constructor({ appName, providers, keys, monitoring, analytics, versionCheck, timeoutMs, publicApiBaseUrl, attribution, }: IAugustBase);
     /**
      * Verify the configured August API key and mark this instance as authorized.
+     * Only for SDKs built with `keys.august`; a keyless SDK skips `init()`.
      * @throws Error when `keys.august` is missing or rejected by the API.
      */
     init(): Promise<void>;

package/lib/core/base.class.js

@@ -46,7 +46,9 @@ class AugustBase {
                 rpcUrl: Object.values(providers)[0],
             };
         }
-        this.keys = keys;
+        // Default to an empty set so the api and sub-account modules can read
+        // `this.keys.august` (undefined) instead of throwing on a keyless SDK.
+        this.keys = keys ?? {};
         // Set environment (defaults to PROD for safety)
         const environment = monitoring?.env || monitoring?.['x-environment'] || 'PROD';
         this.monitoring = {
@@ -71,6 +73,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.
@@ -88,6 +93,7 @@ class AugustBase {
     }
     /**
      * Verify the configured August API key and mark this instance as authorized.
+     * Only for SDKs built with `keys.august`; a keyless SDK skips `init()`.
      * @throws Error when `keys.august` is missing or rejected by the API.
      */
     async init() {

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;