@stridge/openapi 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# @stridge/openapi
+
+The **public** OpenAPI 3.1 specification for the Stridge API, published as an npm
+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.
+
+## Scope
+
+Currently the **UDA** surface only — 7 operations under the `UDA` tag:
+
+| 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` |
+
+> **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.
+
+Paths are relative to the server base URL, which carries the `/v1` prefix
+(`POST /uda` → `https://api.stridge.com/v1/uda`).
+
+## 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.
+
+### Clean name ↔ core definition map
+
+| Public schema | Core definition |
+| --- | --- |
+| `UDAAddress` | `internal_uda_application_http.UDAAddressResponse` |
+| `UDAAddressList` | `…ListUDAAddressResponse` |
+| `CreateUDAAddressRequest` | `…CreateUDAAddressRequest` |
+| `DestinationInput` / `Destination` | `…DestinationRequest` / `…DestinationDTO` |
+| `DepositAddress` / `DepositAsset` | `…DepositAddressDTO` / `…DepositAssetDTO` |
+| `RoutingRuleInput` / `RoutingRule` (+ Match/Destination) | `…RoutingRule*Request` / `…RoutingRule*Response` |
+| `Quote` / `QuoteSide` / `QuoteFees` / `QuoteFeeItem` / `QuoteRoute` | `…Quote*` |
+| `Settlement` (+ Deposit/Outbound/Fees/Route) | `…Settlement*DTO` / `…SettlementResponse` |
+| `SettlementList` / `SettlementsByReference` | `…ListSettlementsResponse` / `…SettlementsByReferenceResponse` |
+| `SupportedAssetsResponse` / `SupportedAssetChain` / `AssetInfo` / `NativeCurrency` | `…supportedassets.*` |
+| `Pagination` | `…PaginationResponse` |
+| `Error` | unified from `…shared_response.ErrorResponse` + `echo.HTTPError` |
+| `SuccessEnvelope` | `…shared_response.OkResponse` |
+
+## Develop
+
+```sh
+pnpm install
+pnpm run lint          # redocly lint
+pnpm run build         # → dist/openapi.json, dist/openapi.dereferenced.json, dist/types.d.ts
+pnpm exec tsc --noEmit # typecheck the generated types
+```
+
+## Consuming
+
+```ts
+import spec from "@stridge/openapi/dereferenced";   // fully flattened OAS 3.1 doc
+import type { paths, components } from "@stridge/openapi/types";
+```
+
+`apps/web` imports the **dereferenced** bundle so it never resolves `$ref`s at
+build time.
+
+## Releasing (Changesets)
+
+Releases are automated with [Changesets](https://github.com/changesets/changesets),
+mirroring [`stridge-foundation/kit`](https://github.com/stridge-foundation/kit).
+The `Release` workflow (`.github/workflows/release.yml`) runs the shared
+`technance-foundation/github-actions/release@main` action on every push to
+`main`, using the org-wide `NPM_PUBLISH_TOKEN` / `RELEASE_PUSH_TOKEN` secrets —
+so it works without per-repo secret setup.
+
+The flow:
+
+1. Add a changeset to your PR describing the spec change:
+
+   ```sh
+   pnpm changeset
+   ```
+
+2. When the PR merges to `main`, the release action opens a **"Version
+   Packages"** PR that applies the version bump and updates `CHANGELOG.md`.
+3. Merging that PR publishes `@stridge/openapi` to npm and tags the release.
+
+Nothing publishes until the Version Packages PR is merged, so a pending
+changeset on `main` is always safe.
+
+> **Access:** `access` in `.changeset/config.json` is `public`, matching kit.
+> Flip it to `restricted` if this package should be private (requires the
+> `@stridge` npm org token to permit restricted publishes).
+
+Local sanity checks (never run `pnpm release` from a laptop — CI owns it):
+
+```sh
+pnpm changeset status   # what's pending
+pnpm bump               # apply versions locally to preview; revert with git
+```