@kubb/core 4.22.0 → 4.22.1

package/schemas/openapi/server.yaml

@@ -0,0 +1,524 @@
+openapi: 3.1.0
+info:
+  title: Kubb Server API
+  version: 1.0.0
+  description: |
+    The Kubb Stream Server provides a real-time HTTP API for code generation using Server-Sent Events (SSE).
+    This API enables live progress tracking, event streaming, and integration with external tools.
+
+    Start the server with: `npx kubb start`
+  contact:
+    name: Kubb
+    url: https://kubb.dev
+  license:
+    name: MIT
+    url: https://github.com/kubb-labs/kubb/blob/main/LICENSE
+
+servers:
+  - url: http://localhost:3000
+    description: Local development server
+
+tags:
+  - name: Health
+    description: Server health and status endpoints
+  - name: Configuration
+    description: Configuration and metadata endpoints
+  - name: Generation
+    description: Code generation endpoints
+
+paths:
+  /api/health:
+    get:
+      summary: Health check
+      description: Returns server status and version information
+      operationId: getHealth
+      tags:
+        - Health
+      responses:
+        '200':
+          description: Server is healthy
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthResponse'
+              example:
+                status: ok
+                version: 4.22.0
+                configPath: kubb.config.ts
+
+  /api/info:
+    get:
+      summary: Get configuration info
+      description: Returns configuration metadata and the OpenAPI specification content
+      operationId: getInfo
+      tags:
+        - Configuration
+      responses:
+        '200':
+          description: Configuration metadata
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ConnectResponse'
+              example:
+                version: 4.22.0
+                configPath: kubb.config.ts
+                spec: "openapi: 3.0.0\ninfo:\n  title: Pet Store API\n..."
+                config:
+                  name: my-api
+                  root: .
+                  input:
+                    path: ./openapi.yaml
+                  output:
+                    path: ./src/gen
+                    write: true
+                    extension:
+                      .ts: .ts
+                    barrelType: all
+                  plugins:
+                    - name: '@kubb/plugin-oas'
+                      options: {}
+                    - name: '@kubb/plugin-ts'
+                      options: {}
+
+  /api/generate:
+    post:
+      summary: Generate code with SSE streaming
+      description: |
+        Starts code generation and streams progress events via Server-Sent Events (SSE).
+        The response is a continuous stream of events in SSE format.
+
+        Each event contains a `type` field and a `data` array with event-specific payload.
+      operationId: generateCode
+      tags:
+        - Generation
+      responses:
+        '200':
+          description: SSE event stream
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                description: Server-Sent Events stream with JSON-encoded StreamEvent objects
+              examples:
+                generation_flow:
+                  summary: Typical generation flow
+                  value: |
+                    data: {"type":"generation:start","data":[{"name":"my-api","plugins":2}]}
+
+                    data: {"type":"plugin:start","data":[{"name":"plugin-oas"}]}
+
+                    data: {"type":"plugin:end","data":[{"name":"plugin-oas"},{"duration":150,"success":true}]}
+
+                    data: {"type":"plugin:start","data":[{"name":"plugin-ts"}]}
+
+                    data: {"type":"files:processing:start","data":[{"total":10}]}
+
+                    data: {"type":"file:processing:update","data":[{"file":"models/Pet.ts","processed":1,"total":10,"percentage":10}]}
+
+                    data: {"type":"file:processing:update","data":[{"file":"models/User.ts","processed":2,"total":10,"percentage":20}]}
+
+                    data: {"type":"files:processing:end","data":[{"total":10}]}
+
+                    data: {"type":"plugin:end","data":[{"name":"plugin-ts"},{"duration":500,"success":true}]}
+
+                    data: {"type":"generation:end","data":[{},[]]}
+
+                    data: {"type":"lifecycle:end","data":[]}
+
+                error_example:
+                  summary: Error during generation
+                  value: |
+                    data: {"type":"generation:start","data":[{"name":"my-api","plugins":1}]}
+
+                    data: {"type":"error","data":[{"message":"Failed to parse OpenAPI spec","stack":"Error: Failed to parse..."}]}
+
+components:
+  schemas:
+    HealthResponse:
+      type: object
+      required:
+        - status
+        - version
+        - configPath
+      properties:
+        status:
+          type: string
+          enum: [ok]
+          description: Server status
+        version:
+          type: string
+          description: Kubb version
+          example: 4.22.0
+        configPath:
+          type: string
+          description: Relative path to the configuration file
+          example: kubb.config.ts
+
+    ConnectResponse:
+      type: object
+      required:
+        - version
+        - configPath
+        - config
+      properties:
+        version:
+          type: string
+          description: Kubb version
+          example: 4.22.0
+        configPath:
+          type: string
+          description: Relative path to the configuration file
+          example: kubb.config.ts
+        spec:
+          type: string
+          description: OpenAPI specification file content (YAML or JSON)
+          nullable: true
+        config:
+          $ref: '#/components/schemas/ConfigMetadata'
+
+    ConfigMetadata:
+      type: object
+      required:
+        - root
+        - input
+        - output
+      properties:
+        name:
+          type: string
+          description: Project name
+          example: my-api
+        root:
+          type: string
+          description: Root directory
+          example: .
+        input:
+          type: object
+          properties:
+            path:
+              type: string
+              description: Path to OpenAPI specification
+              example: ./openapi.yaml
+        output:
+          type: object
+          required:
+            - path
+          properties:
+            path:
+              type: string
+              description: Output directory path
+              example: ./src/gen
+            write:
+              type: boolean
+              description: Whether to write files to disk
+              example: true
+            extension:
+              type: object
+              additionalProperties:
+                type: string
+              description: File extension mappings
+              example:
+                .ts: .ts
+            barrelType:
+              oneOf:
+                - type: string
+                  enum: [all, named]
+                - type: boolean
+                  enum: [false]
+              description: Barrel file generation strategy
+              example: all
+        plugins:
+          type: array
+          items:
+            $ref: '#/components/schemas/PluginMetadata'
+
+    PluginMetadata:
+      type: object
+      required:
+        - name
+        - options
+      properties:
+        name:
+          type: string
+          description: Plugin name
+          example: '@kubb/plugin-ts'
+        options:
+          type: object
+          description: Plugin-specific configuration
+          additionalProperties: true
+
+    StreamEvent:
+      type: object
+      required:
+        - type
+        - data
+      properties:
+        type:
+          $ref: '#/components/schemas/StreamEventType'
+        data:
+          type: array
+          description: Event-specific payload (varies by event type)
+          items: {}
+      discriminator:
+        propertyName: type
+        mapping:
+          'plugin:start': '#/components/schemas/PluginStartEvent'
+          'plugin:end': '#/components/schemas/PluginEndEvent'
+          'files:processing:start': '#/components/schemas/FilesProcessingStartEvent'
+          'file:processing:update': '#/components/schemas/FileProcessingUpdateEvent'
+          'files:processing:end': '#/components/schemas/FilesProcessingEndEvent'
+          'info': '#/components/schemas/InfoEvent'
+          'success': '#/components/schemas/SuccessEvent'
+          'warn': '#/components/schemas/WarnEvent'
+          'error': '#/components/schemas/ErrorEvent'
+          'generation:start': '#/components/schemas/GenerationStartEvent'
+          'generation:end': '#/components/schemas/GenerationEndEvent'
+          'lifecycle:end': '#/components/schemas/LifecycleEndEvent'
+
+    StreamEventType:
+      type: string
+      enum:
+        - plugin:start
+        - plugin:end
+        - files:processing:start
+        - file:processing:update
+        - files:processing:end
+        - info
+        - success
+        - warn
+        - error
+        - generation:start
+        - generation:end
+        - lifecycle:end
+      description: Type of stream event
+
+    PluginStartEvent:
+      allOf:
+        - $ref: '#/components/schemas/StreamEvent'
+        - type: object
+          properties:
+            type:
+              type: string
+              enum: ['plugin:start']
+            data:
+              type: array
+              minItems: 1
+              maxItems: 1
+              items:
+                type: object
+                properties:
+                  name:
+                    type: string
+                    description: Plugin name
+                    example: plugin-ts
+
+    PluginEndEvent:
+      allOf:
+        - $ref: '#/components/schemas/StreamEvent'
+        - type: object
+          properties:
+            type:
+              type: string
+              enum: ['plugin:end']
+            data:
+              type: array
+              minItems: 2
+              maxItems: 2
+              items:
+                oneOf:
+                  - type: object
+                    properties:
+                      name:
+                        type: string
+                  - type: object
+                    properties:
+                      duration:
+                        type: number
+                        description: Plugin execution duration in milliseconds
+                      success:
+                        type: boolean
+                        description: Whether plugin executed successfully
+
+    FilesProcessingStartEvent:
+      allOf:
+        - $ref: '#/components/schemas/StreamEvent'
+        - type: object
+          properties:
+            type:
+              type: string
+              enum: ['files:processing:start']
+            data:
+              type: array
+              minItems: 1
+              maxItems: 1
+              items:
+                type: object
+                properties:
+                  total:
+                    type: number
+                    description: Total number of files to process
+
+    FileProcessingUpdateEvent:
+      allOf:
+        - $ref: '#/components/schemas/StreamEvent'
+        - type: object
+          properties:
+            type:
+              type: string
+              enum: ['file:processing:update']
+            data:
+              type: array
+              minItems: 1
+              maxItems: 1
+              items:
+                type: object
+                properties:
+                  file:
+                    type: string
+                    description: File path being processed
+                  processed:
+                    type: number
+                    description: Number of files processed so far
+                  total:
+                    type: number
+                    description: Total number of files
+                  percentage:
+                    type: number
+                    description: Percentage of completion
+
+    FilesProcessingEndEvent:
+      allOf:
+        - $ref: '#/components/schemas/StreamEvent'
+        - type: object
+          properties:
+            type:
+              type: string
+              enum: ['files:processing:end']
+            data:
+              type: array
+              minItems: 1
+              maxItems: 1
+              items:
+                type: object
+                properties:
+                  total:
+                    type: number
+                    description: Total number of files processed
+
+    InfoEvent:
+      allOf:
+        - $ref: '#/components/schemas/StreamEvent'
+        - type: object
+          properties:
+            type:
+              type: string
+              enum: ['info']
+            data:
+              type: array
+              minItems: 1
+              maxItems: 2
+              items:
+                type: string
+
+    SuccessEvent:
+      allOf:
+        - $ref: '#/components/schemas/StreamEvent'
+        - type: object
+          properties:
+            type:
+              type: string
+              enum: ['success']
+            data:
+              type: array
+              minItems: 1
+              maxItems: 2
+              items:
+                type: string
+
+    WarnEvent:
+      allOf:
+        - $ref: '#/components/schemas/StreamEvent'
+        - type: object
+          properties:
+            type:
+              type: string
+              enum: ['warn']
+            data:
+              type: array
+              minItems: 1
+              maxItems: 2
+              items:
+                type: string
+
+    ErrorEvent:
+      allOf:
+        - $ref: '#/components/schemas/StreamEvent'
+        - type: object
+          properties:
+            type:
+              type: string
+              enum: ['error']
+            data:
+              type: array
+              minItems: 1
+              maxItems: 1
+              items:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    description: Error message
+                  stack:
+                    type: string
+                    description: Error stack trace
+                    nullable: true
+
+    GenerationStartEvent:
+      allOf:
+        - $ref: '#/components/schemas/StreamEvent'
+        - type: object
+          properties:
+            type:
+              type: string
+              enum: ['generation:start']
+            data:
+              type: array
+              minItems: 1
+              maxItems: 1
+              items:
+                type: object
+                properties:
+                  name:
+                    type: string
+                    description: Configuration name
+                    nullable: true
+                  plugins:
+                    type: number
+                    description: Number of plugins
+
+    GenerationEndEvent:
+      allOf:
+        - $ref: '#/components/schemas/StreamEvent'
+        - type: object
+          properties:
+            type:
+              type: string
+              enum: ['generation:end']
+            data:
+              type: array
+              description: Config, generated files, and source mappings
+              minItems: 3
+              maxItems: 3
+
+    LifecycleEndEvent:
+      allOf:
+        - $ref: '#/components/schemas/StreamEvent'
+        - type: object
+          properties:
+            type:
+              type: string
+              enum: ['lifecycle:end']
+            data:
+              type: array
+              maxItems: 0
+              description: Empty array - signals generation completion

package/src/index.ts

@@ -6,6 +6,8 @@ export { definePlugin } from './definePlugin.ts'
 export { PackageManager } from './PackageManager.ts'
 export { getMode, PluginManager } from './PluginManager.ts'
 export { PromiseManager } from './PromiseManager.ts'
+export type { HealthResponse, InfoResponse, ServerEvents, SseEvent, SseEvents, SseEventType } from './server/index.ts'
+export { startServer } from './server/index.ts'
 export * from './types.ts'
 export type { FileMetaBase } from './utils/getBarrelFiles.ts'
 export { getBarrelFiles } from './utils/getBarrelFiles.ts'