@stable_sea/sdk 0.2.3 → 0.2.5

package/README.md

@@ -182,6 +182,16 @@ and wire transfers use the instructions returned by funding.
 See [the funding guide](../../docs/api/funding.md) for the complete sequence,
 permissions and retry behavior.
 
+## Statement previews
+
+Read the current month's interim document with
+`client.GET("/v1/statements/preview")` and `money:read`. Its display-ready
+balances, transactions and fees use the same native calculation as Terminal.
+Values refresh about once a minute. Check `observed_ts`; missing,
+stale or previous-month previews return 503. Opening balances remain provisional
+until the previous month's statement is issued. Issued documents continue to use
+`GET /v1/statements/{id}`.
+
 ## Contract changes
 
 - `GET /v1/balances`: `chain` gains the value `solana`. A USDC balance held on

package/dist/gen/schema.d.ts

@@ -596,6 +596,30 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/price_history": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Read market price history
+         * @description Returns the BTC/USD market-price chart used by Terminal for the last thirty days, ninety days or current UTC year. Prices are decimal strings and do not depend on your holdings. The series contains about fifty samples, carrying forward the latest cached close at or before each sample. The underlying market-data cache retains ninety days, so a year-to-date request can contain a shorter available history.
+         *
+         *     Inspect `source`: `historical` means normalized historical prices, `spot` means a flat two-point line at the current price because history was unavailable, and `unavailable` means no prices were available. A spot fallback does not describe past prices.
+         *
+         *     The worker refreshes this observation about once a minute. `observed_ts` is the calculation start; the reads are not an atomic market snapshot. Missing, failed or older-than-two-minutes observations return HTTP 503. Requires `investments:read`.
+         */
+        get: operations["price_history.snapshot"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/quotes": {
         parameters: {
             query?: never;
@@ -678,6 +702,68 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/statement_generations": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Generate a statement
+         * @description Requests the business's official statement for a closed UTC calendar month. Requires `money:statements_write` and an `Idempotency-Key`. Poll the returned generation with `money:read` until it succeeds or fails, then retrieve its `statement`. Existing statements are returned without reissuing them. Current key access, business availability and business statement eligibility are checked before execution. Retrying the same request and key returns its original pending receipt; the generation read reports the current outcome.
+         *
+         *     Idempotency keys are shared by the business within one environment, including across API credentials and rotation. A replay keeps the original submitting credential as the processing authority; it does not replace that credential with the retrying key.
+         */
+        post: operations["statement_generations.create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/statement_generations/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Retrieve a statement generation
+         * @description Returns the current processing outcome for this business and key environment. `pending` means processing or retrying; `succeeded` names the issued statement; `failed` includes a safe `failure_code`. A failed request does not cancel or change an issued statement. Resolve the cause before submitting another request with a new idempotency key.
+         */
+        get: operations["statement_generations.get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/statement_periods": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List supported statement periods
+         * @description Lists supported statement period types and their earliest UTC month start. Monthly generation also requires a closed month and the business's current business statement eligibility. Use this catalog with the issued statement list to choose a month. A supported calendar period is not a guarantee that a missing earlier statement can be issued after a later period has already been issued. This reference data is the same in Live and Sandbox.
+         */
+        get: operations["statement_periods.catalog"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/statements": {
         parameters: {
             query?: never;
@@ -698,6 +784,30 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/statements/preview": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Preview the current statement
+         * @description Returns the authenticated business's month-to-date statement as display-ready JSON. Requires `money:read` and at least one money account that has not been archived. This read does not issue a statement. The preview refreshes about once a minute; an unavailable or older-than-two-minutes preview returns HTTP 503. At a UTC month boundary, it may be unavailable until the first refresh.
+         *
+         *     Figures update until the month closes. Opening balances remain provisional until the previous month's statement is issued. The period uses UTC and ends at the preview time, normally rounded down to the minute. `observed_ts` is the preview calculation start; the underlying reads are not an atomic snapshot.
+         *
+         *     Transactions exclude pay-ins and payouts, while balances and totals include their effects. Pending movements and movements settled across a period boundary can also prevent transaction amounts from reconciling to the totals. Missing valuations refuse the preview instead of reporting held assets as zero.
+         */
+        get: operations["statements.preview"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/statements/{id}": {
         parameters: {
             query?: never;
@@ -1285,7 +1395,7 @@ export interface components {
             object: "list";
         };
         /** @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";
+        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" | "statement_generation.updated" | "transaction.created" | "transaction.updated";
         ExternalWallet: {
             /** @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;
@@ -1481,6 +1591,25 @@ export interface components {
             holder_identifier?: string;
             legal_entity_name: string;
         };
+        MarketPricePoint: {
+            close_usd: string;
+            /** Format: date-time */
+            sampled_ts: string;
+        };
+        MarketPriceSeries: {
+            /** @enum {string} */
+            asset: "BTC";
+            /** @enum {string} */
+            object: "market_price_series";
+            points: components["schemas"]["MarketPricePoint"][];
+            /** @enum {string} */
+            quote_asset: "USD";
+            /**
+             * @description historical is the normalized market series. spot is a flat current-price fallback, not historical observations. unavailable carries no points.
+             * @enum {string}
+             */
+            source: "historical" | "spot" | "unavailable";
+        };
         /** @description Customer metadata. Sensitive data is forbidden. */
         Metadata: {
             [key: string]: string;
@@ -1660,6 +1789,19 @@ export interface components {
         };
         /** @enum {string} */
         PolicyWindowKind: "calendar_day" | "calendar_week" | "rolling_24h" | "rolling_72h";
+        PriceHistorySnapshot: {
+            data: components["schemas"]["MarketPriceSeries"][];
+            /** Format: date-time */
+            end_ts: string;
+            livemode: boolean;
+            /** @enum {string} */
+            object: "price_history";
+            /** Format: date-time */
+            observed_ts: string;
+            /** Format: date-time */
+            start_ts: string;
+            window: components["schemas"]["BalanceHistoryWindow"];
+        };
         Quote: {
             amount_usd: string;
             /** @enum {string} */
@@ -1799,6 +1941,32 @@ export interface components {
             type: "ach_offramp" | "ach_onramp" | "adjustment" | "buy_fund_token" | "buy_fund_token_return" | "buy_fund_token_return_sweep" | "deposit_hold" | "deposit_return" | "deposit_reversal" | "fund_cash_subscription" | "fund_dividend_payout" | "fund_distribution_payout" | "fund_gas_tank" | "fund_xlm_reserve" | "gas_tank_refill" | "gas_wallet_funding" | "go_account_conversion" | "go_account_custodial_transfer" | "go_account_external_send" | "held_deposit_release" | "onchain_deposit" | "onchain_withdrawal" | "ramp_fee_refund" | "reclassification" | "sell_fund_token" | "sell_fund_token_return" | "trade_order" | "treasury_booking" | "treasury_wire_credit" | "wire_offramp" | "wire_onramp";
             withdrawal?: components["schemas"]["StatementWithdrawal"];
         };
+        StatementGeneration: {
+            /** Format: date-time */
+            created_ts: string;
+            /**
+             * @description Reason processing failed. Correct the cause before submitting a new request with a new idempotency key.
+             * @enum {string}
+             */
+            failure_code?: "permission_denied" | "api_key_revoked" | "business_locked" | "terms_acceptance_required" | "api_access_disabled" | "statement_ineligible" | "invalid_statement_month" | "statement_generation_refused" | "statement_processing_unavailable";
+            id: string;
+            livemode: boolean;
+            /** @enum {string} */
+            object: "statement_generation";
+            /** Format: date-time */
+            period_start_ts: string;
+            /** @description The issued statement after processing succeeds. Retrieve it with GET /v1/statements/{id}. */
+            statement?: string;
+            /** @enum {string} */
+            status: "pending" | "succeeded" | "failed";
+        };
+        StatementGenerationInput: {
+            /**
+             * Format: date-time
+             * @description The first instant of a closed calendar month in UTC, for example 2026-09-01T00:00:00Z. Read available_from_ts in the statement-period catalog for the earliest supported period. Business statement eligibility still applies.
+             */
+            period_start_ts: string;
+        };
         StatementLine: {
             ending_native: string;
             ending_usd: string;
@@ -1823,6 +1991,32 @@ export interface components {
             /** Format: date-time */
             start_ts: string;
         };
+        StatementPeriodAvailability: {
+            /** Format: date-time */
+            available_from_ts: string;
+            /** @enum {string} */
+            object: "statement_period";
+            /** @enum {string} */
+            type: "monthly";
+        };
+        StatementPeriodCatalog: {
+            data: components["schemas"]["StatementPeriodAvailability"][];
+            /** @enum {string} */
+            object: "list";
+        };
+        StatementPreview: {
+            balances: components["schemas"]["StatementLine"][];
+            livemode: boolean;
+            /** @enum {string} */
+            object: "statement_preview";
+            /** Format: date-time */
+            observed_ts: string;
+            period: components["schemas"]["StatementPeriod"];
+            ramp_fees?: components["schemas"]["StatementRampFee"][];
+            totals: components["schemas"]["StatementTotals"];
+            /** @description In-scope movements. Pay-ins and payouts are excluded, although balances and totals include their effects. Pending entries can contain provisional amounts. */
+            transactions: components["schemas"]["StatementEntry"][];
+        };
         StatementRampFee: {
             /** Format: date-time */
             assessed_ts: string;
@@ -3310,6 +3504,45 @@ export interface operations {
             };
         };
     };
+    "price_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"]["PriceHistorySnapshot"];
+                };
+            };
+            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"];
+                };
+            };
+        };
+    };
     "quotes.quote": {
         parameters: {
             query: {
@@ -3470,6 +3703,123 @@ export interface operations {
             };
         };
     };
+    "statement_generations.create": {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["Idempotency-Key"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["StatementGenerationInput"];
+            };
+        };
+        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"]["StatementGeneration"];
+                };
+            };
+            400: components["responses"]["Error400"];
+            401: components["responses"]["Error401"];
+            403: components["responses"]["Error403"];
+            409: components["responses"]["Error409"];
+            429: components["responses"]["Error429"];
+            /** @description Error response. */
+            default: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    "statement_generations.get": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            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"]["StatementGeneration"];
+                };
+            };
+            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"];
+                };
+            };
+        };
+    };
+    "statement_periods.catalog": {
+        parameters: {
+            query?: never;
+            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"]["StatementPeriodCatalog"];
+                };
+            };
+            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"];
+                };
+            };
+        };
+    };
     "statements.list": {
         parameters: {
             query?: {
@@ -3513,6 +3863,42 @@ export interface operations {
             };
         };
     };
+    "statements.preview": {
+        parameters: {
+            query?: never;
+            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"]["StatementPreview"];
+                };
+            };
+            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"];
+                };
+            };
+        };
+    };
     "statements.retrieve": {
         parameters: {
             query?: never;

package/package.json

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