@augustdigital/sdk 8.26.0 → 9.1.0

package/lib/core/logger/curator-alert.js

@@ -0,0 +1,276 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CURATOR_ALERTS_DISABLE_ENV_VAR = exports.DEFAULT_CURATOR_ALERT_ENDPOINT = exports.CURATOR_ALERT_PATH = void 0;
+exports.configureCuratorAlerts = configureCuratorAlerts;
+exports.resetCuratorAlertDedupe = resetCuratorAlertDedupe;
+exports.areCuratorAlertsEnabled = areCuratorAlertsEnabled;
+exports.reportRedeemFailure = reportRedeemFailure;
+const lru_cache_1 = require("lru-cache");
+const env_1 = require("../analytics/env");
+const sanitize_1 = require("../analytics/sanitize");
+const core_1 = require("../constants/core");
+/**
+ * Path on the August public API that accepts a failed-redemption report. Chain
+ * lives in the payload, not the path — see {@link IRedeemFailureEvent.chain}.
+ */
+exports.CURATOR_ALERT_PATH = '/alerts/redeem-failure';
+/**
+ * Where a redeem failure is reported: the August public API, which is already
+ * this SDK's read origin and already serves browsers.
+ *
+ * Browser delivery depends on CORS, and the API's allowlist is an enumerated
+ * list of partner origins (`ALLOWED_ORIGIN_REGEX` in the backend), not a
+ * wildcard. This POST sends `Content-Type: application/json`, so it is
+ * preflighted; an integration served from an origin that is not on that list
+ * loses every alert at the preflight. Onboarding a curator therefore has two
+ * halves — enabling the vault and allowlisting the origin their users load.
+ *
+ * That service is the trust boundary, not the destination: it validates the
+ * report, drops any vault it does not know or that has not opted in,
+ * rate-limits per wallet and per vault, and only then forwards to the Telegram
+ * bot that holds the token and the curator's channel. Nothing
+ * credential-shaped ships in this bundle, which is also why this endpoint
+ * takes no API key — a key in a browser bundle is a published key
+ * (CLAUDE.md §5). See {@link reportRedeemFailure} for the trust model.
+ */
+exports.DEFAULT_CURATOR_ALERT_ENDPOINT = `${core_1.WEBSERVER_URL.public}${exports.CURATOR_ALERT_PATH}`;
+/** Env equivalent of `monitoring.curatorAlerts.enabled: false`. Node only. */
+exports.CURATOR_ALERTS_DISABLE_ENV_VAR = 'AUGUST_SDK_DISABLE_CURATOR_ALERTS';
+/** Suppression window per `{vault, wallet, phase, result code, error class}`. */
+const ALERT_DEDUPE_TTL_MS = 10 * 60 * 1000;
+/**
+ * Diagnostic tail kept on the relayed error. Bounds a field that is unbounded
+ * by nature (a Soroban diagnostic event log) before it leaves the process. The
+ * receiving service applies its own, smaller display cap for the Telegram
+ * message, so this is the transport ceiling, not the one a curator sees.
+ */
+const MAX_ERROR_CHARS = 1500;
+const SEND_TIMEOUT_MS = 5000;
+/**
+ * Dedupe keys only — deliberately NOT the shared `core/cache.ts` LRU. That one
+ * is a 1000-entry cache shared with RPC and metadata memoization, so ordinary
+ * traffic could evict a suppression key mid-window (re-opening the flood this
+ * exists to stop) and a vault-wide incident's keys could evict useful reads.
+ */
+const alertDedupe = new lru_cache_1.LRUCache({
+    max: 200,
+    ttl: ALERT_DEDUPE_TTL_MS,
+});
+let explicitEnabled;
+let endpoint = exports.DEFAULT_CURATOR_ALERT_ENDPOINT;
+let endpointOverridden = false;
+let reporterAppName;
+let reporterEnv;
+let configSignature;
+/**
+ * Apply constructor config. Called unconditionally by `AugustBase` so an
+ * instance that omits `curatorAlerts` RESETS to the defaults rather than
+ * inheriting a prior instance's settings — same contract as
+ * `setPublicApiBaseUrl` and `setAttribution`.
+ *
+ * Also the supported opt-out for code that calls the `Stellar` namespace
+ * functions directly without constructing an `AugustSDK` (the testnet flow in
+ * the docs), and the only one that works in a browser, where the env var is
+ * unreadable.
+ *
+ * @param config - `monitoring.curatorAlerts`, or `null` to restore defaults.
+ * @param context - Facts about the reporting instance; omitted entirely by a
+ *   caller that only wants to disable reporting.
+ */
+function configureCuratorAlerts(config, context = {}) {
+    const override = config?.endpoint?.trim();
+    const nextEndpoint = override ||
+        (context.apiBaseUrl
+            ? `${context.apiBaseUrl.replace(/\/+$/, '')}${exports.CURATOR_ALERT_PATH}`
+            : exports.DEFAULT_CURATOR_ALERT_ENDPOINT);
+    // Suppression state belongs to the configuration that produced it, so a
+    // redirected endpoint or a flipped switch starts with a clean window. But
+    // this runs on EVERY `AugustBase` construction, and an app that builds the
+    // SDK inside a render rather than a memo would otherwise reset flood control
+    // on every attempt — so an identical reconfiguration keeps the window.
+    const signature = `${nextEndpoint}|${config?.enabled}|${context.environment}`;
+    if (signature !== configSignature) {
+        alertDedupe.clear();
+        configSignature = signature;
+    }
+    explicitEnabled = config?.enabled;
+    endpointOverridden = Boolean(override);
+    endpoint = nextEndpoint;
+    reporterAppName = context.appName;
+    reporterEnv = context.environment;
+}
+/**
+ * Drop every suppression key. Test-only seam — reconfiguration no longer
+ * clears the window on its own when the configuration is unchanged, so a suite
+ * that reports the same failure across cases needs an explicit reset.
+ * @internal
+ */
+function resetCuratorAlertDedupe() {
+    alertDedupe.clear();
+}
+function isTruthyEnv(value) {
+    if (!value)
+        return false;
+    const v = value.toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+/**
+ * Whether an alert would be sent right now.
+ *
+ * Quiet by default outside production, mirroring `analytics`: a partner's Jest
+ * suite or `next dev` session exercising a failing redeem must not page a real
+ * curator. Two gates are needed for that, because they cover different
+ * runtimes — `NODE_ENV` is the Node one, and bundlers strip or stub
+ * `process.env` in the browser, so a locally-served app is recognised by its
+ * hostname instead (CLAUDE.md §5). Without that gate, a browser app run
+ * against mainnet from any loopback or private origin — `localhost`, a
+ * container on `172.20.0.0/16`, `[::1]` — pages a real curator on every
+ * failed redeem. `isLocalhost` in `core/analytics/env` lists the ranges.
+ *
+ * `enabled: true` overrides both — it is the documented way to exercise the
+ * path deliberately, and the SDK's own suite relies on it.
+ *
+ * The env var is read per call (not once at module load) so a consumer that
+ * sets it after import is still honoured, and a test can set and unset it
+ * without re-importing. It deliberately outranks an explicit `enabled: true`:
+ * it is the kill switch, and an operator setting it should not have to find
+ * and edit the construction site to be obeyed.
+ */
+function areCuratorAlertsEnabled() {
+    if (explicitEnabled === false)
+        return false;
+    if (isTruthyEnv((0, env_1.readEnv)(exports.CURATOR_ALERTS_DISABLE_ENV_VAR)))
+        return false;
+    if (explicitEnabled === true)
+        return true;
+    if (reporterEnv && reporterEnv !== 'PROD')
+        return false;
+    return !(0, env_1.isNodeDevOrTestEnv)() && !(0, env_1.isLocalhost)();
+}
+/**
+ * Collapse an error to the failure mode it represents, so one wallet retrying
+ * the same failing redeem produces one alert — but two *different* failures on
+ * that vault still produce two.
+ *
+ * Volatile or semantic is decided by shape:
+ *  - long hex (XDR blobs, hashes) and 56-char Stellar strkeys → volatile;
+ *  - runs of 4+ digits (amounts, balances, ledger sequences) → volatile;
+ *  - a `#`-prefixed number → semantic, kept whatever its length. A Soroban
+ *    contract code IS the failure's identity: merging `Error(Contract, #408)`
+ *    (insufficient shares) with `#10` (balance out of range) — or two 4-digit
+ *    codes with each other — would hide the second for the whole window.
+ */
+function errorSignature(error) {
+    return error
+        .replace(/0x[0-9a-fA-F]{8,}/g, '0x')
+        .replace(/\b[A-Z2-7]{56}\b/g, 'S')
+        .replace(/(?<![0-9a-fA-Fx#-])\d{4,}/g, 'N')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 200);
+}
+/**
+ * Report a failed vault redemption for the curator of that vault.
+ *
+ * **Why this exists.** Stellar vaults are instant-redeem only — there is no
+ * request/queue path — so a curator whose users' redemptions are failing has
+ * no signal at all today: the failure surfaces to the user, and to August's
+ * internal Sentry, and stops there. Emitting from the SDK rather than from a
+ * single frontend means any integration can report one (AUGUST-7162) — subject
+ * to the CORS caveat on {@link DEFAULT_CURATOR_ALERT_ENDPOINT}.
+ *
+ * **Trust model.** The endpoint is public by construction — it ships in this
+ * bundle — so the relay treats every event as untrusted input, not as an
+ * attested fact. The SDK's job is to report accurately; the relay's job is to
+ * verify, rate-limit per `{vault, wallet}`, and drop events naming a vault
+ * outside its routing map. `'submission'` events carry a `txHash` the relay can
+ * confirm on chain, which makes them unforgeable; `'simulation'` events have no
+ * on-chain artifact and are treated as the weaker claim. Nothing
+ * credential-shaped is reachable from here: no bot token, no chat id, no
+ * curator identity.
+ *
+ * **Side effects.** At most one `POST` to the relay, fire-and-forget: this runs
+ * inside a `catch` on a money path, so it never awaits, never throws back into
+ * the caller, and never alters the error the caller sees. Suppressed to one
+ * send per `{contractId, eoa, phase, resultCode, error class}` per 10 minutes,
+ * so a wallet retrying a deterministic failure costs a single request. Note the
+ * receiving service applies its own, coarser window on top. A no-op when
+ * reporting is disabled (see {@link areCuratorAlertsEnabled}) and, unless a
+ * custom endpoint is configured, for any network other than mainnet — a
+ * testnet failure is not a curator's problem.
+ *
+ * @param event - The failed attempt. `error` is sanitized (secrets scrubbed via
+ *   `sanitizeString`) and capped at 1500 characters before it leaves the
+ *   process; `sharesRaw` is relayed unscaled, and the receiving service scales
+ *   it for display with the decimals it holds for that vault — which for an
+ *   offset vault are the asset's, not the share token's, so the figure a curator
+ *   sees is a magnitude rather than an exact amount (see AUGUST-6381).
+ * @internal
+ */
+function reportRedeemFailure(event) {
+    if (!areCuratorAlertsEnabled())
+        return;
+    if (!event.contractId || !event.eoa || !event.error || !event.sharesRaw) {
+        return;
+    }
+    // Production networks only. Every family names its production network
+    // `mainnet` except Solana (`mainnet-beta`), which is why this is a prefix
+    // test rather than an equality one — a testnet failure is not a curator's
+    // problem, and reporting it would spend a real vault's alert budget.
+    if (!event.network.startsWith('mainnet') && !endpointOverridden)
+        return;
+    const safeError = (0, sanitize_1.sanitizeString)(String(event.error)).slice(0, MAX_ERROR_CHARS);
+    // The two fields that exist only on the submission member, read once through
+    // the discriminant so everything below stays shape-agnostic.
+    const submission = event.phase === 'submission' ? event : undefined;
+    const key = [
+        event.contractId,
+        event.eoa,
+        event.phase,
+        submission?.resultCode ?? '',
+        errorSignature(safeError),
+    ].join('|');
+    if (alertDedupe.has(key))
+        return;
+    alertDedupe.set(key, true);
+    // Coerced rather than trusted: this type is `@internal` but deep-importable,
+    // so an untyped consumer can reach it with a `bigint`, which `JSON.stringify`
+    // rejects. Emptiness is already handled by the guard above.
+    const body = JSON.stringify({
+        event: 'vault.redeem.failed',
+        phase: event.phase,
+        chain: event.chain,
+        network: event.network,
+        contractId: event.contractId,
+        eoa: event.eoa,
+        sharesRaw: String(event.sharesRaw),
+        txHash: submission?.txHash,
+        resultCode: submission?.resultCode,
+        error: safeError,
+        timestamp: new Date().toISOString(),
+        appName: reporterAppName,
+    });
+    (async () => {
+        const res = await fetch(endpoint, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body,
+            signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+        });
+        const status = res?.status ?? 0;
+        if (status >= 200 && status < 300)
+            return;
+        // A 4xx is the endpoint answering: the report was rejected (422), or we are
+        // being throttled (429). Keep the suppression key — retrying a rejected
+        // report cannot make it acceptable, and answering a rate limit by removing
+        // our own backpressure is the wrong direction (CLAUDE.md §4.2). A 5xx or a
+        // transport failure means the report never landed, so release it.
+        if (status < 400 || status >= 500)
+            alertDedupe.delete(key);
+        console.warn('#CuratorAlert.stellarRedeemFailure:', status, res?.statusText);
+    })().catch((e) => {
+        alertDedupe.delete(key);
+        console.warn('#CuratorAlert.redeemFailure.unreachable:', (0, sanitize_1.sanitizeString)(String(e?.message ?? e)));
+    });
+}
+//# sourceMappingURL=curator-alert.js.map

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

@@ -96,3 +96,4 @@ declare const Logger: {
 };
 import * as slack from './slack';
 export { slack as Slack, Logger };
+export { configureCuratorAlerts, areCuratorAlertsEnabled, CURATOR_ALERTS_DISABLE_ENV_VAR, type ICuratorAlertsConfig, type ICuratorAlertsContext, } from './curator-alert';

package/lib/core/logger/index.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Logger = exports.Slack = void 0;
+exports.CURATOR_ALERTS_DISABLE_ENV_VAR = exports.areCuratorAlertsEnabled = exports.configureCuratorAlerts = exports.Logger = exports.Slack = void 0;
 const sanitize_1 = require("../analytics/sanitize");
 let logger = null;
 let structuredLogger = null;
@@ -141,4 +141,23 @@ const Logger = {
 exports.Logger = Logger;
 const slack = __importStar(require("./slack"));
 exports.Slack = slack;
+// Only the opt-out is public: code that drives the `Stellar` namespace directly
+// never constructs an `AugustSDK`, so `configureCuratorAlerts` is its sole way
+// to turn curator alerts off (and the only one that works in a browser, where
+// the env var is unreadable). The emitter itself stays deep-import only — a
+// partner has no reason to inject events into the relay.
+//
+// Safe to re-export from this barrel at all because `curator-alert` imports only
+// `types/`, `constants/` and leaf helpers under `core/analytics/` — never this
+// file — so there is no cycle back through the logger. `madge --circular` in CI
+// is the enforcement; this note is why it passes (CLAUDE.md §9).
+//
+// Both parameter types travel with the function: `ICuratorAlertsContext` is the
+// second argument's type, so without it a consumer cannot type a wrapper around
+// `configureCuratorAlerts` — and API Extractor flags it as a forgotten export
+// (CLAUDE.md §6).
+var curator_alert_1 = require("./curator-alert");
+Object.defineProperty(exports, "configureCuratorAlerts", { enumerable: true, get: function () { return curator_alert_1.configureCuratorAlerts; } });
+Object.defineProperty(exports, "areCuratorAlertsEnabled", { enumerable: true, get: function () { return curator_alert_1.areCuratorAlertsEnabled; } });
+Object.defineProperty(exports, "CURATOR_ALERTS_DISABLE_ENV_VAR", { enumerable: true, get: function () { return curator_alert_1.CURATOR_ALERTS_DISABLE_ENV_VAR; } });
 //# sourceMappingURL=index.js.map

package/lib/sdk.d.ts

@@ -15112,6 +15112,30 @@ export declare type ApproveResult =
     kind: 'native';
 };
 
+/**
+ * Whether an alert would be sent right now.
+ *
+ * Quiet by default outside production, mirroring `analytics`: a partner's Jest
+ * suite or `next dev` session exercising a failing redeem must not page a real
+ * curator. Two gates are needed for that, because they cover different
+ * runtimes — `NODE_ENV` is the Node one, and bundlers strip or stub
+ * `process.env` in the browser, so a locally-served app is recognised by its
+ * hostname instead (CLAUDE.md §5). Without that gate, a browser app run
+ * against mainnet from any loopback or private origin — `localhost`, a
+ * container on `172.20.0.0/16`, `[::1]` — pages a real curator on every
+ * failed redeem. `isLocalhost` in `core/analytics/env` lists the ranges.
+ *
+ * `enabled: true` overrides both — it is the documented way to exercise the
+ * path deliberately, and the SDK's own suite relies on it.
+ *
+ * The env var is read per call (not once at module load) so a consumer that
+ * sets it after import is still honoured, and a test can set and unset it
+ * without re-importing. It deliberately outranks an explicit `enabled: true`:
+ * it is the kill switch, and an operator setting it should not have to find
+ * and edit the construction site to be obeyed.
+ */
+export declare function areCuratorAlertsEnabled(): boolean;
+
 declare type AsArray<T> = T extends readonly unknown[] ? T : never;
 
 /**
@@ -15822,8 +15846,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);
                   /**
@@ -17530,6 +17554,23 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                       */
                      export declare function computeArgShape(args: unknown[]): string[];
 
+                     /**
+                      * Apply constructor config. Called unconditionally by `AugustBase` so an
+                      * instance that omits `curatorAlerts` RESETS to the defaults rather than
+                      * inheriting a prior instance's settings — same contract as
+                      * `setPublicApiBaseUrl` and `setAttribution`.
+                      *
+                      * Also the supported opt-out for code that calls the `Stellar` namespace
+                      * functions directly without constructing an `AugustSDK` (the testnet flow in
+                      * the docs), and the only one that works in a browser, where the env var is
+                      * unreadable.
+                      *
+                      * @param config - `monitoring.curatorAlerts`, or `null` to restore defaults.
+                      * @param context - Facts about the reporting instance; omitted entirely by a
+                      *   caller that only wants to disable reporting.
+                      */
+                     export declare function configureCuratorAlerts(config: ICuratorAlertsConfig | null, context?: ICuratorAlertsContext): void;
+
                      /**
                       * Query the vault's `convert_to_shares` to preview how many shares a deposit
                       * amount would yield.  Returns the raw share amount as a string, or null on
@@ -17627,6 +17668,9 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                       */
                      export declare function crossChainVaultRedeem(props: ICrossChainRedeemRequest): Promise<ICrossChainRedeemResult>;
 
+                     /** Env equivalent of `monitoring.curatorAlerts.enabled: false`. Node only. */
+                     export declare const CURATOR_ALERTS_DISABLE_ENV_VAR = "AUGUST_SDK_DISABLE_CURATOR_ALERTS";
+
                      /**
                       * Datetime
                       */
@@ -19810,6 +19854,19 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                   * `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}.
                                   */
@@ -19960,7 +20017,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
@@ -20408,6 +20466,46 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                      hubOnlyReceipt?: boolean;
                                  }
 
+                                 /** Curator-alert reporting. Enabled by default; this is the opt-out. */
+                                 export declare interface ICuratorAlertsConfig {
+                                     /**
+                                      * `false` stops emitting entirely. `true` forces emitting even in an
+                                      * environment the SDK would otherwise stay quiet in — it bypasses **every**
+                                      * environment gate: `NODE_ENV` of `development`/`test`, a browser served
+                                      * from a loopback or private host, and `monitoring.env` other than `PROD`.
+                                      * It does NOT lift the mainnet-only restriction; only `endpoint` does. A
+                                      * `DEV` or test
+                                      * integration that sets it and then fails a mainnet redeem pages a real
+                                      * curator, so use it only when deliberately exercising the path (pair it
+                                      * with `endpoint` to aim at a test relay). The only thing that still wins is
+                                      * the {@link CURATOR_ALERTS_DISABLE_ENV_VAR} kill switch.
+                                      */
+                                     enabled?: boolean;
+                                     /**
+                                      * Override the relay endpoint. Defaults to
+                                      * {@link DEFAULT_CURATOR_ALERT_ENDPOINT}. Setting it also lifts the
+                                      * mainnet-only restriction, so a staging relay can receive testnet failures.
+                                      */
+                                     endpoint?: string;
+                                 }
+
+                                 /** Ambient facts about the reporting SDK instance, supplied by `AugustBase`. */
+                                 export declare interface ICuratorAlertsContext {
+                                     /** Carried on the payload so August can tell partner traffic apart. */
+                                     appName?: string;
+                                     /**
+                                      * `monitoring.env`. Anything other than `'PROD'` keeps the SDK quiet unless
+                                      * `config.enabled` is explicitly `true`.
+                                      */
+                                     environment?: IEnv;
+                                     /**
+                                      * Effective base URL of the August public API. Reports follow the API this
+                                      * instance reads from, so a deployment pointed at a staging backend alerts
+                                      * staging rather than production.
+                                      */
+                                     apiBaseUrl?: string;
+                                 }
+
                                  /**
                                   * On-chain whitelist status of one subaccount linked to a vault, from
                                   * `GET /curator/vaults/{vault_address}/whitelist` (backend
@@ -20953,6 +21051,27 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                  declare interface IMonitoring extends IWSMonitorHeaders {
                                      slackWebhookUrl?: string;
                                      env?: IEnv;
+                                     /**
+                                      * Curator notifications for failed vault redemptions. Enabled by default
+                                      * (opt-out model, like `analytics`).
+                                      *
+                                      * Stellar vaults are instant-redeem only, so when a redemption fails the
+                                      * vault's curator has no other way to learn about it. The SDK relays the
+                                      * failure to August's notification service, which routes it to that curator's
+                                      * own channel — no credentials or curator identities are held here.
+                                      *
+                                      * Set `enabled: false` (or, in Node, the
+                                      * `AUGUST_SDK_DISABLE_CURATOR_ALERTS` env var) to stop emitting; set
+                                      * `endpoint` only to point a non-prod deployment at a test relay. Nothing is
+                                      * emitted unless `monitoring.env` is `PROD`, `NODE_ENV` is neither
+                                      * `development` nor `test`, and — in a browser, where `NODE_ENV` is not
+                                      * readable — the page is not served from localhost.
+                                      *
+                                      * `enabled: true` is the one exception: it bypasses all three gates, so a
+                                      * `DEV` or test integration that sets it can page a real curator. See
+                                      * {@link ICuratorAlertsConfig}.
+                                      */
+                                     curatorAlerts?: ICuratorAlertsConfig;
                                  }
 
                                  /* Excluded from this release type: IMulticall3Request */
@@ -20983,16 +21102,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;
@@ -26099,10 +26230,22 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                            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`
@@ -26214,6 +26357,14 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                                      *   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/package.json

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