@satrush/api 0.1.0

package/README.md

@@ -0,0 +1,97 @@
+# SatRush Api Client
+
+## Overview
+
+This package provides a TypeScript SDK for the SatRush public API. The SDK is generated from OpenAPI using
+`@hey-api/openapi-ts` and exposes a class-based client plus typed helpers.
+
+## Installation
+
+```bash
+pnpm add @satrush/api
+```
+
+## Usage
+
+```ts
+import {SatrushBackendSdk, createClient, unwrap} from "@satrush/api";
+
+const client = createClient({
+    baseUrl: "https://api.satrush.io/api",
+});
+const sdk = new SatrushBackendSdk({client});
+
+const board = await unwrap(
+    sdk.getBoard(),
+);
+```
+
+## How the SDK works
+
+- Generation source: `openapi.yaml` is the canonical spec.
+- Pre-processing: `scripts/camelizeOpenapi.mjs` produces `openapi.camel.yaml` (converts snake_case into cameCase).
+- Code generation: `@hey-api/openapi-ts` generates `src/generated/**`.
+- Post-processing: `scripts/postprocessOpenapi.mjs` patches the generated client to:
+    - snake_case request payloads/params
+    - camelCase response payloads
+    - apply response transforms before validators where needed
+    - apply custom SSE transforms (see below)
+
+## Case transforms and scalar transforms
+
+- Requests: payloads and query params are snake_cased in `src/transforms.ts`.
+- Responses: payloads are camelCased and then transformed for BigInt/Date via generated transformers.
+
+## SSE streams
+
+SSE response transforms are maintained manually in `src/sseTransforms.ts`. The upstream transformer plugin does not
+handle the SSE union schema, so any changes to SSE payloads must be reflected here.
+
+If you add or modify SSE event types in `openapi.yaml`:
+
+1. Update the SSE schemas and discriminator mapping.
+2. Regenerate the SDK (`pnpm openapi`).
+3. Update `src/sseTransforms.ts` to apply the correct transforms for the new event type.
+
+## Global error behavior
+
+To throw on non-2xx responses for all SDK calls, set `throwOnError: true` on the client instance
+and attach the built-in interceptor that wraps errors as `SatRushSdkError`:
+
+```ts
+import {SatRushBackendSdk, createClient, satrushSdkErrorInterceptor} from "@satrush/api";
+
+const client = createClient({
+    baseUrl: "https://api.satrush.io/api",
+    throwOnError: true,
+});
+client.interceptors.error.use(satrushSdkErrorInterceptor);
+
+const sdk = new SatRushBackendSdk({client});
+```
+
+`SatRushSdkError` includes the HTTP status and the original error payload in `cause`.
+
+If you already have a client, you can also enable it later:
+
+```ts
+import {client, satrushSdkErrorInterceptor} from "@satrush/api";
+
+client.setConfig({throwOnError: true});
+client.interceptors.error.use(satrushSdkErrorInterceptor);
+```
+
+When `responseStyle` is set to `"data"`, SDK calls return only the response payload
+(no `{ data, error, request, response }` wrapper). This is useful for simpler call sites:
+
+```ts
+import {SatRushBackendSdk, createClient} from "@satrush/api";
+
+const client = createClient({
+    baseUrl: "https://api.satrush.io/api",
+    responseStyle: "data",
+});
+
+const sdk = new SatrushBackendSdk({client});
+const board = await sdk.getBoard();
+```