@stackwright-pro/openapi 0.3.0-alpha.2 → 0.3.0-alpha.4

package/dist/index.d.mts

@@ -60,6 +60,32 @@ interface EndpointFilter$1 {
     /** Endpoints/patterns to exclude */
     exclude?: string[];
 }
+/**
+ * Configuration for a single action endpoint in stackwright.yml
+ *
+ * Actions are write-through endpoints (POST, PUT, DELETE, PATCH) that can be
+ * invoked from workflow on_submit handlers via service: references.
+ *
+ * Unlike collections (which generate CollectionProviders for data display),
+ * actions generate typed, schema-validated callables that the workflow runtime
+ * resolves by name.
+ *
+ * Example stackwright.yml:
+ *   actions:
+ *     - name: create-supply-request      # resolves service:create-supply-request
+ *       endpoint: /supplies/request
+ *       method: POST
+ */
+interface ActionConfig {
+    /** Service name — resolves service:<name> in workflow YAML on_submit.action */
+    name: string;
+    /** API endpoint path (e.g. '/supplies/request') */
+    endpoint: string;
+    /** HTTP method — typically POST, PUT, PATCH, or DELETE */
+    method: 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Optional human-readable description (used in generated JSDoc) */
+    description?: string;
+}
 /**
  * Configuration for OpenAPI integration in stackwright.yml
  */
@@ -82,9 +108,13 @@ interface OpenAPIConfig {
         endpoint: string;
         /** Field to use as slug/ID */
         slug_field: string;
+        /** HTTP method for this collection endpoint — defaults to 'GET' */
+        method?: string;
         /** Optional filters */
         filters?: Record<string, unknown>;
     }>;
+    /** Actions to generate from write endpoints (POST, PUT, PATCH, DELETE) */
+    actions?: ActionConfig[];
     /** Endpoint filter - only generate code for matching endpoints */
     endpoints?: EndpointFilter$1;
 }
@@ -100,6 +130,8 @@ interface OpenAPICompilationResult {
     provider: string;
     /** Generated API client */
     client: string;
+    /** Generated CollectionAction implementations */
+    actions: string;
 }
 
 interface ParseOptions {
@@ -164,16 +196,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 +431,50 @@ 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 (best-effort) */
+    private endpointToClientMethod;
+    private toCamelCase;
+    private toPascalCase;
+    private capitalize;
+}
+
 /**
  * Mapping of operationId to schema names
  */
@@ -685,6 +783,7 @@ declare class OpenAPIPlugin implements PrebuildPlugin {
     private generateSchemas;
     private generateTypes;
     private generateProvider;
+    private generateActions;
     private generateClient;
     private extractComponentName;
     private getOperationTypeName;
@@ -954,4 +1053,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 { type ActionConfig, ActionGenerator, 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 };

package/dist/index.d.ts

@@ -60,6 +60,32 @@ interface EndpointFilter$1 {
     /** Endpoints/patterns to exclude */
     exclude?: string[];
 }
+/**
+ * Configuration for a single action endpoint in stackwright.yml
+ *
+ * Actions are write-through endpoints (POST, PUT, DELETE, PATCH) that can be
+ * invoked from workflow on_submit handlers via service: references.
+ *
+ * Unlike collections (which generate CollectionProviders for data display),
+ * actions generate typed, schema-validated callables that the workflow runtime
+ * resolves by name.
+ *
+ * Example stackwright.yml:
+ *   actions:
+ *     - name: create-supply-request      # resolves service:create-supply-request
+ *       endpoint: /supplies/request
+ *       method: POST
+ */
+interface ActionConfig {
+    /** Service name — resolves service:<name> in workflow YAML on_submit.action */
+    name: string;
+    /** API endpoint path (e.g. '/supplies/request') */
+    endpoint: string;
+    /** HTTP method — typically POST, PUT, PATCH, or DELETE */
+    method: 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** Optional human-readable description (used in generated JSDoc) */
+    description?: string;
+}
 /**
  * Configuration for OpenAPI integration in stackwright.yml
  */
@@ -82,9 +108,13 @@ interface OpenAPIConfig {
         endpoint: string;
         /** Field to use as slug/ID */
         slug_field: string;
+        /** HTTP method for this collection endpoint — defaults to 'GET' */
+        method?: string;
         /** Optional filters */
         filters?: Record<string, unknown>;
     }>;
+    /** Actions to generate from write endpoints (POST, PUT, PATCH, DELETE) */
+    actions?: ActionConfig[];
     /** Endpoint filter - only generate code for matching endpoints */
     endpoints?: EndpointFilter$1;
 }
@@ -100,6 +130,8 @@ interface OpenAPICompilationResult {
     provider: string;
     /** Generated API client */
     client: string;
+    /** Generated CollectionAction implementations */
+    actions: string;
 }
 
 interface ParseOptions {
@@ -164,16 +196,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 +431,50 @@ 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 (best-effort) */
+    private endpointToClientMethod;
+    private toCamelCase;
+    private toPascalCase;
+    private capitalize;
+}
+
 /**
  * Mapping of operationId to schema names
  */
@@ -685,6 +783,7 @@ declare class OpenAPIPlugin implements PrebuildPlugin {
     private generateSchemas;
     private generateTypes;
     private generateProvider;
+    private generateActions;
     private generateClient;
     private extractComponentName;
     private getOperationTypeName;
@@ -954,4 +1053,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 { type ActionConfig, ActionGenerator, 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 };