@stackwright-pro/openapi 0.3.0-alpha.5 → 0.3.0-alpha.7

package/dist/index.d.mts

@@ -110,6 +110,8 @@ interface OpenAPIConfig {
         slug_field: string;
         /** HTTP method for this collection endpoint — defaults to 'GET' */
         method?: string;
+        /** Transport protocol — 'websocket' collections are skipped during prebuild */
+        transport?: string;
         /** Optional filters */
         filters?: Record<string, unknown>;
     }>;
@@ -468,8 +470,13 @@ declare class ActionGenerator {
     private generateActionExports;
     private generateRegistry;
     private generateEmptyFile;
-    /** Derives the client method name from endpoint + method (best-effort) */
+    /** 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;
@@ -521,6 +528,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

package/dist/index.d.ts

@@ -110,6 +110,8 @@ interface OpenAPIConfig {
         slug_field: string;
         /** HTTP method for this collection endpoint — defaults to 'GET' */
         method?: string;
+        /** Transport protocol — 'websocket' collections are skipped during prebuild */
+        transport?: string;
         /** Optional filters */
         filters?: Record<string, unknown>;
     }>;
@@ -468,8 +470,13 @@ declare class ActionGenerator {
     private generateActionExports;
     private generateRegistry;
     private generateEmptyFile;
-    /** Derives the client method name from endpoint + method (best-effort) */
+    /** 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;
@@ -521,6 +528,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

package/dist/index.js

@@ -45,8 +45,18 @@ var OpenAPIParser = class {
         await SwaggerParser__default.default.validate(api);
       }
       let document;
+      let dereferenced = false;
       if (dereference) {
-        document = await SwaggerParser__default.default.dereference(api);
+        try {
+          document = await SwaggerParser__default.default.dereference(api);
+          dereferenced = true;
+        } catch {
+          console.warn(
+            `[OpenAPIParser] Warning: Could not fully dereference "${specPath}" (dangling $ref or circular ref). Proceeding without full dereferencing \u2014 some schema references may not resolve.`
+          );
+          document = api;
+          dereferenced = false;
+        }
       } else {
         document = api;
       }
@@ -54,7 +64,7 @@ var OpenAPIParser = class {
       return {
         document,
         version,
-        dereferenced: dereference
+        dereferenced
       };
     } catch (error) {
       throw this.enhanceError(error, specPath);
@@ -150,8 +160,14 @@ var SchemaResolver = class {
       const response = responses[responseCode];
       if (!response) return void 0;
       for (const contentType of SUPPORTED_CONTENT_TYPES) {
-        const content = response.content?.[contentType];
-        if (!content?.schema) continue;
+        const responseContent = response.content;
+        if (!responseContent) continue;
+        const exactContent = responseContent[contentType];
+        const normalizedEntry = exactContent ? void 0 : Object.entries(responseContent).find(
+          ([k]) => k === contentType || k.startsWith(`${contentType};`)
+        );
+        const content = exactContent ?? normalizedEntry?.[1];
+        if (!content || !content.schema) continue;
         const schema = content.schema;
         if ("$ref" in schema) {
           console.warn(
@@ -281,7 +297,7 @@ ${body}`;
     const isNullable = "nullable" in schema && schema.nullable === true;
     let baseSchema = this.schemaTypeToZod(schema);
     if (schema.description) {
-      const escapedDesc = schema.description.replace(/'/g, "\\'");
+      const escapedDesc = schema.description.replace(/'/g, "\\'").replace(/\r?\n/g, " ");
       baseSchema += `.describe('${escapedDesc}')`;
     }
     if (isNullable) {
@@ -419,7 +435,7 @@ ${body}`;
     if (!schema.properties || Object.keys(schema.properties).length === 0) {
       if (schema.additionalProperties) {
         const valueSchema = typeof schema.additionalProperties === "object" ? this.schemaToZod(schema.additionalProperties) : "z.unknown()";
-        return `z.record(${valueSchema})`;
+        return `z.record(z.string(), ${valueSchema})`;
       }
       return "z.object({})";
     }
@@ -616,10 +632,10 @@ var CollectionProviderGenerator = class {
     const authHeader = this.generateAuthHeader(auth);
     const arraySchemaName = `${schemaName.replace(/Schema$/, "")}ArraySchema`;
     const validationSchema = unknownFallback ? "z.unknown()" : isArray ? arraySchemaName : schemaName;
-    const imports = bare ? "" : unknownFallback ? `import type { CollectionProvider, CollectionItem } from '@stackwright/collections';
+    const imports = bare ? "" : unknownFallback ? `import type { CollectionProvider, CollectionEntry, CollectionListOptions, CollectionListResult } from '@stackwright/collections';
 import { z } from 'zod';
 
-` : `import type { CollectionProvider, CollectionItem } from '@stackwright/collections';
+` : `import type { CollectionProvider, CollectionEntry, CollectionListOptions, CollectionListResult } from '@stackwright/collections';
 import { ${isArray ? arraySchemaName : schemaName} } from './schemas';
 
 `;
@@ -638,29 +654,20 @@ export class ${providerName} implements CollectionProvider {
   }
 
   /**
-   * Get collection name
+   * List available collection names.
    */
-  getName(): string {
-    return '${collectionName}';
+  async collections(): Promise<string[]> {
+    return ['${collectionName}'];
   }
 
   /**
    * List all items in the collection
    */
-  async list(options?: {
-    limit?: number;
-    offset?: number;
-    filters?: Record<string, unknown>;
-  }): Promise<CollectionItem[]> {
+  async list(_collection: string, opts?: CollectionListOptions): Promise<CollectionListResult> {
     const url = new URL(\`\${this.baseUrl}${endpoint}\`);
 
-    // Add pagination/filter params if supported
-    if (options?.limit) {
-      url.searchParams.set('limit', String(options.limit));
-    }
-    if (options?.offset) {
-      url.searchParams.set('offset', String(options.offset));
-    }
+    if (opts?.limit) url.searchParams.set('limit', String(opts.limit));
+    if (opts?.offset) url.searchParams.set('offset', String(opts.offset));
 
     const response = await fetch(url.toString(), {
       method: '${method.toUpperCase()}',
@@ -676,29 +683,24 @@ export class ${providerName} implements CollectionProvider {
     // Validate response with Zod schema
     const validated = ${validationSchema}.parse(data);
     
-    // Convert to CollectionItem format
-    return ${isArray ? "validated" : "[validated]"}.map((item: any) => this.toCollectionItem(item));
+    const entries = ${isArray ? "validated" : "[validated]"}.map((item: any) => this.toCollectionEntry(item));
+    return { entries, total: entries.length };
   }
 
   /**
    * Get a single item by slug
    */
-  async get(slug: string): Promise<CollectionItem | null> {
+  async get(_collection: string, slug: string): Promise<CollectionEntry | null> {
     ${this.generateGetMethod(endpoint, slugField, isArray, collectionName, schemaName, unknownFallback)}
   }
 
   /**
-   * Convert API response to CollectionItem
+   * Convert API response to CollectionEntry
    */
-  private toCollectionItem(item: any): CollectionItem {
+  private toCollectionEntry(item: any): CollectionEntry {
     return {
       slug: String(item.${slugField}),
-      title: item.${this.guessTitle(slugField)},
-      data: item,
-      metadata: {
-        source: '${collectionName}',
-        _raw: item,
-      },
+      ...item,
     };
   }
 
@@ -741,10 +743,10 @@ export class ${providerName} implements CollectionProvider {
     const data = await response.json();
     const validated = ${validationExpr}.parse(data);
     
-    return this.toCollectionItem(validated);`;
+    return this.toCollectionEntry(validated);`;
     } else {
-      return `const items = await this.list();
-    return items.find((item) => item.slug === slug) || null;`;
+      return `const result = await this.list(_collection);
+    return result.entries.find((item) => item.slug === slug) ?? null;`;
     }
   }
   /**
@@ -992,13 +994,25 @@ import type { CollectionActionRegistry } from '@stackwright-pro/workflow';
 export const actions: CollectionActionRegistry = {};
 `;
   }
-  /** Derives the client method name from endpoint + method (best-effort) */
+  /** Derives the client method name from endpoint + method.
+   *  Prefers operationId (matching ClientGenerator.getMethodName()), falls back
+   *  to path+method derivation for specs that omit operationIds. */
   endpointToClientMethod(endpoint, method) {
+    const pathItem = this.document.paths?.[endpoint];
+    const operation = pathItem?.[method.toLowerCase()];
+    if (operation?.operationId) {
+      return this.camelCase(operation.operationId);
+    }
     const parts = endpoint.split("/").filter(Boolean).filter((p) => !p.startsWith("{")).map((p) => p.replace(/-/g, "_"));
     const prefix = method.toLowerCase();
     const suffix = parts.map((p) => this.capitalize(p)).join("");
     return `${prefix}${suffix}`;
   }
+  /** Convert any string to camelCase — handles operationId values like
+   *  createOrder, list_items, get-by-id, etc. */
+  camelCase(str) {
+    return str.replace(/[^a-zA-Z0-9]+(.)/g, (_, chr) => chr.toUpperCase()).replace(/^[A-Z]/, (chr) => chr.toLowerCase());
+  }
   toCamelCase(str) {
     const parts = str.split(/[-_]/);
     return parts.map((p, i) => i === 0 ? p.toLowerCase() : this.capitalize(p)).join("");
@@ -1019,11 +1033,13 @@ var ClientGenerator = class {
     }
     this.requiredSchemas = /* @__PURE__ */ new Set();
     this.generatedRequestSchemas = /* @__PURE__ */ new Set();
+    this.generatedRequestTypes = /* @__PURE__ */ new Set();
   }
   resolver;
   schemaMapping;
   requiredSchemas;
   generatedRequestSchemas;
+  generatedRequestTypes;
   /**
    * Generate typed API client code from OpenAPI document
    */
@@ -1042,12 +1058,11 @@ var ClientGenerator = class {
     }
     this.requiredSchemas.clear();
     this.generatedRequestSchemas.clear();
+    this.generatedRequestTypes.clear();
     let code = this.generateImports(!!schemaMapping, validateResponses);
     code += "\n";
-    if (schemaMapping) {
-      code += this.generateRequestSchemas(endpoints);
-      code += "\n";
-    }
+    code += this.generateRequestSchemas(endpoints);
+    code += "\n";
     code += this.generateTypes(endpoints, schemaMapping);
     code += "\n";
     code += this.generateErrorClasses();
@@ -1078,9 +1093,9 @@ var ClientGenerator = class {
  */
 
 `;
-    if (useSchemas && validateResponses) {
-      code += `import { z } from 'zod';
+    code += `import { z } from 'zod';
 `;
+    if (useSchemas && validateResponses) {
       code += `import * as schemas from './schemas';
 `;
     }
@@ -1113,6 +1128,9 @@ var ClientGenerator = class {
       const schemaName = `${typeName}RequestSchema`;
       const schemaCode = this.generateRequestSchemaForEndpoint(endpoint);
       if (schemaCode) {
+        if (this.generatedRequestSchemas.has(schemaName)) {
+          continue;
+        }
         code += `export const ${schemaName} = ${schemaCode};
 
 `;
@@ -1164,7 +1182,8 @@ ${parts.join(",\n")}
     for (const param of params) {
       const zodSchema = this.parameterSchemaToZod(param);
       const desc = param.description ? `.describe('${this.escapeString(param.description)}')` : "";
-      paramSchemas.push(`    ${param.name}: ${zodSchema}${desc}`);
+      const safeParamKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(param.name) ? param.name : `'${param.name}'`;
+      paramSchemas.push(`    ${safeParamKey}: ${zodSchema}${desc}`);
     }
     return `z.object({
 ${paramSchemas.join(",\n")}
@@ -1183,7 +1202,8 @@ ${paramSchemas.join(",\n")}
       if (!param.required) {
         zodSchema += ".optional()";
       }
-      paramSchemas.push(`    ${param.name}: ${zodSchema}`);
+      const safeParamKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(param.name) ? param.name : `'${param.name}'`;
+      paramSchemas.push(`    ${safeParamKey}: ${zodSchema}`);
     }
     return `z.object({
 ${paramSchemas.join(",\n")}
@@ -1256,7 +1276,7 @@ ${paramSchemas.join(",\n")}
     }
     if (schema.type === "object") {
       if (!schema.properties) {
-        return "z.record(z.unknown())";
+        return "z.record(z.string(), z.unknown())";
       }
       const props = [];
       const required = schema.required || [];
@@ -1266,7 +1286,8 @@ ${paramSchemas.join(",\n")}
         if (!isRequired) {
           propZod += ".optional()";
         }
-        props.push(`${key}: ${propZod}`);
+        const safeKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : `'${key}'`;
+        props.push(`${safeKey}: ${propZod}`);
       }
       return `z.object({ ${props.join(", ")} })`;
     }
@@ -1424,13 +1445,24 @@ ${paramSchemas.join(",\n")}
       const operationId = endpoint.operationId || this.getMethodName(endpoint);
       const mapping = schemaMapping[operationId];
       if (!mapping) {
+        const typeName2 = this.getOperationTypeName(endpoint);
+        const requestSchemaName2 = `${typeName2}RequestSchema`;
+        if (this.generatedRequestSchemas.has(requestSchemaName2) && !this.generatedRequestTypes.has(requestSchemaName2)) {
+          code += `export type ${typeName2}Request = z.infer<typeof ${requestSchemaName2}>;
+`;
+          this.generatedRequestTypes.add(requestSchemaName2);
+        }
+        code += `export type ${typeName2}Response = unknown;
+
+`;
         continue;
       }
       const typeName = this.getOperationTypeName(endpoint);
       const requestSchemaName = mapping.requestSchema || typeName + "RequestSchema";
-      if (this.generatedRequestSchemas.has(requestSchemaName)) {
+      if (this.generatedRequestSchemas.has(requestSchemaName) && !this.generatedRequestTypes.has(requestSchemaName)) {
         this.addRequiredSchema(requestSchemaName);
         code += "export type " + typeName + "Request = z.infer<typeof " + requestSchemaName + ">;\n";
+        this.generatedRequestTypes.add(requestSchemaName);
       }
       this.addRequiredSchema(mapping.responseSchema);
       code += `export type ${typeName}Response = z.infer<typeof schemas.${mapping.responseSchema}>;
@@ -1475,8 +1507,9 @@ ${paramSchemas.join(",\n")}
         const type = this.getTypeFromSchemaLegacy(param.schema);
         const desc = param.description ? `    /** ${param.description} */
 ` : "";
+        const safeParamKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(param.name) ? param.name : `'${param.name}'`;
         code += desc;
-        code += `    ${param.name}${required}: ${type};
+        code += `    ${safeParamKey}${required}: ${type};
 `;
       }
       code += "  };\n";
@@ -1489,8 +1522,9 @@ ${paramSchemas.join(",\n")}
         const type = this.getTypeFromSchemaLegacy(param.schema);
         const desc = param.description ? `    /** ${param.description} */
 ` : "";
+        const safeParamKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(param.name) ? param.name : `'${param.name}'`;
         code += desc;
-        code += `    ${param.name}${required}: ${type};
+        code += `    ${safeParamKey}${required}: ${type};
 `;
       }
       code += "  };\n";
@@ -1503,8 +1537,9 @@ ${paramSchemas.join(",\n")}
         const type = this.getTypeFromSchemaLegacy(param.schema);
         const desc = param.description ? `    /** ${param.description} */
 ` : "";
+        const safeParamKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(param.name) ? param.name : `'${param.name}'`;
         code += desc;
-        code += `    ${param.name}${required}: ${type};
+        code += `    ${safeParamKey}${required}: ${type};
 `;
       }
       code += "  };\n";
@@ -1851,9 +1886,10 @@ ${paramSchemas.join(",\n")}
       code += `    if (request.query) {
 `;
       for (const param of queryParams) {
-        code += `      if (request.query.${param.name} != null) {
+        const safeAccess = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(param.name) ? `.${param.name}` : `['${param.name}']`;
+        code += `      if (request.query${safeAccess} != null) {
 `;
-        code += `        searchParams.append('${param.name}', String(request.query.${param.name}));
+        code += `        searchParams.append('${param.name}', String(request.query${safeAccess}));
 `;
         code += `      }
 `;
@@ -1877,7 +1913,7 @@ ${paramSchemas.join(",\n")}
     code += `      method: '${method.toUpperCase()}',
 `;
     if (hasBody) {
-      code += `      body: request.body ? JSON.stringify(request.body) : null,
+      code += `      body: request.body ? JSON.stringify(request.body) : undefined,
 `;
     }
     if (headerParams.length > 0) {
@@ -1994,9 +2030,10 @@ ${paramSchemas.join(",\n")}
       code += `    if (request.query) {
 `;
       for (const param of queryParams) {
-        code += `      if (request.query.${param.name} != null) {
+        const safeAccess = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(param.name) ? `.${param.name}` : `['${param.name}']`;
+        code += `      if (request.query${safeAccess} != null) {
 `;
-        code += `        searchParams.append('${param.name}', String(request.query.${param.name}));
+        code += `        searchParams.append('${param.name}', String(request.query${safeAccess}));
 `;
         code += `      }
 `;
@@ -2018,7 +2055,7 @@ ${paramSchemas.join(",\n")}
     code += `      method: '${method.toUpperCase()}',
 `;
     if (hasBody) {
-      code += `      body: request.body ? JSON.stringify(request.body) : null,
+      code += `      body: request.body ? JSON.stringify(request.body) : undefined,
 `;
     }
     const headerParams = params.filter((p) => p.in === "header");
@@ -2184,7 +2221,7 @@ ${paramSchemas.join(",\n")}
     if (endpoint.operationId) {
       return this.camelCase(endpoint.operationId);
     }
-    const pathParts = endpoint.path.split("/").filter((p) => p && !p.startsWith("{")).join("-");
+    const pathParts = endpoint.path.split("/").filter((p) => p).map((p) => p.startsWith("{") && p.endsWith("}") ? p.slice(1, -1) : p).join("-");
     return this.camelCase(`${endpoint.method}-${pathParts}`);
   }
   /**
@@ -2841,6 +2878,23 @@ var OpenAPIPlugin = class {
   async processIntegration(config, projectRoot) {
     const { name, spec, auth, mockUrl, collections, endpoints, actions } = config;
     console.log(`  - Processing integration: ${name}`);
+    const httpCollections = (collections || []).filter((c) => {
+      if (c.transport === "websocket") {
+        console.warn(
+          `    > Skipping collection "${c.endpoint}" (transport: websocket \u2014 not yet supported)`
+        );
+        return false;
+      }
+      return true;
+    });
+    const hasEndpoints = endpoints && (endpoints.include?.length || endpoints.exclude?.length);
+    const hasActions = actions && actions.length > 0;
+    if (httpCollections.length === 0 && !hasEndpoints && !hasActions) {
+      console.log(
+        "    > No HTTP endpoints or REST collections found \u2014 skipping (WebSocket-only integration not yet supported)"
+      );
+      return;
+    }
     const specPath = spec.startsWith("http") ? spec : path2__default.default.resolve(projectRoot, spec);
     const parser = new OpenAPIParser();
     const { document } = await parser.parse(specPath);
@@ -2859,13 +2913,13 @@ var OpenAPIPlugin = class {
     fs2__default.default.mkdirSync(outputDir, { recursive: true });
     const schemaMapping = await this.generateSchemas(
       document,
-      collections || [],
+      httpCollections,
       outputDir,
       name,
       endpointFilter
     );
-    await this.generateTypes(document, collections || [], outputDir, name);
-    if (collections && collections.length > 0) {
+    await this.generateTypes(document, httpCollections, outputDir, name);
+    if (httpCollections.length > 0) {
       await this.generateProvider(document, config, outputDir, name);
     }
     await this.generateClient(document, outputDir, name, schemaMapping, endpointFilter);
@@ -2973,6 +3027,7 @@ import { z } from 'zod';
         if (!operation) continue;
         const opId = operation.operationId || this.generateOperationId(pathStr, method);
         const responseSchemaName = `${this.getOperationTypeName(opId)}ResponseSchema`;
+        if (!generatedSchemas.has(responseSchemaName)) continue;
         schemaMapping[opId] = {
           requestSchema: null,
           // ClientGenerator handles request schema generation + type inference
@@ -2997,7 +3052,13 @@ import type * as schemas from './schemas';
 
 `;
     if (collections) {
+      const resolver = new SchemaResolver(document);
       for (const collection of collections) {
+        const schema = resolver.getResponseSchema(
+          collection.endpoint,
+          collection.method?.toLowerCase() ?? "get"
+        );
+        if (!schema) continue;
         const collectionName = this.sanitizeName(collection.endpoint);
         const typeName = this.capitalize(collectionName);
         const schemaName = `${typeName}Schema`;
@@ -3043,13 +3104,20 @@ import type * as schemas from './schemas';
         collection.endpoint,
         collection.method?.toLowerCase() ?? "get"
       );
-      const isArray = schema?.type === "array";
-      if (isArray) {
-        schemaImports.add(`${this.capitalize(collectionName)}ArraySchema`);
-      } else {
-        schemaImports.add(`${this.capitalize(collectionName)}Schema`);
+      if (schema) {
+        const isArray = schema.type === "array";
+        if (isArray) {
+          schemaImports.add(`${this.capitalize(collectionName)}ArraySchema`);
+        } else {
+          schemaImports.add(`${this.capitalize(collectionName)}Schema`);
+        }
       }
     }
+    const needsZodImport = classBlocks.some((block) => block.includes("z.unknown()"));
+    const zodImportLine = needsZodImport ? `import { z } from 'zod';
+` : "";
+    const schemaImportLine = schemaImports.size > 0 ? `import { ${Array.from(schemaImports).join(", ")} } from './schemas';
+` : "";
     let providerCode = `/**
  * Generated CollectionProvider from OpenAPI spec
  * Integration: ${integrationName}
@@ -3058,9 +3126,8 @@ import type * as schemas from './schemas';
  * Regenerate by running: pnpm prebuild
  */
 
-import type { CollectionProvider, CollectionItem } from '@stackwright/collections';
-import { ${Array.from(schemaImports).join(", ")} } from './schemas';
-
+import type { CollectionProvider, CollectionEntry, CollectionListOptions, CollectionListResult } from '@stackwright/collections';
+${zodImportLine}${schemaImportLine}
 `;
     providerCode += classBlocks.join("\n");
     fs2__default.default.writeFileSync(path2__default.default.join(outputDir, "provider.ts"), providerCode);