@stable_sea/sdk 0.2.0 → 0.2.2

package/README.md

@@ -88,6 +88,28 @@ API request, response, pagination, and error types are generated from
 `services/backend/api/openapi.public.json` and exported as `paths`, `operations`,
 and `components`.
 
+## Balance history
+
+Read daily balance history with `money:read`:
+
+```ts
+const history = await client.GET("/v1/balance_history", {
+  params: { query: { window: "30d" } },
+});
+if (history.error) throw new Error(history.error.error.message);
+console.log(history.data.data);
+```
+
+Windows are `30d`, `90d` and `ytd`. Pending amounts include unfinished internal
+movements only. ACH, wire and on-chain deposits and withdrawals appear after
+settlement. Completed legs enter settled history while other legs can remain
+pending, so these amounts can differ from `/v1/balances`.
+
+USD amounts are null when unavailable;
+`aggregated` includes only priced settled balances. Check `unpriced_assets` for
+valuation gaps. History follows current account membership; use issued
+statements for immutable reporting.
+
 ## Money controls and rate limits
 
 Read `GET /v1/policies` with a key that has `money:read`.

package/dist/gen/schema.d.ts

@@ -64,6 +64,32 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/balance_history": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Read balance history
+         * @description Returns daily settled and pending balances for the authenticated business, grouped by asset, for the last 30 days, 90 days, or the current UTC year. Each series contains at most 367 samples.
+         *
+         *     Pending amounts include unfinished internal movements only. ACH, wire and on-chain deposits and withdrawals appear after settlement. Completed legs enter settled history even while other legs remain pending, so these amounts can differ from `/v1/balances`.
+         *
+         *     Amounts are decimal strings. A null USD amount means no valuation was available. Totals include priced settled balances; inspect `unpriced_assets` before treating them as a complete valuation.
+         *
+         *     This dashboard history uses the business's current account membership. Archived accounts are excluded, including from past samples. Use issued statements for immutable period reporting. Aggregate balances can include the effects of Payments, while individual Payments records remain excluded from the API.
+         */
+        get: operations["balance_history.snapshot"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/balances": {
         parameters: {
             query?: never;
@@ -975,7 +1001,7 @@ export interface components {
             pending_incoming_native: string;
             /** @description pending_incoming_native valued in USD. Omitted when no rate is available at created_ts. */
             pending_incoming_usd?: string;
-            /** @description Value outgoing from this balance and not yet settled, in the asset's own units. Never netted against pending_incoming_native. A single movement's pass-through legs are netted inside this figure: an account credited and debited within one movement counts once, not twice in both directions. */
+            /** @description Value reserved for outgoing movements or confirmed bank-return recovery, in the asset's own units. Never netted against pending_incoming_native. A single movement's pass-through legs are netted inside this figure: an account credited and debited within one movement counts once, not twice in both directions. */
             pending_outgoing_native: string;
             /** @description pending_outgoing_native valued in USD. Omitted when no rate is available at created_ts. */
             pending_outgoing_usd?: string;
@@ -987,6 +1013,45 @@ export interface components {
              */
             source: "custody";
         };
+        BalanceHistoryPoint: {
+            balance_native: string;
+            balance_usd: string | null;
+            pending_incoming_native: string;
+            pending_incoming_usd: string | null;
+            pending_outgoing_native: string;
+            pending_outgoing_usd: string | null;
+            /** Format: date-time */
+            sampled_ts: string;
+        };
+        BalanceHistorySeries: {
+            asset: string;
+            /** @enum {string} */
+            object: "balance_series";
+            points: components["schemas"]["BalanceHistoryPoint"][];
+        };
+        BalanceHistorySnapshot: {
+            aggregated: components["schemas"]["BalanceHistoryTotal"][];
+            data: components["schemas"]["BalanceHistorySeries"][];
+            /** Format: date-time */
+            end_ts: string;
+            livemode: boolean;
+            /** @enum {string} */
+            object: "balance_history";
+            /** Format: date-time */
+            observed_ts: string;
+            /** Format: date-time */
+            start_ts: string;
+            /** @description Assets with a nonzero native balance and no USD valuation in at least one sample. Their native balances remain available. */
+            unpriced_assets: string[];
+        };
+        BalanceHistoryTotal: {
+            /** @description Sum of the priced settled balances at this timestamp. Inspect unpriced_assets before treating it as a complete valuation. */
+            balance_usd: string;
+            /** Format: date-time */
+            sampled_ts: string;
+        };
+        /** @enum {string} */
+        BalanceHistoryWindow: "30d" | "90d" | "ytd";
         BalanceList: {
             data: components["schemas"]["Balance"][];
             has_more: boolean;
@@ -1222,11 +1287,13 @@ export interface components {
         /** @enum {string} */
         EventTypeName: "bank_account.created" | "bank_account.removed" | "bank_account_operation.updated" | "deposit.updated" | "deposit_quote.updated" | "external_wallet.created" | "external_wallet.updated" | "external_wallet_operation.updated" | "notification.created" | "order.updated" | "source_wallet_declaration.updated" | "transaction.created" | "transaction.updated";
         ExternalWallet: {
-            /** @description The wallet's on-chain address, exactly as the business connected it. */
+            /** @description True when a Stable Sea operator registered this wallet for the business; false when the business added it itself. */
+            added_by_stable_sea: boolean;
+            /** @description The wallet's on-chain address, exactly as it was registered. */
             address: string;
             /**
              * Format: date-time
-             * @description When the wallet was connected. The list is ordered and paged on this instant.
+             * @description When the wallet was added, by the business or by Stable Sea. The list is ordered and paged on this instant.
              */
             created_ts: string;
             /**
@@ -1252,7 +1319,7 @@ export interface components {
             livemode: boolean;
             /** @description Optional Stellar memo identifying this withdrawal destination. Address-level holdings are not reported when a memo is present. */
             memo?: string;
-            /** @description The name your business assigned to this wallet. */
+            /** @description The wallet's name, as set when it was registered or last renamed. */
             name?: string;
             /** @enum {string} */
             object: "external_wallet";
@@ -2149,6 +2216,45 @@ export interface operations {
             };
         };
     };
+    "balance_history.snapshot": {
+        parameters: {
+            query?: {
+                /** @description Thirty days, ninety days, or the current UTC year to date. */
+                window?: components["schemas"]["BalanceHistoryWindow"];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    "X-RateLimit-Limit": components["headers"]["X-RateLimit-Limit"];
+                    "X-RateLimit-Remaining": components["headers"]["X-RateLimit-Remaining"];
+                    "X-RateLimit-Reset": components["headers"]["X-RateLimit-Reset"];
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BalanceHistorySnapshot"];
+                };
+            };
+            400: components["responses"]["Error400"];
+            401: components["responses"]["Error401"];
+            403: components["responses"]["Error403"];
+            429: components["responses"]["Error429"];
+            /** @description Error response. */
+            default: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
     "balances.list": {
         parameters: {
             query?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stable_sea/sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "sideEffects": false,
   "files": [