@augustdigital/sdk 8.26.0 → 9.1.0

package/lib/adapters/stellar/actions.d.ts

@@ -22,6 +22,19 @@ export declare function handleStellarDeposit(params: IStellarDepositParams): Pro
  * `redeem(shares: i128, receiver, owner, operator) -> i128`; divergence
  * surfaces as a generic Soroban simulation error.
  *
+ * Side effect on failure: when the *vault* cannot serve the redemption — it
+ * rejected the call, or its ledger state needs restoring — the failure is
+ * reported to that vault's curator. Stellar vaults are instant-redeem only, so
+ * this is the curator's only signal that their depositors cannot get out
+ * (AUGUST-7162). Fire-and-forget and deduped; see
+ * {@link reportRedeemFailure} and {@link REPORTED_BUILD_STAGES}.
+ *
+ * Note this includes a caller-caused rejection such as redeeming more shares
+ * than the wallet holds: the contract trapping is what we can observe, and
+ * telling that apart from a vault-side problem needs the vault's error
+ * taxonomy. A bad address, an unfunded account, and an exhausted RPC failover
+ * are excluded — none of those reached the vault.
+ *
  * @returns Base64-encoded XDR ready for wallet signing; pass the signed
  *   XDR to {@link submitStellarTransaction}.
  */

package/lib/adapters/stellar/actions.js

@@ -12,6 +12,21 @@ const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const soroban_1 = require("./soroban");
 const utils_1 = require("./utils");
 const core_1 = require("../../core");
+const curator_alert_1 = require("../../core/logger/curator-alert");
+/**
+ * Build failures that mean the *vault* cannot serve a redemption right now, as
+ * opposed to a caller problem or a transport problem.
+ *
+ * `simulation` is the contract rejecting the call. `restore-required` is its
+ * ledger state having been archived, which blocks every redemption on the vault
+ * until someone submits a restore footprint — different remedy, same
+ * consequence for a depositor trying to get out.
+ *
+ * Deliberately excluded: `rpc-failover` (our transport, not their vault),
+ * `assembly` (an SDK-side fault), and validation errors, which carry no stage
+ * at all.
+ */
+const REPORTED_BUILD_STAGES = new Set(['simulation', 'restore-required']);
 function validateContractAddress(contractId) {
     if (!(0, utils_1.isStellarAddress)(contractId) || contractId[0] !== 'C') {
         throw new core_1.AugustValidationError('INVALID_ADDRESS', `Invalid contract address: expected a Stellar contract (C-prefix), got "${contractId}"`);
@@ -63,6 +78,19 @@ async function handleStellarDeposit(params) {
  * `redeem(shares: i128, receiver, owner, operator) -> i128`; divergence
  * surfaces as a generic Soroban simulation error.
  *
+ * Side effect on failure: when the *vault* cannot serve the redemption — it
+ * rejected the call, or its ledger state needs restoring — the failure is
+ * reported to that vault's curator. Stellar vaults are instant-redeem only, so
+ * this is the curator's only signal that their depositors cannot get out
+ * (AUGUST-7162). Fire-and-forget and deduped; see
+ * {@link reportRedeemFailure} and {@link REPORTED_BUILD_STAGES}.
+ *
+ * Note this includes a caller-caused rejection such as redeeming more shares
+ * than the wallet holds: the contract trapping is what we can observe, and
+ * telling that apart from a vault-side problem needs the vault's error
+ * taxonomy. A bad address, an unfunded account, and an exhausted RPC failover
+ * are excluded — none of those reached the vault.
+ *
  * @returns Base64-encoded XDR ready for wallet signing; pass the signed
  *   XDR to {@link submitStellarTransaction}.
  */
@@ -71,7 +99,28 @@ async function handleStellarRedeem(params) {
     validateContractAddress(contractId);
     validateAccountAddress(receiverAddress, 'receiver');
     const config = (0, soroban_1.resolveNetworkConfig)(network, sorobanRpcUrl);
-    const args = buildSelfOperationArgs((0, soroban_1.toBigIntAmount)(shares, 'redeem shares'), receiverAddress);
-    return (0, soroban_1.buildSorobanTx)(config, receiverAddress, contractId, 'redeem', args);
+    // Normalized once and reused for both the invocation and the report: the
+    // caller's string may be any form `BigInt` accepts (`'0x10'`, `' 42 '`), and
+    // relaying that verbatim hands the reporting endpoint something it rejects.
+    const shareAmount = (0, soroban_1.toBigIntAmount)(shares, 'redeem shares');
+    const args = buildSelfOperationArgs(shareAmount, receiverAddress);
+    try {
+        return await (0, soroban_1.buildSorobanTx)(config, receiverAddress, contractId, 'redeem', args);
+    }
+    catch (err) {
+        if (err instanceof core_1.AugustSDKError &&
+            REPORTED_BUILD_STAGES.has(String(err.context?.stage))) {
+            (0, curator_alert_1.reportRedeemFailure)({
+                phase: 'simulation',
+                chain: 'stellar',
+                network,
+                contractId,
+                eoa: receiverAddress,
+                sharesRaw: shareAmount.toString(),
+                error: String(err.message),
+            });
+        }
+        throw err;
+    }
 }
 //# sourceMappingURL=actions.js.map

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

@@ -64,10 +64,22 @@ export declare class StellarAdapter {
     vaultDeposit(params: Omit<IStellarDepositParams, 'network'>): Promise<string>;
     /**
      * Build an unsigned redeem transaction for a Stellar vault.
+     *
+     * Side effect on failure: a redemption the vault cannot serve is reported to
+     * that vault's curator, since Stellar vaults are instant-redeem only and this
+     * is the curator's only signal. Fire-and-forget — it never delays or alters
+     * the error you receive. On by default in production; see
+     * `monitoring.curatorAlerts` and the Curator Notifications section of the
+     * Stellar Actions guide for exactly what is sent and how to opt out.
+     *
      * @returns Base64-encoded XDR of the unsigned transaction.
      */
     vaultRedeem(params: Omit<IStellarRedeemParams, 'network'>): Promise<string>;
     /**
+     * Side effect: a submitted transaction that the network reports as a failed
+     * `redeem` operation is reported to that vault's curator, on the same
+     * fire-and-forget terms as {@link StellarAdapter.vaultRedeem}.
+     *
      * Submit a signed Soroban transaction and poll until the network confirms it.
      *
      * Submits on the network this adapter was constructed with, so `signedXdr`

package/lib/adapters/stellar/index.js

@@ -110,6 +110,14 @@ class StellarAdapter {
     }
     /**
      * Build an unsigned redeem transaction for a Stellar vault.
+     *
+     * Side effect on failure: a redemption the vault cannot serve is reported to
+     * that vault's curator, since Stellar vaults are instant-redeem only and this
+     * is the curator's only signal. Fire-and-forget — it never delays or alters
+     * the error you receive. On by default in production; see
+     * `monitoring.curatorAlerts` and the Curator Notifications section of the
+     * Stellar Actions guide for exactly what is sent and how to opt out.
+     *
      * @returns Base64-encoded XDR of the unsigned transaction.
      */
     async vaultRedeem(params) {
@@ -121,6 +129,10 @@ class StellarAdapter {
         });
     }
     /**
+     * Side effect: a submitted transaction that the network reports as a failed
+     * `redeem` operation is reported to that vault's curator, on the same
+     * fire-and-forget terms as {@link StellarAdapter.vaultRedeem}.
+     *
      * Submit a signed Soroban transaction and poll until the network confirms it.
      *
      * Submits on the network this adapter was constructed with, so `signedXdr`

package/lib/adapters/stellar/invocation.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Stellar Invocation Decoding
+ *
+ * Reads back what a built transaction actually invokes. `submitStellarTransaction`
+ * takes an opaque signed XDR — it has no idea whether it is broadcasting a
+ * deposit, a redeem, or something else — so a failure there cannot be attributed
+ * to a vault operation without looking inside the envelope.
+ */
+import type { FeeBumpTransaction, Transaction } from '@stellar/stellar-sdk';
+/** A vault contract invocation recovered from a transaction envelope. */
+export interface IVaultInvocation {
+    /** Invoked contract (C-address). */
+    contractId: string;
+    /** Contract function name, e.g. `'redeem'` or `'deposit'`. */
+    functionName: string;
+    /**
+     * First argument as a decimal string, when it decodes to an integer. Both
+     * `deposit(assets, …)` and `redeem(shares, …)` lead with the `i128` amount.
+     * `undefined` when the argument is absent or not an integer.
+     */
+    amountRaw?: string;
+    /**
+     * Second argument as a Stellar address, when it decodes to one — the
+     * `receiver` in both vault signatures. `undefined` otherwise.
+     */
+    receiver?: string;
+    /**
+     * Third argument as a Stellar address, when it decodes to one — `owner` in
+     * `redeem(shares, receiver, owner, operator)`, i.e. the account whose shares
+     * are burned. Identical to `receiver` for the self-redeem the SDK builds, but
+     * they differ for a delegated redemption. `undefined` otherwise.
+     */
+    owner?: string;
+}
+/**
+ * Decode the single Soroban contract invocation in a transaction.
+ *
+ * Every transaction the SDK builds carries exactly one `invokeHostFunction`
+ * operation (see `buildSorobanTx`), so the first one found is authoritative.
+ * Purely local — no RPC, no network.
+ *
+ * Written defensively rather than optimistically: this is called from an error
+ * path where the envelope may be anything a caller handed us, and a throw here
+ * would replace the real transaction failure with a decoding error. Anything
+ * unexpected — a fee-bump wrapper, a classic payment, a shape-drifted SDK
+ * union, a non-address argument — yields `undefined`.
+ *
+ * @param tx - Parsed transaction (e.g. `TransactionBuilder.fromXDR(...)`, whose
+ *   return type includes the fee-bump wrapper — that case yields `undefined`,
+ *   since the invocation lives in the inner transaction and the SDK never
+ *   builds one).
+ * @returns The invocation, or `undefined` when the transaction does not carry a
+ *   decodable contract call.
+ */
+export declare function describeVaultInvocation(tx: Transaction | FeeBumpTransaction): IVaultInvocation | undefined;

package/lib/adapters/stellar/invocation.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Stellar Invocation Decoding
+ *
+ * Reads back what a built transaction actually invokes. `submitStellarTransaction`
+ * takes an opaque signed XDR — it has no idea whether it is broadcasting a
+ * deposit, a redeem, or something else — so a failure there cannot be attributed
+ * to a vault operation without looking inside the envelope.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeVaultInvocation = describeVaultInvocation;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+/**
+ * Decode the single Soroban contract invocation in a transaction.
+ *
+ * Every transaction the SDK builds carries exactly one `invokeHostFunction`
+ * operation (see `buildSorobanTx`), so the first one found is authoritative.
+ * Purely local — no RPC, no network.
+ *
+ * Written defensively rather than optimistically: this is called from an error
+ * path where the envelope may be anything a caller handed us, and a throw here
+ * would replace the real transaction failure with a decoding error. Anything
+ * unexpected — a fee-bump wrapper, a classic payment, a shape-drifted SDK
+ * union, a non-address argument — yields `undefined`.
+ *
+ * @param tx - Parsed transaction (e.g. `TransactionBuilder.fromXDR(...)`, whose
+ *   return type includes the fee-bump wrapper — that case yields `undefined`,
+ *   since the invocation lives in the inner transaction and the SDK never
+ *   builds one).
+ * @returns The invocation, or `undefined` when the transaction does not carry a
+ *   decodable contract call.
+ */
+function describeVaultInvocation(tx) {
+    try {
+        if (!('operations' in tx))
+            return undefined;
+        for (const op of tx.operations ?? []) {
+            if (op.type !== 'invokeHostFunction')
+                continue;
+            const hostFn = op.func;
+            if (hostFn.switch() !==
+                stellar_sdk_1.xdr.HostFunctionType.hostFunctionTypeInvokeContract()) {
+                continue;
+            }
+            const invocation = hostFn.invokeContract();
+            const contractId = stellar_sdk_1.Address.fromScAddress(invocation.contractAddress()).toString();
+            const functionName = invocation.functionName().toString();
+            const args = invocation.args();
+            return {
+                contractId,
+                functionName,
+                amountRaw: decodeInteger(args[0]),
+                receiver: decodeAddress(args[1]),
+                owner: decodeAddress(args[2]),
+            };
+        }
+    }
+    catch {
+        // Shape drift or an envelope we don't recognise. The caller falls back to
+        // reporting nothing rather than misattributing the failure.
+    }
+    return undefined;
+}
+/** `bigint` / `number` ScVal → decimal string; `undefined` for anything else. */
+function decodeInteger(value) {
+    if (!value)
+        return undefined;
+    try {
+        const native = (0, stellar_sdk_1.scValToNative)(value);
+        if (typeof native === 'bigint')
+            return native.toString();
+        if (typeof native === 'number' && Number.isInteger(native)) {
+            return String(native);
+        }
+    }
+    catch {
+        // Not an integer ScVal.
+    }
+    return undefined;
+}
+/** Address ScVal → strkey; `undefined` for anything else. */
+function decodeAddress(value) {
+    if (!value)
+        return undefined;
+    try {
+        return stellar_sdk_1.Address.fromScVal(value).toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=invocation.js.map

package/lib/adapters/stellar/soroban.d.ts

@@ -119,5 +119,13 @@ export declare function queryContract(config: ISorobanNetworkConfig, contractId:
  * Fetches the real source account from the network (the account must exist and be funded).
  * Simulates via Soroban RPC to attach resource footprint and auth entries,
  * using MAX_FEE_STROOPS as the fee ceiling and incorporating the simulated resource fee.
+ *
+ * Thrown errors carry `context.stage` naming where the build broke:
+ * `'simulation'` (the contract itself rejected the call), `'restore-required'`,
+ * `'assembly'`, or `'rpc-failover'` (no endpoint answered). Callers use it to
+ * separate a vault-level rejection from a transport problem — see the curator
+ * alerting in `handleStellarRedeem`. Validation errors (e.g.
+ * `ACCOUNT_NOT_FUNDED`) carry no stage, so treat a missing one as "not a
+ * vault-level failure" rather than assuming the field is always present.
  */
 export declare function buildSorobanTx(config: ISorobanNetworkConfig, sourceAddress: string, contractId: string, method: string, args: xdr.ScVal[]): Promise<string>;

package/lib/adapters/stellar/soroban.js

@@ -367,7 +367,10 @@ async function withEndpointFailover(config, method, operation, options = {}) {
     let lastError;
     // A terminal "everything failed" error, scrubbed so a keyed endpoint can't
     // leak through the message or chained cause.
-    const failAllEndpoints = () => new core_1.AugustSDKError('UNKNOWN', `Soroban ${method} failed on all endpoints: ${scrub(String(lastError))}`, { cause: scrubErrorUrls(lastError, scrub), context: { method } });
+    const failAllEndpoints = () => new core_1.AugustSDKError('UNKNOWN', `Soroban ${method} failed on all endpoints: ${scrub(String(lastError))}`, {
+        cause: scrubErrorUrls(lastError, scrub),
+        context: { method, stage: 'rpc-failover' },
+    });
     // Fast path: the health-gated, cross-call-cached endpoint.
     const { server: primaryServer, url: primaryUrl, healthy, } = await resolveHealthyServer(config);
     try {
@@ -545,6 +548,14 @@ async function getNetworkCloseTime(server) {
  * Fetches the real source account from the network (the account must exist and be funded).
  * Simulates via Soroban RPC to attach resource footprint and auth entries,
  * using MAX_FEE_STROOPS as the fee ceiling and incorporating the simulated resource fee.
+ *
+ * Thrown errors carry `context.stage` naming where the build broke:
+ * `'simulation'` (the contract itself rejected the call), `'restore-required'`,
+ * `'assembly'`, or `'rpc-failover'` (no endpoint answered). Callers use it to
+ * separate a vault-level rejection from a transport problem — see the curator
+ * alerting in `handleStellarRedeem`. Validation errors (e.g.
+ * `ACCOUNT_NOT_FUNDED`) carry no stage, so treat a missing one as "not a
+ * vault-level failure" rather than assuming the field is always present.
  */
 async function buildSorobanTx(config, sourceAddress, contractId, method, args) {
     const contract = new stellar_sdk_1.Contract(contractId);
@@ -595,18 +606,21 @@ async function buildSorobanTx(config, sourceAddress, contractId, method, args) {
                 // retryable error so the failover wrapper tries another endpoint.
                 throw new Error(`Soroban simulation node error for ${method}: ${errorText}`);
             }
-            throw new core_1.AugustSDKError('UNKNOWN', `Soroban simulation failed: ${errorText}`, { context: { method, contractId } });
+            throw new core_1.AugustSDKError('UNKNOWN', `Soroban simulation failed: ${errorText}`, { context: { method, contractId, stage: 'simulation' } });
         }
         if ('restorePreamble' in simulated && simulated.restorePreamble) {
             throw new core_1.AugustSDKError('UNKNOWN', `Contract ledger state needs restoration before invoking ${method}. ` +
-                'Submit a restore footprint transaction first.', { context: { method, contractId } });
+                'Submit a restore footprint transaction first.', { context: { method, contractId, stage: 'restore-required' } });
         }
         try {
             const assembled = stellar_sdk_1.rpc.assembleTransaction(tx, simulated).build();
             return assembled.toXDR();
         }
         catch (assemblyErr) {
-            throw new core_1.AugustSDKError('UNKNOWN', `Failed to assemble Soroban transaction for ${method}: ${String(assemblyErr)}`, { cause: assemblyErr, context: { method, contractId } });
+            throw new core_1.AugustSDKError('UNKNOWN', `Failed to assemble Soroban transaction for ${method}: ${String(assemblyErr)}`, {
+                cause: assemblyErr,
+                context: { method, contractId, stage: 'assembly' },
+            });
         }
     });
 }

package/lib/adapters/stellar/submit.d.ts

@@ -20,6 +20,14 @@ import type { IStellarNetwork } from './types';
  *   plus, when the result XDR decodes, a `resultCode` string holding the
  *   transaction-level reason (e.g. `"txBadSeq"`, `"txTooLate"`); `resultCode`
  *   is `undefined` when the code cannot be decoded.
+ *
+ * Side effect: a transaction whose `resultCode` is `txFailed` — the operation
+ * itself ran and failed — and whose envelope shows a vault `redeem` is relayed
+ * to that vault's curator (fire-and-forget, deduped — see
+ * {@link reportRedeemFailure}). Nothing else alerts: an RPC-rejected
+ * broadcast is a retryable race, a poll timeout is indeterminate (the
+ * transaction may yet succeed), and any other result code means the redeem
+ * never executed.
  * @example
  * ```ts
  * try {

package/lib/adapters/stellar/submit.js

@@ -8,7 +8,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.submitStellarTransaction = submitStellarTransaction;
 const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const core_1 = require("../../core");
+const curator_alert_1 = require("../../core/logger/curator-alert");
 const soroban_1 = require("./soroban");
+const invocation_1 = require("./invocation");
 const constants_1 = require("./constants");
 /**
  * Best-effort decode of the transaction-level result code (the XDR union
@@ -64,6 +66,14 @@ function safeStringify(value) {
  *   plus, when the result XDR decodes, a `resultCode` string holding the
  *   transaction-level reason (e.g. `"txBadSeq"`, `"txTooLate"`); `resultCode`
  *   is `undefined` when the code cannot be decoded.
+ *
+ * Side effect: a transaction whose `resultCode` is `txFailed` — the operation
+ * itself ran and failed — and whose envelope shows a vault `redeem` is relayed
+ * to that vault's curator (fire-and-forget, deduped — see
+ * {@link reportRedeemFailure}). Nothing else alerts: an RPC-rejected
+ * broadcast is a retryable race, a poll timeout is indeterminate (the
+ * transaction may yet succeed), and any other result code means the redeem
+ * never executed.
  * @example
  * ```ts
  * try {
@@ -137,6 +147,42 @@ async function submitStellarTransaction(signedXdr, network, sorobanRpcUrl) {
         network,
         resultCode,
     });
+    // A redemption that executed and failed is the strongest form of the signal
+    // the curator needs — and the only one carrying a hash the relay can verify
+    // on chain. Two gates, because a FAILED confirmation is not by itself a vault
+    // failure:
+    //   - `txFailed` is the only result code meaning the operations were applied
+    //     and one of them failed. Everything else at this layer is
+    //     transaction-level — `txBadSeq`, `txInsufficientBalance`,
+    //     `txTooLate`, resource-limit overruns — where the redeem never ran, and
+    //     which the caller resolves by retrying. An undecodable code is treated
+    //     the same way: without it we cannot tell the two apart, and silence
+    //     beats paging a curator over a sequence-number race.
+    //   - the envelope must actually be a redeem: this function is handed an
+    //     opaque XDR and would otherwise misattribute deposits.
+    const invocation = resultCode === 'txFailed' ? (0, invocation_1.describeVaultInvocation)(tx) : undefined;
+    // A partially-decoded envelope is not reported at all: an alert naming no
+    // wallet or no amount is one a curator cannot act on, and the reporting
+    // endpoint rejects it anyway.
+    const redeemer = invocation?.owner ?? invocation?.receiver;
+    if (invocation?.functionName === 'redeem' &&
+        redeemer &&
+        invocation.amountRaw) {
+        (0, curator_alert_1.reportRedeemFailure)({
+            phase: 'submission',
+            chain: 'stellar',
+            network,
+            contractId: invocation.contractId,
+            // `owner` is the account whose shares burn; `receiver` only receives the
+            // assets. They are the same for a self-redeem, and owner is the right one
+            // to name when they differ.
+            eoa: redeemer,
+            sharesRaw: invocation.amountRaw,
+            txHash: sendResult.hash,
+            resultCode,
+            error: msg,
+        });
+    }
     throw new core_1.AugustSDKError('UNKNOWN', msg, {
         context: {
             hash: sendResult.hash,

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/env.d.ts

@@ -27,3 +27,20 @@ export declare function isAnalyticsDisabledViaEnv(): boolean;
  * `NODE_ENV` undefined / `'production'` / `'staging'` / anything else → false.
  */
 export declare function isNodeDevOrTestEnv(): boolean;
+/**
+ * True when the page is being served from a developer's own machine or private
+ * network.
+ *
+ * The browser counterpart to {@link isNodeDevOrTestEnv}: bundlers strip or
+ * stub `process.env`, so `NODE_ENV` cannot tell a `next dev` tab apart from a
+ * production deploy. The hostname can. Always false in Node, where
+ * `NODE_ENV` is the gate.
+ *
+ * Recognises `localhost` and the `.localhost` TLD (RFC 6761 reserves both for
+ * loopback), mDNS `.local` names, and any loopback / private / link-local IP
+ * literal in either address family. Anything else — including a public host
+ * that merely *contains* one of those names, like `localhost.acme.com` — is
+ * treated as a real deployment, because suppressing a genuine production
+ * origin is the more costly mistake of the two.
+ */
+export declare function isLocalhost(): boolean;

package/lib/core/analytics/env.js

@@ -8,6 +8,7 @@ exports.readEnv = readEnv;
 exports.isAnalyticsForcedOnViaEnv = isAnalyticsForcedOnViaEnv;
 exports.isAnalyticsDisabledViaEnv = isAnalyticsDisabledViaEnv;
 exports.isNodeDevOrTestEnv = isNodeDevOrTestEnv;
+exports.isLocalhost = isLocalhost;
 /**
  * Read a process env var without crashing in browsers or in bundles where
  * `process.env` is a frozen / proxied object that throws on missing keys.
@@ -56,4 +57,91 @@ function isNodeDevOrTestEnv() {
     const env = readEnv('NODE_ENV');
     return env === 'development' || env === 'test';
 }
+/** Dotted-quad IPv4 literal. Anchored, so `10.acme.com` is not an address. */
+const IPV4_LITERAL = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+/**
+ * True for an IPv4 literal that cannot be a public production origin: loopback
+ * (`127.0.0.0/8` — `127.0.0.1` is only the most common of 16.7M), the
+ * "this host" block (`0.0.0.0/8`), the three RFC 1918 private ranges, and
+ * link-local (`169.254.0.0/16`).
+ *
+ * Ranges are checked by octet rather than by string prefix on purpose: a
+ * `startsWith('10.')` test both misses `172.20.0.2` (a default Docker bridge
+ * address, and a very ordinary way to reach a container) and misfires on a
+ * public host that merely begins with those digits.
+ */
+function isPrivateIpv4(hostname) {
+    const octets = IPV4_LITERAL.exec(hostname);
+    if (!octets)
+        return false;
+    const [a, b, c, d] = octets.slice(1).map(Number);
+    // The regex counts digits, not values, so an out-of-range quad still matches
+    // its shape. `127.0.0.999` is not an address — the URL parser rejects it
+    // rather than handing it over as a `hostname` — so it is a name, and names
+    // that are not the reserved ones are treated as deployed.
+    if (a > 255 || b > 255 || c > 255 || d > 255)
+        return false;
+    return (a === 127 ||
+        a === 0 ||
+        a === 10 ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 169 && b === 254));
+}
+/**
+ * True for an IPv6 literal that cannot be a public production origin:
+ * loopback (`::1`, in either notation), the unspecified address, an
+ * IPv4-mapped private address, unique-local (`fc00::/7`) and link-local
+ * (`fe80::/10`).
+ *
+ * `hostname` carries the brackets for an IPv6 host — `http://[::1]:3000/`
+ * yields `[::1]`, per the URL standard's host serialization — so they are
+ * stripped before matching.
+ */
+function isLocalIpv6(hostname) {
+    const host = hostname.replace(/^\[/, '').replace(/\]$/, '');
+    if (!host.includes(':'))
+        return false;
+    if (host === '::1' || host === '::')
+        return true;
+    if (/^(?:0{1,4}:){7}0{0,3}1$/.test(host))
+        return true;
+    if (host.startsWith('::ffff:'))
+        return isPrivateIpv4(host.slice(7));
+    return /^f[cd]/.test(host) || /^fe[89ab]/.test(host);
+}
+/**
+ * True when the page is being served from a developer's own machine or private
+ * network.
+ *
+ * The browser counterpart to {@link isNodeDevOrTestEnv}: bundlers strip or
+ * stub `process.env`, so `NODE_ENV` cannot tell a `next dev` tab apart from a
+ * production deploy. The hostname can. Always false in Node, where
+ * `NODE_ENV` is the gate.
+ *
+ * Recognises `localhost` and the `.localhost` TLD (RFC 6761 reserves both for
+ * loopback), mDNS `.local` names, and any loopback / private / link-local IP
+ * literal in either address family. Anything else — including a public host
+ * that merely *contains* one of those names, like `localhost.acme.com` — is
+ * treated as a real deployment, because suppressing a genuine production
+ * origin is the more costly mistake of the two.
+ */
+function isLocalhost() {
+    try {
+        if (typeof window !== 'undefined' && window.location) {
+            // Hostnames are case-insensitive; browsers normalize, other runtimes
+            // hosting a `window` shim may not.
+            const hostname = String(window.location.hostname).toLowerCase();
+            return (hostname === 'localhost' ||
+                hostname.endsWith('.localhost') ||
+                hostname.endsWith('.local') ||
+                isPrivateIpv4(hostname) ||
+                isLocalIpv6(hostname));
+        }
+    }
+    catch {
+        // Some embedded/sandboxed runtimes throw on `window.location`. Not local.
+    }
+    return false;
+}
 //# sourceMappingURL=env.js.map