@augustdigital/sdk 9.0.0 → 9.1.0

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;
 
 /**
@@ -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}.
                                   */
@@ -20409,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
@@ -20954,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 */
@@ -26112,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`
@@ -26227,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": "9.0.0",
+  "version": "9.1.0",
   "main": "lib/index.js",
   "types": "lib/sdk.d.ts",
   "keywords": [