@stackql/provider-utils 0.4.1 → 0.4.2

package/README.md

@@ -1,6 +1,7 @@
 # StackQL Provider Utils
 
-![NPM Version](https://img.shields.io/npm/v/%40stackql%2Fprovider-utils) | ![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/stackql/stackql/total?style=plastic&label=stackql%20downloads)
+![NPM Version](https://img.shields.io/npm/v/%40stackql%2Fprovider-utils)
+![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/stackql/stackql/total?style=plastic&label=stackql%20downloads)
 
 A comprehensive toolkit for transforming OpenAPI specifications into StackQL providers. This library streamlines the process of parsing, mapping, validating, testing, and generating documentation for StackQL providers.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackql/provider-utils",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Utilities for building StackQL providers from OpenAPI specifications.",
   "type": "module",
   "main": "./src/index.js",

package/src/docgen/resource/methods.js

@@ -4,6 +4,24 @@ import {
     sanitizeHtml
 } from '../helpers.js';
 
+const getRequiredBodyParams = (methodDetails, accessType) => {
+    // Only process request body for insert, update, replace, and exec
+    if (!['insert', 'update', 'replace', 'exec'].includes(accessType)) {
+        return [];
+    }
+    
+    // Get required body params if they exist
+    const requiredBodyProps = methodDetails.requestBody?.required ? methodDetails.requestBody.required : [];
+    
+    // For insert, update, and replace, prefix with data__
+    if (['insert', 'update', 'replace'].includes(accessType)) {
+        return requiredBodyProps.map(prop => `data__${prop}`);
+    } else {
+        // For exec, don't prefix
+        return requiredBodyProps;
+    }
+};
+
 export function createMethodsSection(resourceData, dereferencedAPI) {
     
     let content = `\n## Methods\n\n`;
@@ -37,10 +55,16 @@ export function createMethodsSection(resourceData, dereferencedAPI) {
         for (const [methodName, methodDetails] of Object.entries(methods)) {
             console.info(`Adding ${accessType} method to table: ${methodName}`);
             
+            // Get required params from both the standard params and the request body
+            const reqParamsArr = Object.keys(methodDetails.requiredParams || {});
+            const reqBodyParamsArr = getRequiredBodyParams(methodDetails, accessType);
+            
+            // Combine both types of required parameters
+            const allReqParamsArr = [...reqParamsArr, ...reqBodyParamsArr];
+            
             // Format required params as comma-delimited list with hyperlinks
-            const requiredParamsArr = Object.keys(methodDetails.requiredParams || {});
-            const requiredParamsStr = requiredParamsArr.length > 0 
-                ? requiredParamsArr.map(param => `<a href="#parameter-${param}"><code>${param}</code></a>`).join(', ') 
+            const requiredParamsStr = allReqParamsArr.length > 0 
+                ? allReqParamsArr.map(param => `<a href="#parameter-${param}"><code>${param}</code></a>`).join(', ') 
                 : '';
             
             // Format optional params as comma-delimited list with hyperlinks
@@ -48,7 +72,7 @@ export function createMethodsSection(resourceData, dereferencedAPI) {
             const optionalParamsStr = optionalParamsArr.length > 0 
                 ? optionalParamsArr.map(param => `<a href="#parameter-${param}"><code>${param}</code></a>`).join(', ') 
                 : '';
-            
+
             // Add the method row to the table
             content += `
 <tr>

package/src/providerdev/analyze.js

@@ -95,6 +95,23 @@ function findExistingMapping(spec, pathRef) {
   };
 }
 
+/**
+ * Escape and sanitize a CSV field value
+ * @param {string} value - Field value to escape
+ * @returns {string} - Escaped value
+ */
+function escapeCsvField(value) {
+  if (!value) return '';
+  
+  // If the value contains commas, double quotes, or newlines, wrap it in quotes
+  // and escape any existing double quotes by doubling them
+  if (value.includes(',') || value.includes('"') || value.includes('\n')) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  
+  return value;
+}
+
 /**
  * Analyze OpenAPI specs and generate mapping CSV
  * @param {Object} options - Options for analysis
@@ -159,7 +176,7 @@ export async function analyze(options) {
 
     // Only write header if creating a new file
     if (!fileExists) {
-      writer.write('filename,path,operationId,formatted_op_id,verb,response_object,tags,formatted_tags,stackql_resource_name,stackql_method_name,stackql_verb\n');
+      writer.write('filename,path,operationId,formatted_op_id,verb,response_object,tags,formatted_tags,stackql_resource_name,stackql_method_name,stackql_verb,op_description\n');
     }
     
     const files = fs.readdirSync(inputDir);
@@ -216,15 +233,27 @@ export async function analyze(options) {
           // Find existing mapping if available
           const { resourceName, methodName, sqlVerb } = findExistingMapping(spec, pathRef);
           
-          // Escape commas in fields
-          const escapedPath = pathKey.includes(',') ? `"${pathKey}"` : pathKey;
-          const escapedOperationId = operationId.includes(',') ? `"${operationId}"` : operationId;
-          const escapedFormattedOpId = formattedOpId.includes(',') ? `"${formattedOpId}"` : formattedOpId;
-          const escapedTags = tagsStr.includes(',') ? `"${tagsStr}"` : tagsStr;
-          const escapedFormattedTags = formattedTags.includes(',') ? `"${formattedTags}"` : formattedTags;
+          // Get operation description
+          const opDescription = operation.summary || operation.description || '';
+          
+          // Escape fields that might contain commas, quotes, or other special characters
+          const escapedFields = {
+            filename: escapeCsvField(filename),
+            path: escapeCsvField(pathKey),
+            operationId: escapeCsvField(operationId),
+            formattedOpId: escapeCsvField(formattedOpId),
+            verb: escapeCsvField(verb),
+            responseRef: escapeCsvField(responseRef),
+            tagsStr: escapeCsvField(tagsStr),
+            formattedTags: escapeCsvField(formattedTags),
+            resourceName: escapeCsvField(resourceName),
+            methodName: escapeCsvField(methodName),
+            sqlVerb: escapeCsvField(sqlVerb),
+            opDescription: escapeCsvField(opDescription)
+          };
           
           // Write row
-          writer.write(`${filename},${escapedPath},${escapedOperationId},${escapedFormattedOpId},${verb},${responseRef},${escapedTags},${escapedFormattedTags},${resourceName},${methodName},${sqlVerb}\n`);
+          writer.write(`${escapedFields.filename},${escapedFields.path},${escapedFields.operationId},${escapedFields.formattedOpId},${escapedFields.verb},${escapedFields.responseRef},${escapedFields.tagsStr},${escapedFields.formattedTags},${escapedFields.resourceName},${escapedFields.methodName},${escapedFields.sqlVerb},${escapedFields.opDescription}\n`);
         }
       }
     }

package/src/providerdev/split.js

@@ -11,7 +11,6 @@ import {
 
 // Constants
 const OPERATIONS = ["get", "post", "put", "delete", "patch", "options", "head", "trace"];
-const NON_OPERATIONS = ["parameters", "servers", "summary", "description"];
 const COMPONENTS_CHILDREN = ["schemas", "responses", "parameters", "examples", "requestBodies", "headers", "securitySchemes", "links", "callbacks"];
 
 /**
@@ -42,9 +41,10 @@ function isOperationExcluded(exclude, opItem) {
  * @param {string} svcDiscriminator - Service discriminator
  * @param {Object[]} allTags - All tags from API doc
  * @param {boolean} debug - Debug flag
+ * @param {Object} svcNameOverrides - Service name overrides
  * @returns {[string, string]} - [service name, service description]
  */
-function retServiceNameAndDesc(providerName, opItem, pathKey, svcDiscriminator, allTags, debug) {
+function retServiceNameAndDesc(providerName, opItem, pathKey, svcDiscriminator, allTags, debug, svcNameOverrides) {
   let service = "default";
   let serviceDesc = `${providerName} API`;
   
@@ -84,9 +84,25 @@ function retServiceNameAndDesc(providerName, opItem, pathKey, svcDiscriminator,
     return ["skip", ""];
   }
   
+  // Apply service name overrides if present
+  if (svcNameOverrides && svcNameOverrides[service]) {
+    const newName = svcNameOverrides[service];
+    if (debug) {
+      logger.debug(`Overriding service name: ${service} -> ${newName}`);
+    }
+    
+    // Update service description for path-based services
+    if (svcDiscriminator === "path") {
+      serviceDesc = `${providerName} ${newName} API`;
+    }
+    
+    service = newName;
+  }
+  
   return [service, serviceDesc];
 }
 
+
 /**
  * Initialize service map
  * @param {Object} services - Services map
@@ -192,43 +208,6 @@ function getPathLevelRefs(pathItem) {
   return refs;
 }
 
-/**
- * Add referenced components to service
- * @param {Set<string>} refs - Set of refs
- * @param {Object} service - Service object
- * @param {Object} components - Components from API doc
- * @param {boolean} debug - Debug flag
- */
-function addRefsToComponents(refs, service, components, debug) {
-  for (const ref of refs) {
-    const parts = ref.split('/');
-    
-    // Only process refs that point to components
-    if (parts.length >= 4 && parts[1] === "components") {
-      const componentType = parts[2];
-      const componentName = parts[3];
-      
-      // Check if component type exists in service
-      if (!service.components[componentType]) {
-        service.components[componentType] = {};
-      }
-      
-      // Skip if component already added
-      if (service.components[componentType][componentName]) {
-        continue;
-      }
-      
-      // Add component if it exists in source document
-      if (components[componentType] && components[componentType][componentName]) {
-        service.components[componentType][componentName] = components[componentType][componentName];
-        if (debug) {
-          logger.debug(`Added component ${componentType}/${componentName}`);
-        }
-      }
-    }
-  }
-}
-
 /**
  * Add missing type: object to schema objects
  * @param {any} obj - Object to process
@@ -338,7 +317,8 @@ export async function split(options) {
     svcDiscriminator = "tag",
     exclude = null,
     overwrite = true,
-    verbose = false
+    verbose = false,
+    svcNameOverrides = {}  // Add this new parameter with default empty object
   } = options;
   
   // Setup logging based on verbosity
@@ -351,6 +331,13 @@ export async function split(options) {
   logger.info(`Output: ${outputDir}`);
   logger.info(`Service Discriminator: ${svcDiscriminator}`);
   
+  if (Object.keys(svcNameOverrides).length > 0) {
+    logger.info(`Using ${Object.keys(svcNameOverrides).length} service name overrides`);
+    if (verbose) {
+      logger.debug(`Service name overrides: ${JSON.stringify(svcNameOverrides, null, 2)}`);
+    }
+  }
+  
   // Process exclude list
   const excludeList = exclude ? exclude.split(",") : [];
   
@@ -409,12 +396,11 @@ export async function split(options) {
         continue;
       }
       
-      // Determine service name
       const [service, serviceDesc] = retServiceNameAndDesc(
         providerName, opItem, pathKey, svcDiscriminator, 
-        apiDocObj.tags || [], verbose
-      );
-      
+        apiDocObj.tags || [], verbose, svcNameOverrides
+      );      
+
       // Skip if service is marked to skip
       if (service === 'skip') {
         logger.warn(`⭐️ Skipping service: ${service}`);