@stable_sea/sdk 0.2.27 → 0.2.28

package/README.md

@@ -99,6 +99,64 @@ do not place another subscription to resolve it. Instructions can lag the native
 state: retry a 503 read. Sandbox instructions are synthetic and must never be used
 to send real funds. Existing native eligibility, agreements and controls apply.
 
+## Manage trading schedules
+
+Use `investments:read` to list schedules and run history. Create, edit, pause,
+resume and delete schedules with `investments:automations_write`. An API-created
+schedule executes using its original key, which also needs `investments:write`
+and, for BTC, `investments:btc_write`. Rotation or revocation stops new runs;
+editing with another key does not transfer execution ownership. Human-created
+Terminal schedules retain their creator's current member permissions.
+
+```ts
+const creation = client.mutation();
+const created = await creation.POST("/v1/automations", {
+  body: {
+    name: "Daily USDC investment",
+    side: "buy",
+    denomination: "usd",
+    source_symbol: "USDC",
+    destination_symbol: "WTGXX",
+    condition_operator: "above",
+    condition_threshold: "1000",
+    sweep_type: "fixed",
+    sweep_amount: "25",
+    cadence_frequency: "daily",
+    cadence_days_of_week: [],
+    cadence_time_of_day: "09:00",
+    cadence_timezone: "America/New_York",
+    settlement: "standard",
+    skip_weekends: true,
+  },
+});
+if (created.error) throw new Error(created.error.error.message);
+console.log(created.data.id, created.data.status);
+```
+
+Creation enables the schedule. Retrieve `GET /v1/automations/{id}` until its
+configuration `status` is `ready` or `failed`. A failed edit leaves the previous
+configuration effective; inspect `failure_code` and `error_message` before
+correcting it. Save and reuse each mutation's body and idempotency key after a
+lost response. Use a new mutation for a corrected request. If creation itself
+fails, delete the failed resource and create a corrected schedule.
+
+Use `POST /v1/automations/{id}` with `enabled: false` to pause, or `true` to
+resume. Omitted or null update fields remain unchanged. Direction cannot change;
+changing `denomination` also requires `condition_threshold` and `sweep_amount`.
+`DELETE /v1/automations/{id}` needs no body or idempotency key. Repeat it while
+HTTP 202 reports pending removal; only HTTP 200 with `deleted: true` confirms
+removal. Deletion does not reverse an accepted trade.
+
+List `GET /v1/automation_runs?automation={id}` for execution history, including
+removed schedules. Runs can be `pending`, `completed`, `failed` or `skipped`.
+`completed` means a trade was booked; follow `transaction_id` to confirm
+settlement. The `automation_run.updated` webhook announces a terminal run and
+links to its current resource. New runs retain their original `denomination` and
+`symbol`; those fields are omitted on older runs without a unit snapshot.
+Unattended trades that require human approval are refused rather than queued for
+a vote. Current business controls, key grants, agreements and asset eligibility
+apply to every run. Test keys manage isolated sandbox schedules.
+
 ## Cancel an unbooked order
 
 Use the original key with `investments:write` to request cancellation. Save the

package/dist/gen/schema.d.ts

@@ -64,6 +64,98 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/automation_runs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List automation runs
+         * @description Lists trading-schedule runs, newest first. Optionally filter by `automation`. History includes deleted schedules. A completed run booked a trade; retrieve its transaction to follow settlement.
+         */
+        get: operations["automation_runs.list"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/automation_runs/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Retrieve an automation run
+         * @description Returns the outcome of one schedule run, including runs whose schedule was deleted. A transaction id links to the booked trade and its settlement history.
+         */
+        get: operations["automation_runs.get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/automations": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List automations
+         * @description Lists the business's trading schedules, newest first, including schedules created in Terminal. Deleted schedules are excluded; their run history remains available. Test keys read isolated sandbox schedules.
+         */
+        get: operations["automations.list"];
+        put?: never;
+        /**
+         * Create an automation
+         * @description Creates an enabled trading schedule. Wait for `status: ready`; a refused configuration has `status: failed` and a `failure_code`. Each run checks the original credential's current scheduling and trading grants, business permissions and money controls. Rotation or revocation stops new runs. Requires `investments:automations_write` and an `Idempotency-Key`.
+         */
+        post: operations["automations.create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/automations/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Retrieve an automation
+         * @description Returns a schedule and its latest configuration processing status. Use automation runs to inspect execution and transactions to inspect settlement.
+         */
+        get: operations["automations.get"];
+        put?: never;
+        /**
+         * Update an automation
+         * @description Updates a schedule; set `enabled` to pause or resume it. Omitted or null fields remain unchanged. Trade direction and original execution credential cannot change. Wait for `status: ready` before relying on an edit; a refused edit leaves the previous configuration effective. Requires `investments:automations_write` and an `Idempotency-Key`.
+         */
+        post: operations["automations.update"];
+        /**
+         * Delete an automation
+         * @description Removes a trading schedule. HTTP 202 returns the schedule while removal is pending, or its failure code after a refused attempt. Repeat DELETE to check progress or retry a failed attempt. Failed creates can also be removed. If another configuration change is pending, wait for it to finish before deleting. HTTP 200 with `deleted: true` confirms committed removal. Run and transaction history is preserved; an accepted trade is not reversed. Send no body or idempotency key.
+         */
+        delete: operations["automations.delete"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/balance_history": {
         parameters: {
             query?: never;
@@ -1272,6 +1364,189 @@ export interface components {
             /** @enum {string} */
             object: "list";
         };
+        Automation: {
+            /** @description The original execution credential. Omitted for a human-created Terminal schedule. */
+            api_client?: string;
+            cadence_day_of_month?: number;
+            /** @description Weekly execution days. Sunday is 0 and Saturday is 6; empty for other cadences. */
+            cadence_days_of_week: (0 | 1 | 2 | 3 | 4 | 5 | 6)[];
+            /** @enum {string} */
+            cadence_frequency: "daily" | "weekly" | "monthly" | "once";
+            /** @description Local calendar date as YYYY-MM-DD. Required for a one-time schedule. */
+            cadence_start_date?: string;
+            /** @description Local execution time as HH:MM. */
+            cadence_time_of_day: string;
+            /** @description An IANA time zone, such as America/New_York. */
+            cadence_timezone: string;
+            /** @enum {string} */
+            condition_operator: "above" | "below";
+            condition_threshold: string;
+            /** Format: date-time */
+            created_ts: string;
+            /**
+             * @description How to read the threshold and fixed sweep amount. units is supported only for sells.
+             * @enum {string}
+             */
+            denomination: "usd" | "units";
+            destination_symbol: string;
+            /** @description Whether the schedule is enabled. Each run still checks its condition, cadence and current authority. */
+            enabled: boolean;
+            /** @description A customer-safe explanation of the latest refused configuration change. */
+            error_message?: string;
+            /** @description Why the latest configuration write failed. Existing configuration remains effective after a refused edit. */
+            failure_code?: string;
+            id: string;
+            livemode: boolean;
+            name: string;
+            /** @enum {string} */
+            object: "automation";
+            /**
+             * @description One-time schedules only. spent means the schedule has no remaining execution window.
+             * @enum {string}
+             */
+            schedule_state?: "scheduled" | "spent";
+            /**
+             * @description Trade settlement option. instant is available only for supported assets and pathways.
+             * @enum {string}
+             */
+            settlement: "standard" | "instant";
+            /**
+             * @description Trade direction. Fixed when the schedule is created.
+             * @enum {string}
+             */
+            side: "buy" | "sell";
+            skip_weekends: boolean;
+            source_symbol: string;
+            /**
+             * @description Configuration processing state. Wait for ready before relying on a change.
+             * @enum {string}
+             */
+            status: "pending" | "ready" | "failed";
+            /** @description A fixed amount in denomination units, or a whole percentage from 1 to 100. */
+            sweep_amount: string;
+            /** @enum {string} */
+            sweep_type: "fixed" | "percentage";
+        };
+        AutomationCreateInput: {
+            cadence_day_of_month?: number;
+            /** @description Weekly execution days. Sunday is 0 and Saturday is 6; empty for other cadences. */
+            cadence_days_of_week: components["schemas"]["AutomationWeekday"][];
+            /** @enum {string} */
+            cadence_frequency: "daily" | "weekly" | "monthly" | "once";
+            /** @description Local calendar date as YYYY-MM-DD. Required for a one-time schedule. */
+            cadence_start_date?: string;
+            /** @description Local execution time as HH:MM. */
+            cadence_time_of_day: string;
+            /** @description An IANA time zone, such as America/New_York. */
+            cadence_timezone: string;
+            /** @enum {string} */
+            condition_operator: "above" | "below";
+            condition_threshold: string;
+            /**
+             * @description How to read the threshold and fixed sweep amount. units is supported only for sells.
+             * @enum {string}
+             */
+            denomination: "usd" | "units";
+            destination_symbol: string;
+            name: string;
+            /**
+             * @description Trade settlement option. instant is available only for supported assets and pathways.
+             * @enum {string}
+             */
+            settlement: "standard" | "instant";
+            /**
+             * @description Trade direction. Fixed when the schedule is created.
+             * @enum {string}
+             */
+            side: "buy" | "sell";
+            skip_weekends: boolean;
+            source_symbol: string;
+            /** @description A fixed amount in denomination units, or a whole percentage from 1 to 100. */
+            sweep_amount: string;
+            /** @enum {string} */
+            sweep_type: "fixed" | "percentage";
+        };
+        AutomationDeleted: {
+            /** @enum {boolean} */
+            deleted: true;
+            id: string;
+        };
+        AutomationList: {
+            data: components["schemas"]["Automation"][];
+            has_more: boolean;
+            /** @enum {string} */
+            object: "list";
+        };
+        AutomationRun: {
+            /** @description The recorded trade amount in this run's original units. */
+            amount_transferred?: string;
+            automation: string;
+            /** @description The observed balance in this run's recorded units. */
+            balance_at_check: string;
+            /** Format: date-time */
+            completed_ts?: string;
+            condition_met: boolean;
+            /** Format: date-time */
+            created_ts: string;
+            /**
+             * @description The units used when this run executed. Omitted for historical runs without a unit snapshot.
+             * @enum {string}
+             */
+            denomination?: "usd" | "units";
+            /** @description A customer-safe native refusal or failure explanation. */
+            error_message?: string;
+            /** @description A stable failure classification. Unclassified historical failures use execution_failed. */
+            failure_code?: string;
+            id: string;
+            livemode: boolean;
+            /** @enum {string} */
+            object: "automation_run";
+            skip_reason?: string;
+            /**
+             * @description The execution outcome. completed means a trade was booked; retrieve its transaction for settlement.
+             * @enum {string}
+             */
+            status: "pending" | "completed" | "failed" | "skipped";
+            /** @description The original asset used to label balance_at_check and amount_transferred. Omitted when not recorded. */
+            symbol?: string;
+            transaction_id?: string;
+        };
+        AutomationRunList: {
+            data: components["schemas"]["AutomationRun"][];
+            has_more: boolean;
+            /** @enum {string} */
+            object: "list";
+        };
+        AutomationUpdateInput: {
+            cadence_day_of_month?: number | null;
+            cadence_days_of_week?: components["schemas"]["AutomationWeekday"][] | null;
+            /** @enum {string|null} */
+            cadence_frequency?: "daily" | "weekly" | "monthly" | "once" | null;
+            /** @description Set an empty string to clear the start date when the resulting cadence allows it. */
+            cadence_start_date?: string | null;
+            cadence_time_of_day?: string | null;
+            cadence_timezone?: string | null;
+            /** @enum {string|null} */
+            condition_operator?: "above" | "below" | null;
+            condition_threshold?: string | null;
+            /** @enum {string|null} */
+            denomination?: "usd" | "units" | null;
+            destination_symbol?: string | null;
+            enabled?: boolean | null;
+            name?: string | null;
+            /** @enum {string|null} */
+            settlement?: "standard" | "instant" | null;
+            skip_weekends?: boolean | null;
+            source_symbol?: string | null;
+            sweep_amount?: string | null;
+            /** @enum {string|null} */
+            sweep_type?: "fixed" | "percentage" | null;
+        };
+        /**
+         * Format: int32
+         * @enum {integer}
+         */
+        AutomationWeekday: 0 | 1 | 2 | 3 | 4 | 5 | 6;
         Balance: {
             /** @description The asset symbol, in the ledger's own casing (USDC, BTC, WTGXX, SOL:USDC). */
             asset: string;
@@ -1593,7 +1868,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" | "statement_generation.updated" | "transaction.created" | "transaction.updated" | "transfer_approval.created" | "transfer_approval.updated" | "withdrawal.created" | "withdrawal.updated";
+        EventTypeName: "automation_run.updated" | "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" | "transfer_approval.created" | "transfer_approval.updated" | "withdrawal.created" | "withdrawal.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;
@@ -3200,6 +3475,299 @@ export interface operations {
             };
         };
     };
+    "automation_runs.list": {
+        parameters: {
+            query?: {
+                limit?: number;
+                starting_after?: string;
+                ending_before?: string;
+                /** @description Return only this schedule's runs. Omit to read all business runs, including deleted schedules. */
+                automation?: string;
+            };
+            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"]["AutomationRunList"];
+                };
+            };
+            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"];
+                };
+            };
+        };
+    };
+    "automation_runs.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"]["AutomationRun"];
+                };
+            };
+            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"];
+                };
+            };
+        };
+    };
+    "automations.list": {
+        parameters: {
+            query?: {
+                limit?: number;
+                starting_after?: string;
+                ending_before?: string;
+            };
+            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"]["AutomationList"];
+                };
+            };
+            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"];
+                };
+            };
+        };
+    };
+    "automations.create": {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["Idempotency-Key"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["AutomationCreateInput"];
+            };
+        };
+        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"]["Automation"];
+                };
+            };
+            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"];
+                };
+            };
+        };
+    };
+    "automations.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"]["Automation"];
+                };
+            };
+            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"];
+                };
+            };
+        };
+    };
+    "automations.update": {
+        parameters: {
+            query?: never;
+            header: {
+                "Idempotency-Key": components["parameters"]["Idempotency-Key"];
+            };
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["AutomationUpdateInput"];
+            };
+        };
+        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"]["Automation"];
+                };
+            };
+            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"];
+                };
+            };
+        };
+    };
+    "automations.delete": {
+        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"]["AutomationDeleted"];
+                };
+            };
+            /** @description Accepted */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Automation"];
+                };
+            };
+            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"];
+                };
+            };
+        };
+    };
     "balance_history.snapshot": {
         parameters: {
             query?: {

package/package.json

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