@augustdigital/sdk 4.27.3 → 5.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 August Digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -29,6 +29,9 @@ import { AugustSDK } from '@augustdigital/sdk';
 
 // Initialize with RPC providers
 const sdk = new AugustSDK({
+  // Required: a stable kebab-case slug identifying your application.
+  // See "App Name" below for what this is used for.
+  appName: 'acme-trader',
   providers: {
     1: 'https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY',
     42161: 'https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY',
@@ -58,6 +61,61 @@ const positions = await sdk.getVaultPositions({
 });
 ```
 
+### App Name
+
+`appName` is required on every `AugustSDK` constructor call. Pass a
+stable kebab-case slug identifying your application (e.g.
+`'acme-trader'`, `'my-defi-app'`):
+
+- **What it's used for.** August Digital tags outbound analytics events
+  with `app.name = <yourSlug>`. We use this to (a) reach out about
+  breaking changes that will affect you, (b) attribute error spikes to
+  the right consuming app, and (c) prioritize bug fixes by impact.
+- **What it is _not_.** It's not a secret, not a license key, not an
+  auth token, and despite the friendly name it's **not a display
+  label**. It's a self-issued identifier — pick a slug once and reuse
+  it across deployments.
+- **Constraints.** 3–64 characters, only `[a-zA-Z0-9._-]`. Use a slug
+  like `'acme-trader'`, **not** a display name like `'Acme Trader'`
+  (spaces and special characters will throw). The SDK throws
+  synchronously from the constructor if the value is missing or
+  invalid, so a wrong value fails loudly at integration time rather
+  than silently in production.
+
+```typescript
+// Will throw — appName is required.
+new AugustSDK({
+  providers: {
+    /* ... */
+  },
+  keys: {
+    /* ... */
+  },
+} as any);
+
+// Will throw — display name, not a slug. Use 'acme-trader' instead.
+new AugustSDK({
+  appName: 'Acme Trader',
+  providers: {
+    /* ... */
+  },
+  keys: {
+    /* ... */
+  },
+});
+
+// Correct.
+new AugustSDK({
+  appName: 'acme-trader',
+  providers: {
+    /* ... */
+  },
+  keys: {
+    /* ... */
+  },
+});
+```
+
 ## Architecture
 
 ```

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

@@ -1,2 +1,5 @@
+export declare function sanitizeString(input: string): string;
+export declare function sanitizeError(err: unknown): unknown;
+export declare function sanitizeForLogging(input: unknown, depth?: number): unknown;
 export declare function sanitizeArgs(args: unknown[]): Record<string, unknown>;
 export declare function sanitizeObject(obj: Record<string, unknown>, depth?: number): Record<string, unknown>;

package/lib/core/analytics/sanitize.js

@@ -1,22 +1,96 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeString = sanitizeString;
+exports.sanitizeError = sanitizeError;
+exports.sanitizeForLogging = sanitizeForLogging;
 exports.sanitizeArgs = sanitizeArgs;
 exports.sanitizeObject = sanitizeObject;
 const SENSITIVE_KEYS = [
     'apikey',
     'api_key',
     'apiKey',
+    'x-api-key',
     'password',
     'secret',
     'token',
     'bearer',
     'authorization',
+    'proxy-authorization',
+    'cookie',
+    'set-cookie',
     'privatekey',
     'private_key',
     'privateKey',
     'mnemonic',
     'seed',
 ];
+const STRING_REDACTION_PATTERNS = [
+    [/(authorization\s*[:=]\s*)(bearer|basic|token)\s+\S+/gi, '$1$2 [REDACTED]'],
+    [
+        /([?&](?:api[-_]?key|apikey|access[-_]?token|token|key|auth)=)[^&\s#]+/gi,
+        '$1[REDACTED]',
+    ],
+    [/(gateway\.thegraph\.com\/api\/)[A-Za-z0-9]{20,}(\/)/g, '$1[REDACTED]$2'],
+    [/eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, '[REDACTED_JWT]'],
+    [/\bnpm_[A-Za-z0-9]{30,}\b/g, '[REDACTED_NPM_TOKEN]'],
+    [
+        /(\b(?:api[-_]?key|apikey|password|secret|private[-_]?key|mnemonic|seed)\s*[:=]\s*)["']?[^\s"',;}&#]+["']?/gi,
+        '$1[REDACTED]',
+    ],
+];
+function sanitizeString(input) {
+    if (!input)
+        return input;
+    let out = input;
+    for (const [pattern, replacement] of STRING_REDACTION_PATTERNS) {
+        out = out.replace(pattern, replacement);
+    }
+    return out;
+}
+function sanitizeError(err) {
+    if (!(err instanceof Error))
+        return err;
+    const safe = Object.create(Object.getPrototypeOf(err));
+    for (const key of Object.getOwnPropertyNames(err)) {
+        const value = err[key];
+        if (key === 'message' && typeof value === 'string') {
+            safe[key] = sanitizeString(value);
+        }
+        else if (key === 'stack' && typeof value === 'string') {
+            safe[key] = sanitizeString(value);
+        }
+        else {
+            safe[key] = value;
+        }
+    }
+    if (!safe.message && typeof err.message === 'string') {
+        safe.message = sanitizeString(err.message);
+    }
+    if (!safe.stack && typeof err.stack === 'string') {
+        safe.stack = sanitizeString(err.stack);
+    }
+    safe.name = err.name;
+    return safe;
+}
+function sanitizeForLogging(input, depth = 0) {
+    if (input === null || input === undefined)
+        return input;
+    if (depth > 3)
+        return '[TRUNCATED]';
+    if (typeof input === 'string')
+        return sanitizeString(input);
+    if (typeof input === 'number' || typeof input === 'boolean')
+        return input;
+    if (input instanceof Error)
+        return sanitizeError(input);
+    if (Array.isArray(input)) {
+        return input.slice(0, 10).map((v) => sanitizeForLogging(v, depth + 1));
+    }
+    if (typeof input === 'object') {
+        return sanitizeObject(input, depth);
+    }
+    return `[${typeof input}]`;
+}
 function sanitizeArgs(args) {
     const sanitized = {};
     args.forEach((arg, index) => {

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

@@ -1,7 +1,7 @@
 import * as Sentry from '@sentry/browser';
 import { IEnv } from '../../types';
 import { IAnalyticsConfig } from './types';
-export declare function initializeSentry(config: IAnalyticsConfig, environment: IEnv, walletAddress?: string, apiKey?: string): void;
+export declare function initializeSentry(config: IAnalyticsConfig, environment: IEnv, walletAddress?: string, apiKey?: string, appName?: string): void;
 export declare function updateUser(walletAddress?: string, environment?: IEnv): void;
 export declare function clearUser(): void;
 export declare function isAnalyticsEnabled(): boolean;

package/lib/core/analytics/sentry.js

@@ -84,7 +84,7 @@ function safeSetUser(user) {
     catch {
     }
 }
-function initializeSentry(config, environment, walletAddress, apiKey) {
+function initializeSentry(config, environment, walletAddress, apiKey, appName) {
     if (config.enabled === false) {
         isEnabled = false;
         console.log('August SDK: Analytics disabled');
@@ -125,6 +125,9 @@ function initializeSentry(config, environment, walletAddress, apiKey) {
         updateUser(walletAddress, environment);
         safeSetTag('sdk', 'august-digital');
         safeSetTag('sdk.version', getSDKVersion());
+        if (appName) {
+            safeSetTag('app.name', appName);
+        }
         isInitialized = true;
         console.log('August SDK: Analytics initialized. Disable with { analytics: { enabled: false } }');
     }

package/lib/core/auth/verify.js

@@ -13,9 +13,14 @@ async function verifyInfuraKey(key) {
     return true;
 }
 async function verifyAugustKey(key) {
-    const verify = await (0, fetcher_1.fetchAugustWithKey)(key, core_1.WEBSERVER_ENDPOINTS.auth.verify);
-    if (verify.status === 200)
-        return true;
-    return false;
+    if (!key)
+        return false;
+    try {
+        const verify = await (0, fetcher_1.fetchAugustWithKey)(key, core_1.WEBSERVER_ENDPOINTS.auth.verify);
+        return verify.status === 200;
+    }
+    catch {
+        return false;
+    }
 }
 //# sourceMappingURL=verify.js.map

package/lib/core/base.class.d.ts

@@ -1,5 +1,6 @@
 import { ISolanaConfig, IAddress, IChainId, IEnv, IProvidersConfig, IWSMonitorHeaders } from '../types';
 import { IAnalyticsConfig } from './analytics';
+import { IVersionCheckConfig } from './version-check';
 interface IKeys {
     august?: string;
     graph?: string;
@@ -11,11 +12,13 @@ interface IMonitoring extends IWSMonitorHeaders {
     env?: IEnv;
 }
 export interface IAugustBase {
+    appName: string;
     providers?: IProvidersConfig;
     solana?: ISolanaConfig;
     keys: IKeys;
     monitoring?: IMonitoring;
     analytics?: IAnalyticsConfig;
+    versionCheck?: IVersionCheckConfig;
 }
 interface IActiveNetwork {
     chainId: IChainId;
@@ -27,7 +30,8 @@ export declare class AugustBase {
     authorized: boolean;
     activeNetwork?: IActiveNetwork;
     providers: IProvidersConfig;
-    constructor({ providers, keys, monitoring, analytics }: IAugustBase);
+    appName: string;
+    constructor({ appName, providers, keys, monitoring, analytics, versionCheck, }: IAugustBase);
     init(): Promise<void>;
     protected requireActiveNetwork(): IActiveNetwork;
     switchNetwork(chainId: IChainId): void;

package/lib/core/base.class.js

@@ -4,12 +4,28 @@ exports.AugustBase = void 0;
 const auth_1 = require("./auth");
 const logger_1 = require("./logger");
 const analytics_1 = require("./analytics");
+const version_check_1 = require("./version-check");
+function validateAppName(value) {
+    const docsHint = 'See https://docs.augustdigital.io/developers/typescript-sdk#app-name';
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`August SDK: \`appName\` is required. Pass a stable kebab-case slug identifying your application (e.g. "acme-trader"). ${docsHint}`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length < 3 || trimmed.length > 64) {
+        throw new Error(`August SDK: \`appName\` must be 3-64 characters (got ${trimmed.length}). ${docsHint}`);
+    }
+    if (!/^[a-zA-Z0-9._-]+$/.test(trimmed)) {
+        throw new Error(`August SDK: \`appName\` may only contain letters, digits, '.', '_' and '-' (got "${trimmed}"). Use a slug like "acme-trader", not a display name. ${docsHint}`);
+    }
+    return trimmed;
+}
 class AugustBase {
-    constructor({ providers = {}, keys, monitoring, analytics }) {
+    constructor({ appName, providers = {}, keys, monitoring, analytics, versionCheck, }) {
         this.monitoring = {
             'x-user-id': undefined,
             'x-environment': undefined,
         };
+        this.appName = validateAppName(appName);
         this.authorized = true;
         this.providers = providers;
         if (Object.keys(providers).length > 0) {
@@ -25,7 +41,8 @@ class AugustBase {
             'x-environment': environment,
         };
         logger_1.Logger.setDevMode(environment === 'DEV');
-        (0, analytics_1.initializeSentry)(analytics ?? { enabled: true }, environment, monitoring?.['x-user-id'], keys?.august);
+        (0, analytics_1.initializeSentry)(analytics ?? { enabled: true }, environment, monitoring?.['x-user-id'], keys?.august, this.appName);
+        (0, version_check_1.runVersionCheck)(versionCheck);
     }
     async init() {
         const [augustCheck] = await Promise.all([

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

@@ -0,0 +1,40 @@
+export type AugustErrorCode = 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED' | 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'UNKNOWN';
+export interface AugustErrorOptions {
+    cause?: unknown;
+    correlationId?: string;
+    context?: Record<string, unknown>;
+}
+export declare class AugustSDKError extends Error {
+    readonly code: AugustErrorCode;
+    readonly correlationId?: string;
+    readonly context?: Record<string, unknown>;
+    constructor(code: AugustErrorCode, message: string, options?: AugustErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+export declare class AugustAuthError extends AugustSDKError {
+    constructor(code: Extract<AugustErrorCode, 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED'>, message: string, options?: AugustErrorOptions);
+}
+export declare class AugustNetworkError extends AugustSDKError {
+    constructor(message: string, options?: AugustErrorOptions);
+}
+export declare class AugustTimeoutError extends AugustSDKError {
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number, options?: AugustErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+export declare class AugustValidationError extends AugustSDKError {
+    constructor(code: Extract<AugustErrorCode, 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS'>, message: string, options?: AugustErrorOptions);
+}
+export declare class AugustRateLimitError extends AugustSDKError {
+    readonly retryAfterMs?: number;
+    constructor(message: string, options?: AugustErrorOptions & {
+        retryAfterMs?: number;
+    });
+    toJSON(): Record<string, unknown>;
+}
+export declare class AugustServerError extends AugustSDKError {
+    readonly status: number;
+    constructor(status: number, message: string, options?: AugustErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+export declare function isAugustSDKError(err: unknown): err is AugustSDKError;

package/lib/core/errors/index.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AugustServerError = exports.AugustRateLimitError = exports.AugustValidationError = exports.AugustTimeoutError = exports.AugustNetworkError = exports.AugustAuthError = exports.AugustSDKError = void 0;
+exports.isAugustSDKError = isAugustSDKError;
+class AugustSDKError extends Error {
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = 'AugustSDKError';
+        this.code = code;
+        this.correlationId = options.correlationId;
+        this.context = options.context;
+        if (options.cause !== undefined) {
+            this.cause = options.cause;
+        }
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    toJSON() {
+        const out = {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+        };
+        if (this.correlationId !== undefined)
+            out.correlationId = this.correlationId;
+        if (this.context !== undefined)
+            out.context = this.context;
+        if (this.stack !== undefined)
+            out.stack = this.stack;
+        const cause = this.cause;
+        if (cause !== undefined) {
+            out.cause =
+                cause instanceof Error
+                    ? { name: cause.name, message: cause.message }
+                    : cause;
+        }
+        return out;
+    }
+}
+exports.AugustSDKError = AugustSDKError;
+class AugustAuthError extends AugustSDKError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'AugustAuthError';
+    }
+}
+exports.AugustAuthError = AugustAuthError;
+class AugustNetworkError extends AugustSDKError {
+    constructor(message, options) {
+        super('NETWORK_ERROR', message, options);
+        this.name = 'AugustNetworkError';
+    }
+}
+exports.AugustNetworkError = AugustNetworkError;
+class AugustTimeoutError extends AugustSDKError {
+    constructor(message, timeoutMs, options) {
+        super('TIMEOUT', message, options);
+        this.name = 'AugustTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+    toJSON() {
+        return { ...super.toJSON(), timeoutMs: this.timeoutMs };
+    }
+}
+exports.AugustTimeoutError = AugustTimeoutError;
+class AugustValidationError extends AugustSDKError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'AugustValidationError';
+    }
+}
+exports.AugustValidationError = AugustValidationError;
+class AugustRateLimitError extends AugustSDKError {
+    constructor(message, options) {
+        super('RATE_LIMITED', message, options);
+        this.name = 'AugustRateLimitError';
+        this.retryAfterMs = options?.retryAfterMs;
+    }
+    toJSON() {
+        const base = super.toJSON();
+        if (this.retryAfterMs !== undefined)
+            base.retryAfterMs = this.retryAfterMs;
+        return base;
+    }
+}
+exports.AugustRateLimitError = AugustRateLimitError;
+class AugustServerError extends AugustSDKError {
+    constructor(status, message, options) {
+        super('SERVER_ERROR', message, options);
+        this.name = 'AugustServerError';
+        this.status = status;
+    }
+    toJSON() {
+        return { ...super.toJSON(), status: this.status };
+    }
+}
+exports.AugustServerError = AugustServerError;
+function isAugustSDKError(err) {
+    return (err instanceof AugustSDKError ||
+        (err instanceof Error &&
+            typeof err.code === 'string' &&
+            err.name.startsWith('August')));
+}
+//# sourceMappingURL=index.js.map

package/lib/core/fetcher.d.ts

@@ -7,6 +7,8 @@ export type IFetchAugustOptions = {
     headers?: Record<string, string>;
     data?: any;
     server?: keyof typeof WEBSERVER_URL;
+    signal?: AbortSignal;
+    timeoutMs?: number;
     override?: boolean;
 };
 export declare const CACHE: LRUCache<string, any, unknown>;