@augustdigital/sdk 9.0.0 → 9.2.0

package/lib/core/base.class.js

@@ -8,6 +8,7 @@ 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");
+const curator_alert_1 = require("./logger/curator-alert");
 /**
  * Base class providing core SDK functionality including provider management,
  * network switching, and authentication state.
@@ -74,6 +75,16 @@ class AugustBase {
         // `publicApiBaseUrl`: called unconditionally so a prior instance's
         // builder codes never leak into a later instance in the same process.
         (0, attribution_1.setAttribution)(attribution ?? null);
+        // Same reset-on-omit contract, for the same reason: an instance that says
+        // nothing about curator alerts gets the default (on in production), not
+        // whatever a previously-constructed instance asked for.
+        // Reports follow the API this instance reads from — resolved AFTER
+        // `setPublicApiBaseUrl` above, so a staging deployment alerts staging.
+        (0, curator_alert_1.configureCuratorAlerts)(monitoring?.curatorAlerts ?? null, {
+            appName: this.appName,
+            environment: environment,
+            apiBaseUrl: (0, fetcher_1.getPublicApiBaseUrl)(),
+        });
     }
     /**
      * Verify API keys and authorize SDK usage.

package/lib/core/logger/curator-alert.d.ts

@@ -0,0 +1,217 @@
+import type { ChainType, IEnv } from '../../types';
+/**
+ * Path on the August public API that accepts a failed-redemption report. Chain
+ * lives in the payload, not the path — see {@link IRedeemFailureEvent.chain}.
+ */
+export declare const 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.
+ */
+export declare const DEFAULT_CURATOR_ALERT_ENDPOINT: string;
+/** Env equivalent of `monitoring.curatorAlerts.enabled: false`. Node only. */
+export declare const CURATOR_ALERTS_DISABLE_ENV_VAR = "AUGUST_SDK_DISABLE_CURATOR_ALERTS";
+/** Curator-alert reporting. Enabled by default; this is the opt-out. */
+export 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;
+}
+/** Fields every report carries, whatever stage the redemption failed at. */
+interface IRedeemFailureBase {
+    /**
+     * Chain family the vault lives on. Carried rather than assumed so the
+     * receiving endpoint stays one contract for every chain; it decides which
+     * families it actually serves, and validates the identifiers below by that
+     * family's rules.
+     */
+    chain: ChainType;
+    /**
+     * Network within the family, in that family's own vocabulary — Stellar's
+     * `mainnet`/`testnet`, Solana's `mainnet-beta`, an EVM network name. A plain
+     * string rather than one family's union, because the receiving endpoint
+     * validates it against the family named in `chain`; typing it as Stellar's
+     * two values would make this the narrower half of a contract the rest of this
+     * module describes as chain-agnostic.
+     */
+    network: string;
+    /** Vault identifier in the chain's own format. The endpoint routes on this. */
+    contractId: string;
+    /** Account that attempted the redemption, in the chain's own format. */
+    eoa: string;
+    /** Shares requested, in the vault's smallest unit (unscaled). */
+    sharesRaw: string;
+    /** Failure detail; sanitized and capped before it leaves the process. */
+    error: string;
+}
+/**
+ * A redemption the vault refused before anything reached chain — a failed
+ * simulation, or a vault whose ledger state needs restoring. There is no
+ * on-chain artifact, so the receiving endpoint has nothing to verify the claim
+ * against and treats it as the weaker of the two. Which build stage raised it
+ * stays legible in `error`.
+ */
+interface IRedeemBuildFailure extends IRedeemFailureBase {
+    phase: 'simulation';
+}
+/**
+ * A redemption that executed on chain and failed. `txHash` is what makes this
+ * the stronger claim — the endpoint can verify it — so it is required here
+ * rather than optional, which is the whole reason these are two types.
+ */
+interface IRedeemSubmissionFailure extends IRedeemFailureBase {
+    phase: 'submission';
+    /** The failed transaction. Verifiable, which is why it is not optional. */
+    txHash: string;
+    /** Transaction result code, when the result XDR decoded. */
+    resultCode?: string;
+}
+/**
+ * A redemption failure worth a curator's attention.
+ *
+ * Two members rather than one shape with optional fields, because `txHash` is
+ * only meaningful — and is always available — on the submission path. As a
+ * single interface, `{ phase: 'simulation', txHash }` and a submission report
+ * with no hash both type-checked, and the receiving endpoint's `is_well_formed`
+ * check was the only thing between either and a silently dropped alert. That
+ * check stays, since a server cannot trust its input, but it is no longer
+ * covering for a shape this SDK could have made unrepresentable. The two call
+ * sites in `adapters/stellar/` are the ones this actually constrains, and they
+ * are type-checked by `pnpm build`.
+ *
+ * @internal
+ */
+export type IRedeemFailureEvent = IRedeemBuildFailure | IRedeemSubmissionFailure;
+/** Ambient facts about the reporting SDK instance, supplied by `AugustBase`. */
+export 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;
+}
+/**
+ * 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;
+/**
+ * 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
+ */
+export declare function resetCuratorAlertDedupe(): void;
+/**
+ * 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;
+/**
+ * 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
+ */
+export declare function reportRedeemFailure(event: IRedeemFailureEvent): void;
+export {};

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

@@ -126,6 +126,12 @@ export declare class AugustSDK extends AugustBase {
      * `cefi` / `otc` arrays back the drill-downs. See the "Rendering the Vault
      * Exposure section" guide in the vaults docs for a faithful reproduction.
      *
+     * Stellar vaults resolve their DeFi exposure through the Untangled portfolio
+     * API instead of DeBank — one extra HTTP call, covering the idle buffer,
+     * Stellar protocol positions, custody wallets and bridged capital. If that
+     * call fails the exposure legs come back empty rather than throwing, so CeFi,
+     * OTC and loan allocations still resolve.
+     *
      * @param props - Vault address and chain ID
      * @returns Detailed breakdown of vault allocations by category
      * @example

package/lib/main.js

@@ -254,6 +254,12 @@ class AugustSDK extends core_1.AugustBase {
      * `cefi` / `otc` arrays back the drill-downs. See the "Rendering the Vault
      * Exposure section" guide in the vaults docs for a faithful reproduction.
      *
+     * Stellar vaults resolve their DeFi exposure through the Untangled portfolio
+     * API instead of DeBank — one extra HTTP call, covering the idle buffer,
+     * Stellar protocol positions, custody wallets and bridged capital. If that
+     * call fails the exposure legs come back empty rather than throwing, so CeFi,
+     * OTC and loan allocations still resolve.
+     *
      * @param props - Vault address and chain ID
      * @returns Detailed breakdown of vault allocations by category
      * @example

package/lib/modules/vaults/getters.d.ts

@@ -55,6 +55,15 @@ export declare function getVaultSubaccountLoans(vault: VaultAddress | IVault, op
  * Fetch comprehensive vault asset allocation breakdown.
  * Includes DeFi protocols (via DeBank), CeFi balances, OTC positions, and loans.
  * Categorizes exposures by borrowing, supplying, lending, and wallet holdings.
+ *
+ * DeFi exposure resolves per chain family: EVM vaults via DeBank, Solana
+ * borrowers via Octav.fi, and Stellar vaults via the Untangled portfolio API —
+ * one vault-level call covering the idle buffer, Stellar protocol positions,
+ * custody wallets, and capital bridged to other chains. The Stellar path adds
+ * exactly 1 HTTP call and zero for every other chain; when it fails, the
+ * exposure section comes back empty and the CeFi, OTC and loan allocations are
+ * still returned.
+ *
  * @param vault - Vault address
  * @param options - RPC configuration
  * @returns Detailed allocation data with exposure categorization

package/lib/modules/vaults/getters.js

@@ -84,6 +84,7 @@ const TokenizedVaultV2_1 = require("../../abis/TokenizedVaultV2");
 const TokenizedVaultV2Receipt_1 = require("../../abis/TokenizedVaultV2Receipt");
 const ethereum_block_by_date_1 = __importDefault(require("ethereum-block-by-date"));
 const octavfi_1 = require("../../services/octavfi");
+const untangled_1 = require("../../services/untangled");
 const date_utils_1 = require("./utils/date-utils");
 const call_data_decoder_1 = require("./utils/call-data-decoder");
 const deposits_1 = require("../../services/layerzero/deposits");
@@ -433,6 +434,15 @@ function httpStatusFromError(error) {
  * Fetch comprehensive vault asset allocation breakdown.
  * Includes DeFi protocols (via DeBank), CeFi balances, OTC positions, and loans.
  * Categorizes exposures by borrowing, supplying, lending, and wallet holdings.
+ *
+ * DeFi exposure resolves per chain family: EVM vaults via DeBank, Solana
+ * borrowers via Octav.fi, and Stellar vaults via the Untangled portfolio API —
+ * one vault-level call covering the idle buffer, Stellar protocol positions,
+ * custody wallets, and capital bridged to other chains. The Stellar path adds
+ * exactly 1 HTTP call and zero for every other chain; when it fails, the
+ * exposure section comes back empty and the CeFi, OTC and loan allocations are
+ * still returned.
+ *
  * @param vault - Vault address
  * @param options - RPC configuration
  * @returns Detailed allocation data with exposure categorization
@@ -532,6 +542,21 @@ async function getVaultAllocations(vault, options) {
                 }
             }
         }
+        else if ((0, core_1.getAddressChainType)(vault) === 'stellar') {
+            // Untangled reconciles the whole Stellar vault in one call — idle buffer,
+            // Stellar protocol positions, custody wallets, and value bridged to other
+            // chains. It is keyed by vault, not by borrower, so it runs here rather
+            // than in the per-borrower loop below, which would multiply the totals.
+            const untangledExposure = await (0, untangled_1.fetchUntangledVaultExposure)(vault);
+            // A miss leaves the exposure section empty — never `debankErr`. See the
+            // `no_fetcher` branch below for why throwing here was wrong.
+            if (untangledExposure) {
+                const untangledRes = (0, untangled_1.transformUntangledToDebank)(untangledExposure);
+                (0, debank_1.parseVaultLevelDebank)(untangledRes, protocolExposure, tokenExposure, vault, exposurePerCategory, netValue);
+                unfilteredTokens = untangledRes.subaccount.tokens;
+                defiPerBorrower[vault] = (0, debank_1.parseLoanLevelDebank)(untangledRes);
+            }
+        }
         // Fetch portfolio data for non-EVM borrowers (EVM handled by fetchVaultDebankResponse above).
         // CeFi and OTC fetches below run for ALL borrowers regardless of chain type.
         for (const borrower of uniqueBorrowers) {