@stackwright-pro/openapi 0.2.2-alpha.3 → 0.3.0-alpha.10

package/dist/index.d.mts

@@ -1,95 +1,14 @@
 import { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 import { z, ZodSchema } from 'zod';
+import { ActionConfig, EndpointFilter as EndpointFilter$1, PrebuildSecurityConfig, ValidationResult } from '@stackwright-pro/types';
+export { ActionConfig, ApprovedSpec, OpenAPIConfig, PrebuildSecurityConfig, SiteConfig, ValidationResult } from '@stackwright-pro/types';
 
 /**
  * Supported OpenAPI versions
  */
 type OpenAPIDocument = OpenAPIV3.Document | OpenAPIV3_1.Document;
 /**
- * An approved API specification.
- * Used by enterprise customers to whitelist specific OpenAPI specs.
- */
-interface ApprovedSpec {
-    /** Human-readable name for the spec */
-    name: string;
-    /** URL or file path to the approved spec */
-    url: string;
-    /** Expected SHA-256 hash of the spec content */
-    sha256: string;
-}
-/**
- * Security configuration for approved specs enforcement.
- * Configured in stackwright.yml under `prebuild.security`.
- */
-interface PrebuildSecurityConfig {
-    /** Enable approved-specs enforcement */
-    enabled: boolean;
-    /** List of approved specifications */
-    allowlist: ApprovedSpec[];
-}
-/**
- * Result of validating a spec against the approved list.
- */
-interface ValidationResult {
-    /** Whether the spec is approved */
-    valid: boolean;
-    /** Error code if not valid */
-    errorCode?: 'SPEC_NOT_ON_ALLOWLIST' | 'SPEC_MODIFIED' | 'DOWNLOAD_FAILED';
-    /** Human-readable error message */
-    error?: string;
-    /** URL of the spec that was validated */
-    specUrl?: string;
-}
-/**
- * Extended site config with prebuild security.
- * Users can add this to stackwright.yml.
- */
-interface SiteConfig {
-    /** Prebuild configuration */
-    prebuild?: {
-        /** Security settings for approved-specs enforcement */
-        security?: PrebuildSecurityConfig;
-    };
-}
-/**
- * Endpoint filter configuration
- */
-interface EndpointFilter$1 {
-    /** Endpoints/patterns to include (default: all) */
-    include?: string[];
-    /** Endpoints/patterns to exclude */
-    exclude?: string[];
-}
-/**
- * Configuration for OpenAPI integration in stackwright.yml
- */
-interface OpenAPIConfig {
-    /** Name of this integration */
-    name: string;
-    /** OpenAPI spec (URL or local file path) */
-    spec: string;
-    /** Mock server URL for development (e.g., http://localhost:4010) */
-    mockUrl?: string;
-    /** Authentication configuration */
-    auth?: {
-        type: 'bearer' | 'apiKey' | 'oauth2';
-        token?: string;
-        apiKey?: string;
-    };
-    /** Collections to generate from endpoints */
-    collections?: Array<{
-        /** API endpoint path */
-        endpoint: string;
-        /** Field to use as slug/ID */
-        slug_field: string;
-        /** Optional filters */
-        filters?: Record<string, unknown>;
-    }>;
-    /** Endpoint filter - only generate code for matching endpoints */
-    endpoints?: EndpointFilter$1;
-}
-/**
- * Result of OpenAPI compilation
+ * Result of OpenAPI compilation (internal — not a public contract)
  */
 interface OpenAPICompilationResult {
     /** Generated Zod schemas as code */
@@ -100,6 +19,8 @@ interface OpenAPICompilationResult {
     provider: string;
     /** Generated API client */
     client: string;
+    /** Generated CollectionAction implementations */
+    actions: string;
 }
 
 interface ParseOptions {
@@ -164,16 +85,38 @@ type SchemaObject$1 = OpenAPIV3.SchemaObject | OpenAPIV3_1.SchemaObject;
  */
 declare class SchemaResolver {
     private document;
+    /**
+     * @param document - Fully dereferenced OpenAPI document. Pass the result of
+     * SwaggerParser.dereference() or OpenAPIParser.parse(). Passing a document
+     * with unresolved $ref objects will produce console warnings and undefined
+     * returns from schema extraction methods.
+     */
     constructor(document: OpenAPIV3.Document | OpenAPIV3_1.Document);
     /**
-     * Get schema for a specific path and method
+     * Get schema for a specific path and method.
+     *
+     * Tries `preferredResponseCode` first (default `'200'`). If that code is
+     * absent or has no JSON schema, falls back through other 2xx codes in
+     * priority order so that REST-correct `201 Created` responses are resolved
+     * automatically.
      *
      * @param path - API path (e.g., '/equipment')
      * @param method - HTTP method (e.g., 'get')
-     * @param responseCode - Response code (default: '200')
+     * @param preferredResponseCode - Response code to try first (default: '200')
+     * @returns Schema object or undefined
+     */
+    getResponseSchema(path: string, method: string, preferredResponseCode?: string): SchemaObject$1 | undefined;
+    /**
+     * Get the request body schema for a specific path and method.
+     *
+     * Extracts the application/json schema from the operation's requestBody.
+     * Returns undefined if the operation has no requestBody or no JSON content.
+     *
+     * @param path - API path (e.g., '/supplies/request')
+     * @param method - HTTP method (e.g., 'post')
      * @returns Schema object or undefined
      */
-    getResponseSchema(path: string, method: string, responseCode?: string): SchemaObject$1 | undefined;
+    getRequestBodySchema(path: string, method: string): SchemaObject$1 | undefined;
     /**
      * Get all schemas defined in components
      */
@@ -377,6 +320,55 @@ declare class CollectionProviderGenerator {
     private guessTitle;
 }
 
+/**
+ * ActionGenerator
+ *
+ * Generates typed CollectionAction implementations from OpenAPI action configs.
+ * Each configured action endpoint becomes a named export satisfying the
+ * CollectionAction<TInput, TOutput> interface from @stackwright-pro/workflow.
+ *
+ * The generated actions.ts is the bridge between:
+ *   - stackwright.yml  actions: config  (what to generate)
+ *   - workflow YAML    service: refs    (how it's addressed at runtime)
+ *   - useWorkflow      actions registry (where it executes)
+ *
+ * IoC note: This generator emits `import type { CollectionAction } from
+ * '@stackwright-pro/workflow'` as a string. The generator package itself has
+ * no dependency on @stackwright-pro/workflow — only the generated files do.
+ */
+declare class ActionGenerator {
+    private document;
+    private resolver;
+    private zodGenerator;
+    constructor(document: OpenAPIDocument);
+    /**
+     * Generate the complete actions.ts file content.
+     *
+     * @param actions - Action configs from stackwright.yml
+     * @param integrationName - Used in the file header comment
+     * @param clientClassName - Name of the generated API client class to import
+     * @returns Complete TypeScript source for actions.ts
+     */
+    generate(actions: ActionConfig[], integrationName: string, clientClassName: string): string;
+    private processAction;
+    private generateHeader;
+    private generateImports;
+    private generateInlineSchemas;
+    private generateActionExports;
+    private generateRegistry;
+    private generateEmptyFile;
+    /** Derives the client method name from endpoint + method.
+     *  Prefers operationId (matching ClientGenerator.getMethodName()), falls back
+     *  to path+method derivation for specs that omit operationIds. */
+    private endpointToClientMethod;
+    /** Convert any string to camelCase — handles operationId values like
+     *  createOrder, list_items, get-by-id, etc. */
+    private camelCase;
+    private toCamelCase;
+    private toPascalCase;
+    private capitalize;
+}
+
 /**
  * Mapping of operationId to schema names
  */
@@ -423,6 +415,7 @@ declare class ClientGenerator {
     private schemaMapping?;
     private requiredSchemas;
     private generatedRequestSchemas;
+    private generatedRequestTypes;
     constructor(document: OpenAPIDocument, schemaMapping?: SchemaMapping);
     /**
      * Generate typed API client code from OpenAPI document
@@ -685,6 +678,7 @@ declare class OpenAPIPlugin implements PrebuildPlugin {
     private generateSchemas;
     private generateTypes;
     private generateProvider;
+    private generateActions;
     private generateClient;
     private extractComponentName;
     private getOperationTypeName;
@@ -954,4 +948,4 @@ declare class ApprovedSpecsValidator {
     clearCache(): void;
 }
 
-export { type ApprovedSpec, ApprovedSpecsValidator, type ClientGenerationOptions, ClientGenerator, type CollectionConfig, CollectionProviderGenerator, EndpointFilter, type OpenAPICompilationResult, type OpenAPIConfig, type OpenAPIDocument, OpenAPIParser, OpenAPIPlugin, type OpenAPISourceConfig, type ParseOptions, type ParseResult, type PrebuildSecurityConfig, type ProviderGenerationOptions, type SchemaMapping, SchemaResolver, type SiteConfig, type TypeGenerationOptions, TypeGenerator, type ValidationResult, type ZodGenerationOptions, ZodSchemaGenerator, createOpenAPIFetcher, createOpenAPIPlugin, isUrlSafe, validateUrlSafe };
+export { ActionGenerator, ApprovedSpecsValidator, type ClientGenerationOptions, ClientGenerator, type CollectionConfig, CollectionProviderGenerator, EndpointFilter, type OpenAPICompilationResult, type OpenAPIDocument, OpenAPIParser, OpenAPIPlugin, type OpenAPISourceConfig, type ParseOptions, type ParseResult, type ProviderGenerationOptions, type SchemaMapping, SchemaResolver, type TypeGenerationOptions, TypeGenerator, type ZodGenerationOptions, ZodSchemaGenerator, createOpenAPIFetcher, createOpenAPIPlugin, isUrlSafe, validateUrlSafe };

package/dist/index.d.ts

@@ -1,95 +1,14 @@
 import { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
 import { z, ZodSchema } from 'zod';
+import { ActionConfig, EndpointFilter as EndpointFilter$1, PrebuildSecurityConfig, ValidationResult } from '@stackwright-pro/types';
+export { ActionConfig, ApprovedSpec, OpenAPIConfig, PrebuildSecurityConfig, SiteConfig, ValidationResult } from '@stackwright-pro/types';
 
 /**
  * Supported OpenAPI versions
  */
 type OpenAPIDocument = OpenAPIV3.Document | OpenAPIV3_1.Document;
 /**
- * An approved API specification.
- * Used by enterprise customers to whitelist specific OpenAPI specs.
- */
-interface ApprovedSpec {
-    /** Human-readable name for the spec */
-    name: string;
-    /** URL or file path to the approved spec */
-    url: string;
-    /** Expected SHA-256 hash of the spec content */
-    sha256: string;
-}
-/**
- * Security configuration for approved specs enforcement.
- * Configured in stackwright.yml under `prebuild.security`.
- */
-interface PrebuildSecurityConfig {
-    /** Enable approved-specs enforcement */
-    enabled: boolean;
-    /** List of approved specifications */
-    allowlist: ApprovedSpec[];
-}
-/**
- * Result of validating a spec against the approved list.
- */
-interface ValidationResult {
-    /** Whether the spec is approved */
-    valid: boolean;
-    /** Error code if not valid */
-    errorCode?: 'SPEC_NOT_ON_ALLOWLIST' | 'SPEC_MODIFIED' | 'DOWNLOAD_FAILED';
-    /** Human-readable error message */
-    error?: string;
-    /** URL of the spec that was validated */
-    specUrl?: string;
-}
-/**
- * Extended site config with prebuild security.
- * Users can add this to stackwright.yml.
- */
-interface SiteConfig {
-    /** Prebuild configuration */
-    prebuild?: {
-        /** Security settings for approved-specs enforcement */
-        security?: PrebuildSecurityConfig;
-    };
-}
-/**
- * Endpoint filter configuration
- */
-interface EndpointFilter$1 {
-    /** Endpoints/patterns to include (default: all) */
-    include?: string[];
-    /** Endpoints/patterns to exclude */
-    exclude?: string[];
-}
-/**
- * Configuration for OpenAPI integration in stackwright.yml
- */
-interface OpenAPIConfig {
-    /** Name of this integration */
-    name: string;
-    /** OpenAPI spec (URL or local file path) */
-    spec: string;
-    /** Mock server URL for development (e.g., http://localhost:4010) */
-    mockUrl?: string;
-    /** Authentication configuration */
-    auth?: {
-        type: 'bearer' | 'apiKey' | 'oauth2';
-        token?: string;
-        apiKey?: string;
-    };
-    /** Collections to generate from endpoints */
-    collections?: Array<{
-        /** API endpoint path */
-        endpoint: string;
-        /** Field to use as slug/ID */
-        slug_field: string;
-        /** Optional filters */
-        filters?: Record<string, unknown>;
-    }>;
-    /** Endpoint filter - only generate code for matching endpoints */
-    endpoints?: EndpointFilter$1;
-}
-/**
- * Result of OpenAPI compilation
+ * Result of OpenAPI compilation (internal — not a public contract)
  */
 interface OpenAPICompilationResult {
     /** Generated Zod schemas as code */
@@ -100,6 +19,8 @@ interface OpenAPICompilationResult {
     provider: string;
     /** Generated API client */
     client: string;
+    /** Generated CollectionAction implementations */
+    actions: string;
 }
 
 interface ParseOptions {
@@ -164,16 +85,38 @@ type SchemaObject$1 = OpenAPIV3.SchemaObject | OpenAPIV3_1.SchemaObject;
  */
 declare class SchemaResolver {
     private document;
+    /**
+     * @param document - Fully dereferenced OpenAPI document. Pass the result of
+     * SwaggerParser.dereference() or OpenAPIParser.parse(). Passing a document
+     * with unresolved $ref objects will produce console warnings and undefined
+     * returns from schema extraction methods.
+     */
     constructor(document: OpenAPIV3.Document | OpenAPIV3_1.Document);
     /**
-     * Get schema for a specific path and method
+     * Get schema for a specific path and method.
+     *
+     * Tries `preferredResponseCode` first (default `'200'`). If that code is
+     * absent or has no JSON schema, falls back through other 2xx codes in
+     * priority order so that REST-correct `201 Created` responses are resolved
+     * automatically.
      *
      * @param path - API path (e.g., '/equipment')
      * @param method - HTTP method (e.g., 'get')
-     * @param responseCode - Response code (default: '200')
+     * @param preferredResponseCode - Response code to try first (default: '200')
+     * @returns Schema object or undefined
+     */
+    getResponseSchema(path: string, method: string, preferredResponseCode?: string): SchemaObject$1 | undefined;
+    /**
+     * Get the request body schema for a specific path and method.
+     *
+     * Extracts the application/json schema from the operation's requestBody.
+     * Returns undefined if the operation has no requestBody or no JSON content.
+     *
+     * @param path - API path (e.g., '/supplies/request')
+     * @param method - HTTP method (e.g., 'post')
      * @returns Schema object or undefined
      */
-    getResponseSchema(path: string, method: string, responseCode?: string): SchemaObject$1 | undefined;
+    getRequestBodySchema(path: string, method: string): SchemaObject$1 | undefined;
     /**
      * Get all schemas defined in components
      */
@@ -377,6 +320,55 @@ declare class CollectionProviderGenerator {
     private guessTitle;
 }
 
+/**
+ * ActionGenerator
+ *
+ * Generates typed CollectionAction implementations from OpenAPI action configs.
+ * Each configured action endpoint becomes a named export satisfying the
+ * CollectionAction<TInput, TOutput> interface from @stackwright-pro/workflow.
+ *
+ * The generated actions.ts is the bridge between:
+ *   - stackwright.yml  actions: config  (what to generate)
+ *   - workflow YAML    service: refs    (how it's addressed at runtime)
+ *   - useWorkflow      actions registry (where it executes)
+ *
+ * IoC note: This generator emits `import type { CollectionAction } from
+ * '@stackwright-pro/workflow'` as a string. The generator package itself has
+ * no dependency on @stackwright-pro/workflow — only the generated files do.
+ */
+declare class ActionGenerator {
+    private document;
+    private resolver;
+    private zodGenerator;
+    constructor(document: OpenAPIDocument);
+    /**
+     * Generate the complete actions.ts file content.
+     *
+     * @param actions - Action configs from stackwright.yml
+     * @param integrationName - Used in the file header comment
+     * @param clientClassName - Name of the generated API client class to import
+     * @returns Complete TypeScript source for actions.ts
+     */
+    generate(actions: ActionConfig[], integrationName: string, clientClassName: string): string;
+    private processAction;
+    private generateHeader;
+    private generateImports;
+    private generateInlineSchemas;
+    private generateActionExports;
+    private generateRegistry;
+    private generateEmptyFile;
+    /** Derives the client method name from endpoint + method.
+     *  Prefers operationId (matching ClientGenerator.getMethodName()), falls back
+     *  to path+method derivation for specs that omit operationIds. */
+    private endpointToClientMethod;
+    /** Convert any string to camelCase — handles operationId values like
+     *  createOrder, list_items, get-by-id, etc. */
+    private camelCase;
+    private toCamelCase;
+    private toPascalCase;
+    private capitalize;
+}
+
 /**
  * Mapping of operationId to schema names
  */
@@ -423,6 +415,7 @@ declare class ClientGenerator {
     private schemaMapping?;
     private requiredSchemas;
     private generatedRequestSchemas;
+    private generatedRequestTypes;
     constructor(document: OpenAPIDocument, schemaMapping?: SchemaMapping);
     /**
      * Generate typed API client code from OpenAPI document
@@ -685,6 +678,7 @@ declare class OpenAPIPlugin implements PrebuildPlugin {
     private generateSchemas;
     private generateTypes;
     private generateProvider;
+    private generateActions;
     private generateClient;
     private extractComponentName;
     private getOperationTypeName;
@@ -954,4 +948,4 @@ declare class ApprovedSpecsValidator {
     clearCache(): void;
 }
 
-export { type ApprovedSpec, ApprovedSpecsValidator, type ClientGenerationOptions, ClientGenerator, type CollectionConfig, CollectionProviderGenerator, EndpointFilter, type OpenAPICompilationResult, type OpenAPIConfig, type OpenAPIDocument, OpenAPIParser, OpenAPIPlugin, type OpenAPISourceConfig, type ParseOptions, type ParseResult, type PrebuildSecurityConfig, type ProviderGenerationOptions, type SchemaMapping, SchemaResolver, type SiteConfig, type TypeGenerationOptions, TypeGenerator, type ValidationResult, type ZodGenerationOptions, ZodSchemaGenerator, createOpenAPIFetcher, createOpenAPIPlugin, isUrlSafe, validateUrlSafe };
+export { ActionGenerator, ApprovedSpecsValidator, type ClientGenerationOptions, ClientGenerator, type CollectionConfig, CollectionProviderGenerator, EndpointFilter, type OpenAPICompilationResult, type OpenAPIDocument, OpenAPIParser, OpenAPIPlugin, type OpenAPISourceConfig, type ParseOptions, type ParseResult, type ProviderGenerationOptions, type SchemaMapping, SchemaResolver, type TypeGenerationOptions, TypeGenerator, type ZodGenerationOptions, ZodSchemaGenerator, createOpenAPIFetcher, createOpenAPIPlugin, isUrlSafe, validateUrlSafe };