@augustdigital/sdk 8.26.0 → 9.0.0

package/lib/core/analytics/app-name.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Validate an `appName` slug at SDK boundary points (the `AugustSDK`
+ * constructor and the standalone {@link initializeSentry} entry point).
+ *
+ * Rules (kept intentionally narrow so the value is safe to use as a Sentry
+ * tag, an HTTP header value, and a filesystem-safe identifier — this is
+ * why we accept slugs only, not display names):
+ *  - non-empty after trim
+ *  - 3..64 characters
+ *  - only `[a-zA-Z0-9._-]`
+ *  - not shaped like an EVM address (`0x` + 40 hex chars) — an address
+ *    passes the character rules but is a high-cardinality wallet
+ *    identifier, not an application name. This also catches callers of
+ *    `initializeSentry` still passing the pre-v9 positional argument
+ *    order, where a wallet address occupied the slot `appName` now holds.
+ *
+ * Throws a descriptive `AugustValidationError` (code `INVALID_INPUT`) that
+ * names the failed rule and includes a remediation hint pointing at the
+ * docs link.
+ *
+ * @param value - The candidate app name, as received from the caller.
+ * @returns The trimmed, validated slug.
+ * @throws AugustValidationError when the value is missing, empty,
+ *   mis-typed, out of the 3–64 length range, contains disallowed
+ *   characters, or is shaped like an EVM address.
+ */
+export declare function validateAppName(value: unknown): string;

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

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAppName = validateAppName;
+const errors_1 = require("../errors");
+/**
+ * Validate an `appName` slug at SDK boundary points (the `AugustSDK`
+ * constructor and the standalone {@link initializeSentry} entry point).
+ *
+ * Rules (kept intentionally narrow so the value is safe to use as a Sentry
+ * tag, an HTTP header value, and a filesystem-safe identifier — this is
+ * why we accept slugs only, not display names):
+ *  - non-empty after trim
+ *  - 3..64 characters
+ *  - only `[a-zA-Z0-9._-]`
+ *  - not shaped like an EVM address (`0x` + 40 hex chars) — an address
+ *    passes the character rules but is a high-cardinality wallet
+ *    identifier, not an application name. This also catches callers of
+ *    `initializeSentry` still passing the pre-v9 positional argument
+ *    order, where a wallet address occupied the slot `appName` now holds.
+ *
+ * Throws a descriptive `AugustValidationError` (code `INVALID_INPUT`) that
+ * names the failed rule and includes a remediation hint pointing at the
+ * docs link.
+ *
+ * @param value - The candidate app name, as received from the caller.
+ * @returns The trimmed, validated slug.
+ * @throws AugustValidationError when the value is missing, empty,
+ *   mis-typed, out of the 3–64 length range, contains disallowed
+ *   characters, or is shaped like an EVM address.
+ */
+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 errors_1.AugustValidationError('INVALID_INPUT', `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 errors_1.AugustValidationError('INVALID_INPUT', `August SDK: \`appName\` must be 3-64 characters (got ${trimmed.length}). ${docsHint}`);
+    }
+    if (!/^[a-zA-Z0-9._-]+$/.test(trimmed)) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', `August SDK: \`appName\` may only contain letters, digits, '.', '_' and '-' (got "${trimmed}"). Use a slug like "acme-trader", not a display name. ${docsHint}`);
+    }
+    if (/^0x[0-9a-fA-F]{40}$/.test(trimmed)) {
+        throw new errors_1.AugustValidationError('INVALID_INPUT', `August SDK: \`appName\` looks like a wallet address ("${trimmed}"). Pass an application slug like "acme-trader" — if you are calling initializeSentry directly, note that since v9 the argument order is (config, environment, appName, walletAddress?, apiKey?). ${docsHint}`);
+    }
+    return trimmed;
+}
+//# sourceMappingURL=app-name.js.map

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

@@ -12,16 +12,28 @@ export declare function resetErrorDedupe(): void;
  * Initialize Sentry with SDK-specific configuration. Idempotent: re-calls
  * only refresh user identity and the cached API-key hash.
  *
+ * Breaking change in v9: `appName` moved from the optional fifth parameter
+ * to the required third parameter, so every telemetry stream carries an
+ * application identity (the `AugustSDK` constructor has required it since
+ * v5). Callers on the old positional order get a synchronous validation
+ * error rather than silently anonymous events.
+ *
  * @param config - Analytics configuration. Pass `tracesSampleRate` to
  *   override the default of `0.1`.
  * @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:
+ *   3–64 chars, `[a-zA-Z0-9._-]` only, and not an EVM address — the same
+ *   rules the `AugustSDK` constructor enforces.
  * @param walletAddress - Optional wallet address for user identification.
  * @param apiKey - Optional API key (hashed for identification).
- * @param appName - Optional app-name slug. Set as the global `app.name`
- *   tag on every event; falls back to `'unverified:anonymous'` when
- *   omitted.
+ * @throws AugustValidationError (code `INVALID_INPUT`) when `appName` is
+ *   missing, empty, mis-typed, out of the allowed length range, contains
+ *   disallowed characters, or is shaped like an EVM address. Thrown before
+ *   any analytics state mutates, even when analytics would be disabled by
+ *   config or environment gates.
  */
-export declare function initializeSentry(config: IAnalyticsConfig, environment: IEnv, walletAddress?: string, apiKey?: string, appName?: string): void;
+export declare function initializeSentry(config: IAnalyticsConfig, environment: IEnv, appName: string, walletAddress?: string, apiKey?: string): void;
 /**
  * Update the current user identity in Sentry.
  * Called when wallet address changes.

package/lib/core/analytics/sentry.js

@@ -9,6 +9,7 @@ exports.getSentry = getSentry;
 exports.resetAnalytics = resetAnalytics;
 exports.captureSdkException = captureSdkException;
 const logger_1 = require("../logger");
+const app_name_1 = require("./app-name");
 const constants_1 = require("./constants");
 const env_1 = require("./env");
 const sentry_runtime_1 = require("./sentry-runtime");
@@ -305,16 +306,32 @@ function createSentrySink() {
  * Initialize Sentry with SDK-specific configuration. Idempotent: re-calls
  * only refresh user identity and the cached API-key hash.
  *
+ * Breaking change in v9: `appName` moved from the optional fifth parameter
+ * to the required third parameter, so every telemetry stream carries an
+ * application identity (the `AugustSDK` constructor has required it since
+ * v5). Callers on the old positional order get a synchronous validation
+ * error rather than silently anonymous events.
+ *
  * @param config - Analytics configuration. Pass `tracesSampleRate` to
  *   override the default of `0.1`.
  * @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:
+ *   3–64 chars, `[a-zA-Z0-9._-]` only, and not an EVM address — the same
+ *   rules the `AugustSDK` constructor enforces.
  * @param walletAddress - Optional wallet address for user identification.
  * @param apiKey - Optional API key (hashed for identification).
- * @param appName - Optional app-name slug. Set as the global `app.name`
- *   tag on every event; falls back to `'unverified:anonymous'` when
- *   omitted.
+ * @throws AugustValidationError (code `INVALID_INPUT`) when `appName` is
+ *   missing, empty, mis-typed, out of the allowed length range, contains
+ *   disallowed characters, or is shaped like an EVM address. Thrown before
+ *   any analytics state mutates, even when analytics would be disabled by
+ *   config or environment gates.
  */
-function initializeSentry(config, environment, walletAddress, apiKey, appName) {
+function initializeSentry(config, environment, appName, walletAddress, apiKey) {
+    // Enforce the identity contract before anything else — including the
+    // idempotency short-circuit and the disable gates — so a bad appName is
+    // equally loud on every call path and in every environment.
+    const validatedAppName = (0, app_name_1.validateAppName)(appName);
     // SDK construction runs this multiple times (base + adapter constructors).
     // Short-circuit so the disable-reason logs only once per process.
     if (isInitialized) {
@@ -473,11 +490,9 @@ function initializeSentry(config, environment, walletAddress, apiKey, appName) {
         safeSetTag('sdk.runtime', (0, sentry_runtime_1.getSentryRuntime)());
         // `app.name` is the dimension we filter on in Sentry to attribute
         // events to a specific consuming application — see SDK quickstart docs.
-        if (appName) {
-            safeSetTag('app.name', appName);
-        }
+        safeSetTag('app.name', validatedAppName);
         // `unverified:` prefix until the backend API-key → partner-id endpoint exists.
-        safeSetTag('partner.id', appName ? `unverified:${appName}` : 'unverified:anonymous');
+        safeSetTag('partner.id', `unverified:${validatedAppName}`);
         safeSetTag('partner.tier', 'unverified');
         // 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

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 = "8.26.0";
+export declare const SDK_VERSION = "9.0.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 = '8.26.0';
+exports.SDK_VERSION = '9.0.0';
 //# sourceMappingURL=version.js.map

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

@@ -25,7 +25,8 @@ export interface IAugustBase {
      * 3–64 characters, `[a-zA-Z0-9._-]` only. Use a slug ("acme-trader"),
      * not a display name ("Acme Trader").
      *
-     * @throws Throws synchronously from the constructor if missing or empty.
+     * @throws AugustValidationError synchronously from the constructor if
+     *   missing, empty, or malformed.
      *
      * @example
      * ```typescript
@@ -120,8 +121,8 @@ export declare class AugustBase {
      * Initialize base SDK with provider configuration and API keys.
      * Sets up the first provider as the active network by default.
      *
-     * @throws If `appName` is missing, malformed, or out of the allowed
-     *   length range — see {@link IAugustBase.appName}.
+     * @throws AugustValidationError if `appName` is missing, malformed, or
+     *   out of the allowed length range — see {@link IAugustBase.appName}.
      */
     constructor({ appName, providers, keys, monitoring, analytics, versionCheck, timeoutMs, publicApiBaseUrl, attribution, }: IAugustBase);
     /**

package/lib/core/base.class.js

@@ -4,36 +4,10 @@ exports.AugustBase = void 0;
 const auth_1 = require("./auth");
 const logger_1 = require("./logger");
 const analytics_1 = require("./analytics");
+const app_name_1 = require("./analytics/app-name");
 const version_check_1 = require("./version-check");
 const fetcher_1 = require("./fetcher");
 const attribution_1 = require("./attribution");
-/**
- * Validate an appName at SDK construction time.
- *
- * Rules (kept intentionally narrow so the value is safe to use as a Sentry
- * tag, an HTTP header value, and a filesystem-safe identifier — this is
- * why we accept slugs only, not display names):
- *  - non-empty after trim
- *  - 3..64 characters
- *  - only `[a-zA-Z0-9._-]`
- *
- * Throws a descriptive Error that names the failed rule and includes a
- * remediation hint pointing at the docs link.
- */
-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;
-}
 /**
  * Base class providing core SDK functionality including provider management,
  * network switching, and authentication state.
@@ -53,13 +27,13 @@ class AugustBase {
      * Initialize base SDK with provider configuration and API keys.
      * Sets up the first provider as the active network by default.
      *
-     * @throws If `appName` is missing, malformed, or out of the allowed
-     *   length range — see {@link IAugustBase.appName}.
+     * @throws AugustValidationError if `appName` is missing, malformed, or
+     *   out of the allowed length range — see {@link IAugustBase.appName}.
      */
     constructor({ appName, providers = {}, keys, monitoring, analytics, versionCheck, timeoutMs, publicApiBaseUrl, attribution, }) {
         // Validate first so the failure mode is a clear, actionable error before
         // any provider / analytics side effects run.
-        this.appName = validateAppName(appName);
+        this.appName = (0, app_name_1.validateAppName)(appName);
         // TODO: change this to false later when august key is required
         this.authorized = true;
         this.providers = providers;
@@ -82,7 +56,7 @@ class AugustBase {
         logger_1.Logger.setDevMode(environment === 'DEV');
         // Initialize analytics (pass API key for hashed identification + the
         // appName so events can be filtered by consuming application).
-        (0, analytics_1.initializeSentry)(analytics ?? { enabled: true }, environment, monitoring?.['x-user-id'], keys?.august, this.appName);
+        (0, analytics_1.initializeSentry)(analytics ?? { enabled: true }, environment, this.appName, monitoring?.['x-user-id'], keys?.august);
         // Best-effort version nudge — fire-and-forget, never blocks init, no
         // network call in production. See `core/version-check.ts` for details.
         (0, version_check_1.runVersionCheck)(versionCheck);

package/lib/sdk.d.ts

@@ -15822,8 +15822,8 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                    * Initialize base SDK with provider configuration and API keys.
                    * Sets up the first provider as the active network by default.
                    *
-                   * @throws If `appName` is missing, malformed, or out of the allowed
-                   *   length range — see {@link IAugustBase.appName}.
+                   * @throws AugustValidationError if `appName` is missing, malformed, or
+                   *   out of the allowed length range — see {@link IAugustBase.appName}.
                    */
                   constructor({ appName, providers, keys, monitoring, analytics, versionCheck, timeoutMs, publicApiBaseUrl, attribution, }: IAugustBase);
                   /**
@@ -19960,7 +19960,8 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                       * 3–64 characters, `[a-zA-Z0-9._-]` only. Use a slug ("acme-trader"),
                                       * not a display name ("Acme Trader").
                                       *
-                                      * @throws Throws synchronously from the constructor if missing or empty.
+                                      * @throws AugustValidationError synchronously from the constructor if
+                                      *   missing, empty, or malformed.
                                       *
                                       * @example
                                       * ```typescript
@@ -20983,16 +20984,28 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                   * Initialize Sentry with SDK-specific configuration. Idempotent: re-calls
                                   * only refresh user identity and the cached API-key hash.
                                   *
+                                  * Breaking change in v9: `appName` moved from the optional fifth parameter
+                                  * to the required third parameter, so every telemetry stream carries an
+                                  * application identity (the `AugustSDK` constructor has required it since
+                                  * v5). Callers on the old positional order get a synchronous validation
+                                  * error rather than silently anonymous events.
+                                  *
                                   * @param config - Analytics configuration. Pass `tracesSampleRate` to
                                   *   override the default of `0.1`.
                                   * @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:
+                                  *   3–64 chars, `[a-zA-Z0-9._-]` only, and not an EVM address — the same
+                                  *   rules the `AugustSDK` constructor enforces.
                                   * @param walletAddress - Optional wallet address for user identification.
                                   * @param apiKey - Optional API key (hashed for identification).
-                                  * @param appName - Optional app-name slug. Set as the global `app.name`
-                                  *   tag on every event; falls back to `'unverified:anonymous'` when
-                                  *   omitted.
+                                  * @throws AugustValidationError (code `INVALID_INPUT`) when `appName` is
+                                  *   missing, empty, mis-typed, out of the allowed length range, contains
+                                  *   disallowed characters, or is shaped like an EVM address. Thrown before
+                                  *   any analytics state mutates, even when analytics would be disabled by
+                                  *   config or environment gates.
                                   */
-                                 export declare function initializeSentry(config: IAnalyticsConfig, environment: IEnv, walletAddress?: string, apiKey?: string, appName?: string): void;
+                                 export declare function initializeSentry(config: IAnalyticsConfig, environment: IEnv, appName: string, walletAddress?: string, apiKey?: string): void;
 
                                  export declare type INormalizedNumber = {
                                      normalized: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@augustdigital/sdk",
-  "version": "8.26.0",
+  "version": "9.0.0",
   "main": "lib/index.js",
   "types": "lib/sdk.d.ts",
   "keywords": [