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

package/dist/index.mjs

@@ -33,8 +33,18 @@ var OpenAPIParser = class {
         await SwaggerParser.validate(api);
       }
       let document;
+      let dereferenced = false;
       if (dereference) {
-        document = await SwaggerParser.dereference(api);
+        try {
+          document = await SwaggerParser.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;
       }
@@ -42,7 +52,7 @@ var OpenAPIParser = class {
       return {
         document,
         version,
-        dereferenced: dereference
+        dereferenced
       };
     } catch (error) {
       throw this.enhanceError(error, specPath);
@@ -138,8 +148,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(
@@ -269,7 +285,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) {
@@ -407,7 +423,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({})";
     }
@@ -604,10 +620,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';
 
 `;
@@ -626,29 +642,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()}',
@@ -664,29 +671,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,
     };
   }
 
@@ -729,10 +731,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;`;
     }
   }
   /**
@@ -980,13 +982,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("");
@@ -1007,11 +1021,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
    */
@@ -1030,12 +1046,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();
@@ -1066,9 +1081,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';
 `;
     }
@@ -1101,6 +1116,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};
 
 `;
@@ -1152,7 +1170,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")}
@@ -1171,7 +1190,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")}
@@ -1244,7 +1264,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 || [];
@@ -1254,7 +1274,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(", ")} })`;
     }
@@ -1412,13 +1433,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}>;
@@ -1463,8 +1495,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";
@@ -1477,8 +1510,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";
@@ -1491,8 +1525,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";
@@ -1839,9 +1874,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 += `      }
 `;
@@ -1865,7 +1901,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) {
@@ -1982,9 +2018,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 += `      }
 `;
@@ -2006,7 +2043,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");
@@ -2172,7 +2209,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}`);
   }
   /**
@@ -2829,6 +2866,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.resolve(projectRoot, spec);
     const parser = new OpenAPIParser();
     const { document } = await parser.parse(specPath);
@@ -2847,13 +2901,13 @@ var OpenAPIPlugin = class {
     fs2.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);
@@ -2961,6 +3015,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
@@ -2985,7 +3040,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`;
@@ -3031,13 +3092,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}
@@ -3046,9 +3114,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.writeFileSync(path2.join(outputDir, "provider.ts"), providerCode);