ts-procedures 6.0.2 → 6.1.0

package/src/codegen/bin/cli.ts

@@ -22,6 +22,9 @@ export interface CodegenConfig {
   selfContained?: boolean
   serviceName?: string
   cleanOutDir?: boolean
+  target?: 'ts' | 'kotlin'
+  kotlin?: { package: string; serializer?: 'kotlinx' | 'none' }
+  unsupportedUnions?: 'throw' | 'fallback'
 }
 
 export interface ParsedArgs {
@@ -37,6 +40,9 @@ export interface ParsedArgs {
   selfContained: boolean
   serviceName?: string
   cleanOutDir: boolean
+  target?: 'ts' | 'kotlin'
+  kotlin?: { package: string; serializer?: 'kotlinx' | 'none' }
+  unsupportedUnions?: 'throw' | 'fallback'
 }
 
 // ---------------------------------------------------------------------------
@@ -88,6 +94,10 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
   let selfContained = config?.selfContained ?? true
   let serviceName: string | undefined = config?.serviceName
   let cleanOutDir = config?.cleanOutDir ?? false
+  let target: 'ts' | 'kotlin' | undefined = config?.target
+  let kotlinPackage: string | undefined = config?.kotlin?.package
+  let kotlinSerializer: 'kotlinx' | 'none' | undefined = config?.kotlin?.serializer
+  let unsupportedUnions: 'throw' | 'fallback' | undefined = config?.unsupportedUnions
   let configPath: string | undefined
 
   for (let i = 0; i < argv.length; i++) {
@@ -137,6 +147,29 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
       cleanOutDir = true
     } else if (arg === '--no-clean-out-dir') {
       cleanOutDir = false
+    } else if (arg === '--target') {
+      const val = argv[++i]
+      if (val === 'ts' || val === 'kotlin') {
+        target = val
+      } else {
+        throw new Error(`Invalid --target value: ${val ?? '(missing)'} (expected 'ts' or 'kotlin')`)
+      }
+    } else if (arg === '--kotlin-package') {
+      kotlinPackage = argv[++i]
+    } else if (arg === '--kotlin-serializer') {
+      const val = argv[++i]
+      if (val === 'kotlinx' || val === 'none') {
+        kotlinSerializer = val
+      } else {
+        throw new Error(`Invalid --kotlin-serializer value: ${val ?? '(missing)'} (expected 'kotlinx' or 'none')`)
+      }
+    } else if (arg === '--unsupported-unions') {
+      const val = argv[++i]
+      if (val === 'throw' || val === 'fallback') {
+        unsupportedUnions = val
+      } else {
+        throw new Error(`Invalid --unsupported-unions value: ${val ?? '(missing)'} (expected 'throw' or 'fallback')`)
+      }
     } else if (arg === '--config') {
       configPath = argv[++i]
     }
@@ -153,6 +186,10 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
     throw new Error('Missing required input source: provide --url <url> or --file <path>')
   }
 
+  if (target === 'kotlin' && (kotlinPackage === undefined || kotlinPackage === '')) {
+    throw new Error('Missing required argument: --kotlin-package <pkg> (required when --target kotlin)')
+  }
+
   return {
     url,
     file,
@@ -166,6 +203,16 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
     selfContained,
     ...(serviceName !== undefined ? { serviceName } : {}),
     cleanOutDir,
+    ...(target !== undefined ? { target } : {}),
+    ...(kotlinPackage !== undefined
+      ? {
+          kotlin: {
+            package: kotlinPackage,
+            ...(kotlinSerializer !== undefined ? { serializer: kotlinSerializer } : {}),
+          },
+        }
+      : {}),
+    ...(unsupportedUnions !== undefined ? { unsupportedUnions } : {}),
   }
 }
 
@@ -201,6 +248,18 @@ async function runWithWatch(parsed: ParsedArgs): Promise<void> {
     cleanOutDir: parsed.cleanOutDir,
   }
 
+  // Resolve the kotlin emitter once at watch start; it's stateless and reused per tick.
+  const kotlinWiring =
+    parsed.target === 'kotlin'
+      ? {
+          target: 'kotlin' as const,
+          kotlinPackage: parsed.kotlin!.package,
+          kotlinEmitter: await (
+            await import('../targets/kotlin/ajsc-adapter.js')
+          ).resolveProductionKotlinEmitter(),
+        }
+      : {}
+
   let lastHash: string | undefined
 
   const run = async (): Promise<void> => {
@@ -226,6 +285,9 @@ async function runWithWatch(parsed: ParsedArgs): Promise<void> {
         selfContained: parsed.selfContained,
         serviceName: parsed.serviceName,
         cleanOutDir: parsed.cleanOutDir,
+        ...(parsed.kotlin?.serializer !== undefined ? { kotlinSerializer: parsed.kotlin.serializer } : {}),
+        ...(parsed.unsupportedUnions !== undefined ? { unsupportedUnions: parsed.unsupportedUnions } : {}),
+        ...kotlinWiring,
       })
       console.log(`[ts-procedures-codegen] Generated client files → ${parsed.outDir}`)
     } catch (err) {
@@ -243,6 +305,33 @@ async function runWithWatch(parsed: ParsedArgs): Promise<void> {
 // Main
 // ---------------------------------------------------------------------------
 
+const KOTLIN_SETUP_GUIDE_URL =
+  'https://bitbucket.org/thermsio/ts-procedures/src/master/docs/codegen-kotlin.md'
+
+export function printPostRunHints(parsed: { target?: 'ts' | 'kotlin' }): void {
+  if (parsed.target === 'kotlin') {
+    console.log(`[ts-procedures-codegen] Kotlin setup guide: ${KOTLIN_SETUP_GUIDE_URL}`)
+  }
+}
+
+/**
+ * Warns about flags that are currently no-ops for the Kotlin target.
+ * Currently: `--unsupported-unions` is a no-op because ajsc v7.2's Kotlin
+ * emitter silently emits an empty data class for untagged oneOf regardless
+ * of the flag (see docs/codegen-kotlin.md#untagged-unions).
+ */
+export function warnIfKotlinNoOpFlags(parsed: {
+  target?: 'ts' | 'kotlin'
+  unsupportedUnions?: 'throw' | 'fallback'
+}): void {
+  if (parsed.target === 'kotlin' && parsed.unsupportedUnions !== undefined) {
+    console.warn(
+      '[ts-procedures-codegen] Note: --unsupported-unions is currently a no-op for --target kotlin ' +
+      '(ajsc v7.2 emits an empty data class regardless). See docs/codegen-kotlin.md#untagged-unions.',
+    )
+  }
+}
+
 async function main(): Promise<void> {
   const argv = process.argv.slice(2)
   const configPath = extractConfigPath(argv)
@@ -251,6 +340,7 @@ async function main(): Promise<void> {
     console.log(`[ts-procedures-codegen] Loaded config from ${configPath ?? DEFAULT_CONFIG_NAME}`)
   }
   const parsed = parseArgs(argv, config)
+  warnIfKotlinNoOpFlags(parsed)
 
   const source = parsed.url ?? parsed.file!
   console.log(`[ts-procedures-codegen] Reading docs from ${source}...`)
@@ -258,6 +348,15 @@ async function main(): Promise<void> {
   if (parsed.watch) {
     await runWithWatch(parsed)
   } else {
+    const kotlinWiring =
+      parsed.target === 'kotlin'
+        ? {
+            target: 'kotlin' as const,
+            kotlinPackage: parsed.kotlin!.package,
+            kotlinEmitter: await (await import('../targets/kotlin/ajsc-adapter.js')).resolveProductionKotlinEmitter(),
+          }
+        : {}
+
     const result = await generateClient({
       url: parsed.url,
       file: parsed.file,
@@ -269,11 +368,15 @@ async function main(): Promise<void> {
       selfContained: parsed.selfContained,
       serviceName: parsed.serviceName,
       cleanOutDir: parsed.cleanOutDir,
+      ...(parsed.kotlin?.serializer !== undefined ? { kotlinSerializer: parsed.kotlin.serializer } : {}),
+      ...(parsed.unsupportedUnions !== undefined ? { unsupportedUnions: parsed.unsupportedUnions } : {}),
+      ...kotlinWiring,
     })
     if (parsed.dryRun) {
       console.log(`[ts-procedures-codegen] Dry run complete — ${result.length} files would be generated`)
     } else {
       console.log(`[ts-procedures-codegen] Generated ${result.length} files → ${parsed.outDir}`)
+      printPostRunHints(parsed)
     }
   }
 }

package/src/codegen/index.ts

@@ -1,6 +1,7 @@
 import { resolveEnvelope, type ResolveInput } from './resolve-envelope.js'
 import { runPipeline, type GeneratedFile } from './pipeline.js'
 import type { AjscOptions } from './emit-types.js'
+import type { KotlinEmitter } from './targets/kotlin/ajsc-adapter.js'
 
 export interface GenerateClientOptions extends ResolveInput {
   outDir: string
@@ -11,6 +12,12 @@ export interface GenerateClientOptions extends ResolveInput {
   selfContained?: boolean
   serviceName?: string
   cleanOutDir?: boolean
+  target?: 'ts' | 'kotlin'
+  kotlinPackage?: string
+  kotlinSerializer?: 'kotlinx' | 'none'
+  unsupportedUnions?: 'throw' | 'fallback'
+  /** Injected for tests; production wiring resolves a real ajsc emitter. */
+  kotlinEmitter?: KotlinEmitter
 }
 
 export async function generateClient(options: GenerateClientOptions): Promise<GeneratedFile[]> {
@@ -25,8 +32,28 @@ export async function generateClient(options: GenerateClientOptions): Promise<Ge
     selfContained: options.selfContained,
     serviceName: options.serviceName,
     cleanOutDir: options.cleanOutDir,
+    target: options.target,
+    kotlinPackage: options.kotlinPackage,
+    kotlinSerializer: options.kotlinSerializer,
+    unsupportedUnions: options.unsupportedUnions,
+    kotlinEmitter: options.kotlinEmitter,
   })
 }
 
 export type { AjscOptions } from './emit-types.js'
 export type { ResolveInput } from './resolve-envelope.js'
+
+/**
+ * @internal Subject to change with ajsc minor versions. Use for test injection
+ *   only; consumer code should not depend on this shape.
+ */
+export type { KotlinEmitter } from './targets/kotlin/ajsc-adapter.js'
+
+/**
+ * @internal Mirrors ajsc's `KotlinConverterOpts` and may shift with ajsc
+ *   minor versions. Use for test injection only.
+ */
+export type { KotlinEmitOptions } from './targets/kotlin/ajsc-adapter.js'
+
+/** Result shape produced by `KotlinEmitter.emit`; stable, useful for stub builders in tests. */
+export type { KotlinEmitResult } from './targets/kotlin/ajsc-adapter.js'

package/src/codegen/pipeline.test.ts

@@ -1,6 +1,8 @@
 import { describe, it, expect, afterEach, vi } from 'vitest'
 import { generateClient } from './index.js'
 import { runPipeline } from './pipeline.js'
+import { createStubKotlinEmitter } from './targets/kotlin/ajsc-adapter.js'
+import type { KotlinEmitOptions } from './targets/kotlin/ajsc-adapter.js'
 import { mkdirSync, rmSync, readFileSync, existsSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
@@ -359,3 +361,176 @@ describe('generateClient pipeline', () => {
     )
   })
 })
+
+describe('runPipeline (kotlin target)', () => {
+  it('emits only .kt files when target is "kotlin"', async () => {
+    const envelope = {
+      basePath: '/api',
+      headers: [],
+      version: '1' as const,
+      routes: [
+        {
+          kind: 'api',
+          name: 'GetUser',
+          scope: 'users',
+          method: 'GET',
+          fullPath: '/users/:id',
+          schema: { input: { pathParams: { type: 'object' } }, returnType: { type: 'object' } },
+          errors: [],
+        },
+      ],
+      errors: [],
+    } as any
+
+    const files = await runPipeline({
+      envelope,
+      outDir: 'out',
+      dryRun: true,
+      target: 'kotlin',
+      kotlinPackage: 'com.example.api',
+      kotlinEmitter: createStubKotlinEmitter({
+        PathParams: {
+          code: '@Serializable data class PathParams(val id: String)',
+          rootTypeName: 'PathParams',
+          extractedTypeNames: [],
+          imports: ['kotlinx.serialization.Serializable'],
+        },
+        Response: {
+          code: '@Serializable data class Response(val id: String)',
+          rootTypeName: 'Response',
+          extractedTypeNames: [],
+          imports: ['kotlinx.serialization.Serializable'],
+        },
+      }),
+    })
+
+    expect(files.map((f) => f.path)).toEqual([join('out', 'Users.kt')])
+    expect(files[0]!.code).toContain('object Users {')
+  })
+
+  it('does not emit _errors.ts, index.ts, or client runtime files when target is "kotlin"', async () => {
+    const envelope = { basePath: '/api', headers: [], version: '1', routes: [], errors: [] } as any
+    const files = await runPipeline({
+      envelope,
+      outDir: 'out',
+      dryRun: true,
+      target: 'kotlin',
+      kotlinPackage: 'p',
+      kotlinEmitter: createStubKotlinEmitter({}),
+    })
+    expect(files.find((f) => f.path.endsWith('_errors.ts'))).toBeUndefined()
+    expect(files.find((f) => f.path.endsWith('index.ts'))).toBeUndefined()
+    expect(files.find((f) => f.path.endsWith('_client.ts'))).toBeUndefined()
+    expect(files.find((f) => f.path.endsWith('_types.ts'))).toBeUndefined()
+  })
+
+  it('threads kotlinSerializer and unsupportedUnions to the emitter', async () => {
+    const calls: KotlinEmitOptions[] = []
+    const captureEmitter = {
+      emit(_s: unknown, opts: KotlinEmitOptions) {
+        calls.push(opts)
+        return { code: 'data class Response(val id: String)', rootTypeName: opts.rootTypeName, extractedTypeNames: [], imports: [] }
+      },
+    }
+
+    const envelope = {
+      basePath: '/api', headers: [], version: '1' as const, errors: [],
+      routes: [
+        {
+          kind: 'api', name: 'GetUser', scope: 'users', method: 'GET', fullPath: '/users/:id',
+          schema: { input: { pathParams: { type: 'object' } }, returnType: { type: 'object' } },
+          errors: [],
+        },
+      ],
+    } as any
+
+    await runPipeline({
+      envelope, outDir: 'out', dryRun: true,
+      target: 'kotlin', kotlinPackage: 'p',
+      kotlinSerializer: 'none',
+      unsupportedUnions: 'fallback',
+      kotlinEmitter: captureEmitter,
+    })
+
+    expect(calls.length).toBeGreaterThan(0)
+    for (const c of calls) {
+      expect(c.serializer).toBe('none')
+      expect(c.unsupportedUnions).toBe('fallback')
+      expect(c.inlineTypes).toBe(true)
+    }
+  })
+
+  it('logs a single summary line for skipped stream routes', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    try {
+      const envelope = {
+        basePath: '/api', headers: [], version: '1' as const, errors: [],
+        routes: [
+          { kind: 'stream', name: 'WatchA', scope: 's', method: 'GET', path: '/a', schema: {}, errors: [] },
+          { kind: 'stream', name: 'WatchB', scope: 's', method: 'GET', path: '/b', schema: {}, errors: [] },
+          { kind: 'api', name: 'GetThing', scope: 's', method: 'GET', fullPath: '/c', schema: { returnType: { type: 'object' } }, errors: [] },
+        ],
+      } as any
+      await runPipeline({
+        envelope, outDir: 'out', dryRun: true,
+        target: 'kotlin', kotlinPackage: 'p',
+        kotlinEmitter: createStubKotlinEmitter({
+          Response: { code: 'data class Response(val ok: Boolean)', rootTypeName: 'Response', extractedTypeNames: [], imports: [] },
+        }),
+      })
+      const summary = logSpy.mock.calls.find((c) => String(c[0]).includes('Skipped'))
+      expect(summary).toBeDefined()
+      expect(String(summary![0])).toContain('Skipped 2 stream routes')
+      expect(String(summary![0])).toContain('WatchA')
+      expect(String(summary![0])).toContain('WatchB')
+    } finally {
+      logSpy.mockRestore()
+    }
+  })
+
+  it('does not log a summary when there are no skipped streams', async () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    try {
+      const envelope = {
+        basePath: '/api', headers: [], version: '1' as const, errors: [],
+        routes: [{ kind: 'api', name: 'X', scope: 's', method: 'GET', fullPath: '/x', schema: { returnType: { type: 'object' } }, errors: [] }],
+      } as any
+      await runPipeline({
+        envelope, outDir: 'out', dryRun: true,
+        target: 'kotlin', kotlinPackage: 'p',
+        kotlinEmitter: createStubKotlinEmitter({ Response: { code: 'data class Response(val x: Int)', rootTypeName: 'Response', extractedTypeNames: [], imports: [] } }),
+      })
+      const summary = logSpy.mock.calls.find((c) => String(c[0]).includes('Skipped'))
+      expect(summary).toBeUndefined()
+    } finally {
+      logSpy.mockRestore()
+    }
+  })
+
+  it('forwards ajsc passthroughs (arrayItemNaming/depluralize/uncountableWords) to the kotlin emitter', async () => {
+    const calls: KotlinEmitOptions[] = []
+    const captureEmitter = {
+      emit(_s: unknown, opts: KotlinEmitOptions) {
+        calls.push(opts)
+        return { code: 'data class Response(val id: String)', rootTypeName: opts.rootTypeName, extractedTypeNames: [], imports: [] }
+      },
+    }
+
+    const envelope = {
+      basePath: '/api', headers: [], version: '1' as const, errors: [],
+      routes: [{ kind: 'api', name: 'GetUser', scope: 'users', method: 'GET', fullPath: '/u', schema: { returnType: { type: 'object' } }, errors: [] }],
+    } as any
+
+    await runPipeline({
+      envelope, outDir: 'out', dryRun: true,
+      target: 'kotlin', kotlinPackage: 'p',
+      ajsc: { arrayItemNaming: 'Item', depluralize: true, uncountableWords: ['data'] },
+      kotlinEmitter: captureEmitter,
+    })
+
+    expect(calls.length).toBe(1)
+    expect(calls[0]!.arrayItemNaming).toBe('Item')
+    expect(calls[0]!.depluralize).toBe(true)
+    expect(calls[0]!.uncountableWords).toEqual(['data'])
+  })
+})

package/src/codegen/pipeline.ts

@@ -10,6 +10,9 @@ import { emitErrorsFile } from './emit-errors.js'
 import { emitClientTypesFile } from './emit-client-types.js'
 import { emitClientRuntimeFile } from './emit-client-runtime.js'
 import { validateServiceName } from './naming.js'
+import type { KotlinEmitter } from './targets/kotlin/ajsc-adapter.js'
+import { emitKotlinScope } from './targets/kotlin/emit-scope-kotlin.js'
+import { pickDefined } from './targets/kotlin/format-kotlin.js'
 
 export interface PipelineOptions {
   envelope: DocEnvelope
@@ -21,6 +24,12 @@ export interface PipelineOptions {
   selfContained?: boolean
   serviceName?: string
   cleanOutDir?: boolean
+  target?: 'ts' | 'kotlin'
+  kotlinPackage?: string
+  kotlinSerializer?: 'kotlinx' | 'none'
+  unsupportedUnions?: 'throw' | 'fallback'
+  /** Injected for tests; production wiring resolves a real ajsc emitter. */
+  kotlinEmitter?: KotlinEmitter
 }
 
 export interface GeneratedFile {
@@ -43,6 +52,76 @@ export async function runPipeline(options: PipelineOptions): Promise<GeneratedFi
   const groups = groupRoutesByScope(envelope.routes)
   const groupArray = Array.from(groups.values())
 
+  if (options.target === 'kotlin') {
+    if (options.kotlinPackage == null) {
+      throw new Error('[ts-procedures-codegen] target=kotlin requires kotlinPackage')
+    }
+    if (options.kotlinEmitter == null) {
+      throw new Error(
+        '[ts-procedures-codegen] target=kotlin requires a kotlinEmitter (CLI resolves via resolveProductionKotlinEmitter)'
+      )
+    }
+
+    // Route errors are taxonomy keys (string[]); look up actual schemas from the
+    // envelope's top-level errors array. Mirrors the existing TS scope emitter.
+    const errorSchemas = new Map<string, unknown>()
+    for (const e of envelope.errors) {
+      if (e.schema != null) errorSchemas.set(e.name, e.schema)
+    }
+
+    // Spec §"CLI flags" — `--array-item-naming`, `--depluralize`, `--uncountable-words`
+    // also apply to the Kotlin target. The CLI parks them on `options.ajsc` (a TS-target
+    // structure historically); copy the Kotlin-relevant subset onto the scope opts here.
+    const ajscPassthrough = options.ajsc ?? {}
+
+    const AJSC_PASSTHROUGH_KEYS = ['arrayItemNaming', 'depluralize', 'uncountableWords'] as const
+
+    const kotlinFiles: GeneratedFile[] = []
+    const allSkipped: string[] = []
+    for (const group of groupArray) {
+      const emitted = emitKotlinScope(
+        group,
+        {
+          kotlinPackage: options.kotlinPackage,
+          sourceHash: hash,
+          ...(options.kotlinSerializer !== undefined ? { serializer: options.kotlinSerializer } : {}),
+          ...(options.unsupportedUnions !== undefined ? { unsupportedUnions: options.unsupportedUnions } : {}),
+          ...pickDefined(ajscPassthrough, AJSC_PASSTHROUGH_KEYS),
+        },
+        options.kotlinEmitter,
+        errorSchemas,
+      )
+      kotlinFiles.push({ path: join(outDir, emitted.filename), code: emitted.code })
+      allSkipped.push(...emitted.skippedStreams)
+    }
+
+    if (allSkipped.length > 0) {
+      console.log(
+        `[ts-procedures-codegen] Skipped ${allSkipped.length} stream route${allSkipped.length === 1 ? '' : 's'} (kotlin target): ${allSkipped.join(', ')}`,
+      )
+    }
+
+    if (dryRun) {
+      if (cleanOutDir) {
+        console.log(`[dry-run] Would clean outDir: ${outDir}`)
+      }
+      for (const f of kotlinFiles) {
+        const bytes = Buffer.byteLength(f.code, 'utf-8')
+        console.log(`[dry-run] Would write: ${f.path} (${bytes} bytes)`)
+      }
+    } else {
+      if (cleanOutDir) {
+        await rm(outDir, { recursive: true, force: true })
+      }
+      await mkdir(outDir, { recursive: true })
+      for (const f of kotlinFiles) {
+        await writeFile(f.path, f.code, 'utf-8')
+      }
+    }
+
+    return kotlinFiles
+  }
+
   // Error keys that will be emitted in `_errors.ts` — only those with a schema.
   // Scope emit uses this to filter `route.errors` so generated code never
   // references an undefined error type.

package/src/codegen/targets/kotlin/__fixtures__/users-envelope.json

@@ -0,0 +1,144 @@
+{
+  "version": "1",
+  "basePath": "/api",
+  "headers": [],
+  "routes": [
+    {
+      "kind": "api",
+      "name": "GetUser",
+      "scope": "users",
+      "method": "GET",
+      "fullPath": "/users/:id",
+      "schema": {
+        "input": {
+          "pathParams": {
+            "type": "object",
+            "properties": { "id": { "type": "string" } },
+            "required": ["id"]
+          }
+        },
+        "returnType": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "string" },
+            "name": { "type": "string" },
+            "created-at": { "type": "string", "format": "date-time" },
+            "address": {
+              "type": "object",
+              "properties": {
+                "street": { "type": "string" },
+                "city": { "type": "string" }
+              },
+              "required": ["street", "city"]
+            }
+          },
+          "required": ["id", "name", "created-at", "address"]
+        }
+      },
+      "errors": ["NotFound"]
+    },
+    {
+      "kind": "api",
+      "name": "CreateUser",
+      "scope": "users",
+      "method": "POST",
+      "fullPath": "/users",
+      "schema": {
+        "input": {
+          "body": {
+            "oneOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "kind": { "const": "guest" },
+                  "displayName": { "type": "string" }
+                },
+                "required": ["kind", "displayName"]
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "kind": { "const": "registered" },
+                  "email": { "type": "string" },
+                  "name": { "type": "string" }
+                },
+                "required": ["kind", "email", "name"]
+              }
+            ]
+          }
+        },
+        "returnType": {
+          "type": "object",
+          "properties": { "id": { "type": "string" } },
+          "required": ["id"]
+        }
+      },
+      "errors": ["ValidationError"]
+    },
+    {
+      "kind": "api",
+      "name": "ListUsers",
+      "scope": "users",
+      "method": "GET",
+      "fullPath": "/users",
+      "schema": {
+        "input": {
+          "query": {
+            "type": "object",
+            "properties": {
+              "status": { "type": "string", "enum": ["active", "inactive"] },
+              "limit": { "type": "integer" }
+            }
+          }
+        },
+        "returnType": {
+          "type": "object",
+          "properties": {
+            "items": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": { "type": "string" },
+                  "name": { "type": "string" }
+                },
+                "required": ["id", "name"]
+              }
+            }
+          },
+          "required": ["items"]
+        }
+      },
+      "errors": []
+    }
+  ],
+  "errors": [
+    {
+      "name": "NotFound",
+      "statusCode": 404,
+      "description": "Resource not found",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "name": { "const": "NotFound" },
+          "message": { "type": "string" }
+        },
+        "required": ["name", "message"]
+      }
+    },
+    {
+      "name": "ValidationError",
+      "statusCode": 400,
+      "description": "Input failed validation",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "name": { "const": "ValidationError" },
+          "message": { "type": "string" },
+          "field": { "type": "string" }
+        },
+        "required": ["name", "message"]
+      }
+    }
+  ]
+}