@lyku/lockstep-client-ts 1.0.0 → 1.3.1

package/LLMs.md

@@ -0,0 +1,85 @@
+# @lyku/lockstep-client-ts -- LLM Context
+
+## Purpose
+
+A code generation library that converts `ExternalApiModel` definitions (TsonSchema-based) into fully-typed, self-contained TypeScript HTTP client files. It bridges the gap between Lyku's custom schema system (`@lyku/lockstep-core`) and external third-party APIs.
+
+## Architecture
+
+```
+External API model definitions (e.g., @lyku/valhalla-models)
+  |
+  v
+lockstep-client-ts (this package)
+  -- reads ExternalApiSpec
+  -- calls tsonToType() from @lyku/lockstep-core to convert schemas to TS types
+  -- generates index.ts with types + client factory
+  |
+  v
+Generated client library (e.g., @lyku/valhalla-handles-ts)
+  -- consumed by route handlers at runtime
+```
+
+The generation is run as a build step, typically from a `build.ts` script like:
+
+```typescript
+import { generateTsClient } from '@lyku/lockstep-client-ts';
+import { valhallaModels } from '@lyku/valhalla-models';
+
+await generateTsClient({
+	models: valhallaModels,
+	name: 'Valhalla',
+	outputDir: '../../dist/libs/valhalla-handles-ts',
+});
+```
+
+## File Structure
+
+```
+src/
+  index.ts    -- entire implementation in a single file
+```
+
+The package is intentionally minimal: one file containing the generator function, validation helper, and all type definitions.
+
+## Key Patterns and Conventions
+
+- **Single-file codegen**: All logic lives in `src/index.ts`. The generator builds a large string template of TypeScript code and writes it to disk.
+- **Schema conversion**: Uses `tsonToType()` from `@lyku/lockstep-core` to convert TsonSchema definitions into TypeScript type strings at generation time.
+- **GET vs POST routing**: GET endpoints use query parameter serialization; POST/PUT/PATCH/DELETE endpoints use JSON request bodies.
+- **Path parameter interpolation**: Endpoints with `pathParams` get template literal paths (e.g., `/stops/${encodeURIComponent(stopId)}`).
+- **Parameter mapping**: The `paramMapping` option supports APIs that use non-standard param formats (e.g., Pelias uses dotted params like `focus.point.lat`).
+- **API key injection**: The `apiKeyParam` option automatically injects an API key into all requests as a query parameter.
+- **Custom methods**: For endpoints with complex signatures (e.g., overloaded path params), `customMethods` allows injecting raw TypeScript code.
+
+## Important Types
+
+- `ExternalApiModel` -- defines a single API endpoint (method, path, request/response schemas, path params)
+- `ExternalApiSpec` -- `Record<string, ExternalApiModel>`, the full API surface
+- `GenerateTsClientOptions` -- configuration for the generator
+
+## Generated Code Structure
+
+For a client named `Foo`, the output contains:
+
+1. Per-endpoint request/response types (`FooBarRequest`, `FooBarResponse`)
+2. A type map (`FooTypes`) for generic method dispatch
+3. Query string builder (with optional parameter mapping)
+4. `FooClientOptions` type for client configuration
+5. `FooError` class extending `Error`
+6. HTTP `request()` helper using `fetch` + `AbortController`
+7. `createFooClient()` factory returning typed methods
+8. `FooClient` type alias
+
+## Common Pitfalls
+
+- **The generated file should never be edited manually** -- it is overwritten on each build. The `DO NOT EDIT MANUALLY` comment is included in the output.
+- **Peer dependency**: `@lyku/lockstep-core` must be available; without it, `tsonToType()` calls will fail.
+- **Prettier failures are non-fatal**: If Prettier formatting fails, the unformatted output is written with a console warning.
+- **GET requests with body schemas**: The validator will flag GET endpoints that use `request` instead of `queryParams`, but the generator will still work (it checks both).
+
+## Monorepo Connections
+
+- **Peer dependency**: `@lyku/lockstep-core` (schema framework)
+- **Consumers**: `@lyku/valhalla-handles-ts`, `@lyku/pelias-handles-ts`, `@lyku/tomtom-handles-ts`, `@lyku/otp-handles-ts` -- each has a `build.ts` that calls `generateTsClient()`
+- **Not used for internal Lyku APIs** -- internal APIs use `@lyku/mapi-models` and the `handles` system instead

package/README.md

@@ -1,17 +1,15 @@
-# ts-codegen
+# @lyku/lockstep-client-ts
 
 Generate fully-typed TypeScript HTTP clients from TsonSchema-based API definitions.
 
 ## Overview
 
-`ts-codegen` takes a set of external API model definitions (request/response schemas, HTTP methods, path patterns) and produces a complete, self-contained TypeScript HTTP client file. It is used within the Lyku monorepo to generate typed clients for third-party APIs such as Valhalla (routing), Pelias (geocoding), TomTom (maps), and OTP (transit).
+This package takes a set of external API model definitions (request/response schemas, HTTP methods, path patterns) and produces a complete, self-contained TypeScript HTTP client file. It is used within the Lyku monorepo to generate typed clients for third-party APIs such as Valhalla (routing), Pelias (geocoding), TomTom (maps), and OTP (transit).
 
 ## Installation
 
 ```bash
-npm install ts-codegen
-# or as a workspace dependency
-pnpm add ts-codegen
+npm install @lyku/lockstep-client-ts
 ```
 
 Requires `@lyku/lockstep-core` as a peer dependency for schema-to-type conversion.
@@ -23,13 +21,13 @@ Requires `@lyku/lockstep-core` as a peer dependency for schema-to-type conversio
 Generates a TypeScript client file in the specified output directory.
 
 ```typescript
-import { generateTsClient } from 'ts-codegen';
-import { valhallaModels } from '@lyku/valhalla-models';
+import { generateTsClient } from '@lyku/lockstep-client-ts';
+import { valhallaModels } from '@myapp/api-models';
 
 await generateTsClient({
 	models: valhallaModels,
 	name: 'Valhalla',
-	outputDir: './dist/libs/valhalla-handles-ts',
+	outputDir: './dist/libs/valhalla-client',
 });
 ```
 
@@ -53,7 +51,7 @@ await generateTsClient({
 Validates an API specification and returns an array of error messages (empty if valid).
 
 ```typescript
-import { validateApiSpec } from 'ts-codegen';
+import { validateApiSpec } from '@lyku/lockstep-client-ts';
 
 const errors = validateApiSpec(myModels);
 if (errors.length > 0) {
@@ -90,6 +88,70 @@ For a client named `Valhalla`, the generated `index.ts` contains:
 
 The generated client uses `fetch` with `AbortController` for timeout support and handles JSON serialization/deserialization automatically.
 
+## Where it fits
+
+<!-- Generated from libs/lockstep-core/diagrams/pipeline.mmd — do not edit manually -->
+
+```mermaid
+graph TD
+    input-tables["Table Schemas<br/><small>PostgresRecordModel</small>"]
+    input-api["API Definitions<br/><small>TsonHandlerModel</small>"]
+
+    core-jsonmodels["generateJsonModels"]
+    core-dbtypes["generateDbTypes"]
+    core-apitypes["generateApiTypes"]
+    core-validators["buildValidator"]
+
+    handles-gen["generateHandles"]
+
+    client-gen["generateTsClient"]
+
+    pg-drift["detectDrift"]
+    pg-migrate["generateMigration"]
+
+    output-jsonschemas["JSON Schemas +<br/>TypeScript Types"]
+    output-kysely["Kysely Database<br/>Interface"]
+    output-reqres["Request / Response<br/>TypeScript Types"]
+    output-handlers["Handler Factories<br/>+ Validators"]
+    output-client["Type-safe<br/>HTTP Client"]
+    output-sql["SQL Migrations"]
+
+    input-tables --> core-jsonmodels
+    core-jsonmodels --> output-jsonschemas
+    output-jsonschemas --> core-dbtypes
+    core-dbtypes --> output-kysely
+
+    input-api --> core-apitypes
+    core-apitypes --> output-reqres
+    input-api --> core-validators
+
+    output-reqres --> handles-gen
+    input-api --> handles-gen
+    core-validators -.-> handles-gen
+    handles-gen --> output-handlers
+
+    output-reqres --> client-gen
+    input-api --> client-gen
+    client-gen --> output-client
+
+    input-tables --> pg-drift
+    pg-drift --> pg-migrate
+    pg-migrate --> output-sql
+
+    classDef highlight fill:#4f46e5,stroke:#3730a3,color:#fff,stroke-width:2px
+    classDef dimmed fill:#f1f5f9,stroke:#cbd5e1,color:#94a3b8,stroke-width:1px
+    classDef inputNode fill:#fef3c7,stroke:#f59e0b,color:#92400e,stroke-width:1px
+    classDef outputNode fill:#d1fae5,stroke:#10b981,color:#065f46,stroke-width:1px
+    classDef ownedOutput fill:#a5b4fc,stroke:#4f46e5,color:#1e1b4b,stroke-width:2px
+    classDef ownedInput fill:#fde68a,stroke:#4f46e5,color:#1e1b4b,stroke-width:2px
+    class client-gen highlight
+    class core-jsonmodels,core-dbtypes,core-apitypes,core-validators,handles-gen,pg-drift,pg-migrate dimmed
+    class input-tables inputNode
+    class output-jsonschemas,output-kysely,output-reqres,output-handlers,output-sql outputNode
+    class input-api ownedInput
+    class output-client ownedOutput
+```
+
 ## Dependencies
 
 - `@lyku/lockstep-core` (peer) -- schema-to-TypeScript-type conversion via `tsonToType`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lyku/lockstep-client-ts",
-	"version": "1.0.0",
+	"version": "1.3.1",
 	"description": "Generate fully-typed TypeScript HTTP clients from TsonSchema-based API definitions",
 	"type": "module",
 	"main": "./index.js",
@@ -15,7 +15,9 @@
 	"files": [
 		"index.js",
 		"index.cjs",
-		"index.d.ts"
+		"index.d.ts",
+		"README.md",
+		"LLMs.md"
 	],
 	"keywords": [
 		"typescript",
@@ -33,6 +35,7 @@
 		"prettier": "^3.0.0"
 	},
 	"devDependencies": {
+		"@lyku/lockstep-core": "1.3.1",
 		"typescript": "^5.0.0"
 	},
 	"module": "./src/index.js"