@stridge/openapi 0.3.0 → 0.5.0

package/README.md

@@ -5,28 +5,67 @@ package (spec JSON + generated TypeScript types). It is the single source the
 public API reference site (`reference.stridge.com`) consumes.
 
 This repo is hand-authored and curated. It is **not** generated from core — it
-deliberately re-expresses a small, public subset of the internal API with clean
-names, public-facing copy, and realistic examples. Core's internal Swagger 2.0
-document (`../core/docs/swagger.yaml`) is the source of truth for field shapes —
-keep this spec in sync by hand when core's UDA endpoints change.
+deliberately re-expresses a public subset of the internal `/v1` API with clean
+names, public-facing copy, and realistic examples. Core's handlers and response
+structs (and its internal Swagger 2.0 document, `../core/docs/swagger.yaml`) are
+the source of truth for field shapes — keep this spec in sync by hand when
+core's public `/v1` endpoints change.
 
-## Scope
-
-Currently the **UDA** surface only — 7 operations under the `UDA` tag:
+> **Stop-gap.** This hand-written spec describes what production serves on
+> `/v1` today. It will be replaced by a spec generated from core's `/v2`
+> contract; until then, edit it by hand and verify every change against the
+> core release that production runs.
 
-| Method · Path | Operation | Auth |
-| --- | --- | --- |
-| `GET /uda` | `list-uda-addresses` | `X-API-Key` |
-| `POST /uda` | `create-uda-address` | `X-API-Key` |
-| `GET /uda/quote` | `get-quote` | public |
-| `GET /uda/supported-assets` | `list-supported-assets` | public |
-| `GET /uda/{id}/settlements` | `list-settlements-for-uda` | `X-API-Key` |
-| `GET /uda/settlements/{id}` | `get-settlement` | `X-API-Key` |
-| `GET /uda/settlements/by-reference` | `list-settlements-by-reference` | `X-API-Key` |
+## Scope
 
-> **Onchain Balance is intentionally excluded for now.** `GET /v1/balance/onchain/{wallet_address}`
-> authenticates with `X-Gateway-Key` (the gateway-scoped key), not `X-API-Key`.
-> It will be added once its public authentication is reconciled.
+30 operations in 6 tags, plus one webhook (`webhook-event`, the signed envelope
+Stridge POSTs to your endpoints):
+
+| Method · Path | Operation | Tag | Auth |
+| --- | --- | --- | --- |
+| `GET /uda` | `list-uda-addresses` | UDA | `X-API-Key` |
+| `POST /uda` | `create-uda-address` | UDA | `X-API-Key` |
+| `GET /uda/quote` | `get-quote` | UDA | public |
+| `GET /uda/supported-assets` | `list-supported-assets` | UDA | public |
+| `GET /uda/{id}/settlements` | `list-settlements-for-uda` | UDA | `X-API-Key` |
+| `GET /uda/settlements/{id}` | `get-settlement` | UDA | `X-API-Key` |
+| `GET /uda/settlements/by-reference` | `list-settlements-by-reference` | UDA | `X-API-Key` |
+| `GET /vault` | `list-vaults` | Payout | `X-API-Key` |
+| `GET /vault/{vault_id}/addresses` | `list-vault-addresses` | Payout | `X-API-Key` |
+| `GET /vault/{vault_id}/addresses/{network}` | `get-vault-address-by-network` | Payout | `X-API-Key` |
+| `GET /vault/{vault_id}/balances` | `get-vault-balances` | Payout | `X-API-Key` |
+| `GET /vault/{vault_id}/total` | `get-vault-total` | Payout | `X-API-Key` |
+| `GET /transfer/payout` | `list-payouts` | Payout | `X-API-Key` |
+| `POST /transfer/payout` | `create-payout` | Payout | `X-API-Key` |
+| `GET /transfer/payout/pending` | `list-pending-payouts` | Payout | `X-API-Key` |
+| `GET /transfer/payout/{id}` | `get-payout` | Payout | `X-API-Key` |
+| `POST /transfer/payout/{id}/reject` | `reject-payout` | Payout | `X-API-Key` |
+| `GET /gas-stations/address/{address}` | `get-gas-station-by-address` | Gas Stations | `X-API-Key` |
+| `GET /gas-stations/wallet/{wallet_id}` | `get-gas-station-by-wallet` | Gas Stations | `X-API-Key` |
+| `GET /gas-stations/wallets` | `list-gas-station-wallets` | Gas Stations | `X-API-Key` |
+| `GET /routing-policies` | `list-routing-policies` | Routing Policies | `X-API-Key` |
+| `GET /routing-policies/{id}` | `get-routing-policy` | Routing Policies | `X-API-Key` |
+| `GET /test_helpers/options` | `get-test-helper-options` | Test Helpers | sandbox key |
+| `POST /test_helpers/uda/deposits` | `simulate-uda-deposit` | Test Helpers | sandbox key |
+| `POST /test_helpers/vault/deposits` | `simulate-vault-deposit` | Test Helpers | sandbox key |
+| `POST /test_helpers/payouts` | `simulate-payout` | Test Helpers | sandbox key |
+| `POST /test_helpers/payouts/{payout_id}/release` | `release-simulated-payout` | Test Helpers | sandbox key |
+| `POST /test_helpers/payouts/{payout_id}/fail` | `fail-simulated-payout` | Test Helpers | sandbox key |
+| `GET /test_helpers/simulations` | `list-simulations` | Test Helpers | sandbox key |
+| `GET /test_helpers/simulations/{simulation_id}` | `get-simulation` | Test Helpers | sandbox key |
+
+The `Test Helpers` operations are sandbox only (`x-sandbox-only: true`): a live
+key is answered `404 not a sandbox environment`.
+
+Live and sandbox keys share one server, `https://api.stridge.com/v1`; the key's
+prefix (`sk_live_`, `sk_sbx_`, or none for older live keys) decides the
+environment. `api.stridge.dev` is Stridge's staging cluster, not a customer
+sandbox, and is not in the spec.
+
+> **Excluded on purpose.** The gateway (`X-Gateway-Key`: `/gateway/*`, the
+> onramp, and `GET /balance/onchain/{wallet_address}`) is documented in the
+> gateway guides, not here; it serves live keys only. Direct and smart routing
+> are switched off in production and are not described.
 
 Paths are relative to the server base URL, which carries the `/v1` prefix
 (`POST /uda` → `https://api.stridge.com/v1/uda`).
@@ -34,9 +73,8 @@ Paths are relative to the server base URL, which carries the `/v1` prefix
 ## Authoring note
 
 The spec is authored as a **single file** (`spec/openapi.yaml`) rather than the
-split-file layout originally sketched in the build plan. At 7 operations this is
-simpler and avoids cross-file `$ref` resolution pitfalls; Redocly bundles and
-dereferences it identically. Split by domain later if the surface grows.
+split-file layout originally sketched in the build plan. It avoids cross-file
+`$ref` resolution pitfalls; Redocly bundles and dereferences it identically.
 
 ### Clean name ↔ core definition map
 
@@ -55,6 +93,13 @@ dereferences it identically. Split by domain later if the surface grows.
 | `Pagination` | `…PaginationResponse` |
 | `Error` | unified from `…shared_response.ErrorResponse` + `echo.HTTPError` |
 | `SuccessEnvelope` | `…shared_response.OkResponse` |
+| `PagePagination` | `lib/filter.PaginationInfo` |
+| `Livemode` (the `livemode` field) | added by `internal/shared/response/livemode.go` to every object a keyed response renders |
+| `RoutingPolicy` | `internal/routing_policy/application/http.PolicyResponse` |
+| `Simulation` / `SimulationCause` / `SimulationChain` | `internal/sandbox/application/http.SimulationResponse` / `internal/sandbox/domain.Cause` / `.ChainRef` |
+| `SimulateUDADepositRequest` / `SimulateVaultDepositRequest` / `SimulatePayoutRequest` | `internal/sandbox/domain.UDADepositRequest` / `.VaultDepositRequest` / `.PayoutRequest` |
+| `TestHelperOptions` (+ UDA/Vault/Network/Preset/Timing) | `internal/sandbox/domain.Options` (+ `Option*`) |
+| `WebhookEnvelope` | `internal/webhook/domain.WebhookEnvelope` |
 
 ## Develop
 
@@ -62,6 +107,7 @@ dereferences it identically. Split by domain later if the surface grows.
 pnpm install
 pnpm run lint          # redocly lint
 pnpm run build         # → dist/openapi.json, dist/openapi.dereferenced.json, dist/types.d.ts
+pnpm test              # contract checks on dist/openapi.json (node:test)
 pnpm exec tsc --noEmit # typecheck the generated types
 ```