@hustle-together/api-dev-tools 3.12.2 → 3.12.10

package/hooks/update-api-showcase.py

@@ -27,12 +27,15 @@ def copy_showcase_templates(cwd):
     """Copy API showcase templates to src/app/api-showcase/."""
     # Source templates (installed by CLI)
     templates_dir = Path(__file__).parent.parent / "templates" / "api-showcase"
+    shared_templates_dir = Path(__file__).parent.parent / "templates" / "shared"
 
     # Destination
     showcase_dir = cwd / "src" / "app" / "api-showcase"
+    shared_dir = cwd / "src" / "app" / "shared"
 
-    # Create directory if needed
+    # Create directories if needed
     showcase_dir.mkdir(parents=True, exist_ok=True)
+    shared_dir.mkdir(parents=True, exist_ok=True)
 
     # Copy template files
     templates_to_copy = [
@@ -55,6 +58,15 @@ def copy_showcase_templates(cwd):
             shutil.copy2(src_path, dest_path)
             created_files.append(str(dest_path.relative_to(cwd)))
 
+    # Also copy shared components (HeroHeader, etc.)
+    if shared_templates_dir.exists():
+        for src_file in shared_templates_dir.iterdir():
+            if src_file.is_file():
+                dest_path = shared_dir / src_file.name
+                if not dest_path.exists():
+                    shutil.copy2(src_file, dest_path)
+                    created_files.append(str(dest_path.relative_to(cwd)))
+
     return created_files
 
 

package/hooks/update-ui-showcase.py

@@ -84,12 +84,15 @@ def copy_showcase_templates(cwd):
     """Copy UI showcase templates to src/app/ui-showcase/."""
     # Source templates (installed by CLI)
     templates_dir = Path(__file__).parent.parent / "templates" / "ui-showcase"
+    shared_templates_dir = Path(__file__).parent.parent / "templates" / "shared"
 
     # Destination
     showcase_dir = cwd / "src" / "app" / "ui-showcase"
+    shared_dir = cwd / "src" / "app" / "shared"
 
-    # Create directory if needed
+    # Create directories if needed
     showcase_dir.mkdir(parents=True, exist_ok=True)
+    shared_dir.mkdir(parents=True, exist_ok=True)
 
     # Copy template files
     templates_to_copy = [
@@ -111,6 +114,15 @@ def copy_showcase_templates(cwd):
             shutil.copy2(src_path, dest_path)
             created_files.append(str(dest_path.relative_to(cwd)))
 
+    # Also copy shared components (HeroHeader, etc.)
+    if shared_templates_dir.exists():
+        for src_file in shared_templates_dir.iterdir():
+            if src_file.is_file():
+                dest_path = shared_dir / src_file.name
+                if not dest_path.exists():
+                    shutil.copy2(src_file, dest_path)
+                    created_files.append(str(dest_path.relative_to(cwd)))
+
     return created_files
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hustle-together/api-dev-tools",
-  "version": "3.12.2",
+  "version": "3.12.10",
   "description": "Interview-driven, research-first API development toolkit with 14-phase TDD workflow, enforcement hooks, and 23 Agent Skills for cross-platform AI agents",
   "main": "bin/cli.js",
   "bin": {
@@ -23,11 +23,15 @@
     "test": "node bin/cli.js --scope=project",
     "usage": "ccusage",
     "format": "prettier --write .",
-    "lint": "eslint . --fix"
+    "lint": "eslint . --fix",
+    "typedoc": "typedoc",
+    "typedoc:watch": "typedoc --watch"
   },
   "devDependencies": {
     "prettier": "^3.0.0",
-    "eslint": "^8.0.0"
+    "eslint": "^8.0.0",
+    "typedoc": "^0.27.0",
+    "typedoc-plugin-markdown": "^4.4.0"
   },
   "optionalDependencies": {
     "ccusage": "^1.0.0"

package/scripts/extract-schema-docs.cjs

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+/**
+ * Extract Schema Documentation
+ *
+ * Parses Zod schema files and extracts parameter documentation
+ * for use in the API Showcase registry.
+ *
+ * Usage:
+ *   node scripts/extract-schema-docs.cjs <schema-file-path>
+ *
+ * Output: JSON with parameter documentation
+ *
+ * Example:
+ *   node scripts/extract-schema-docs.cjs src/lib/schemas/unsplash.ts
+ *
+ * Created with Hustle API Dev Tools (v3.12.10)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Parse Zod schema file and extract documentation
+ * Uses regex-based parsing since we can't import TypeScript directly
+ */
+function parseZodSchema(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+
+  const result = {
+    file: filePath,
+    actions: [],
+    schemas: {},
+    enums: {},
+    constants: {}
+  };
+
+  // Extract action enum values
+  const actionMatch = content.match(/ActionSchema\s*=\s*z\.enum\(\[([^\]]+)\]\)/);
+  if (actionMatch) {
+    result.actions = actionMatch[1]
+      .split(',')
+      .map(s => s.trim().replace(/['"]/g, ''))
+      .filter(Boolean);
+  }
+
+  // Extract all enums
+  const enumRegex = /export const (\w+Schema)\s*=\s*z\.enum\(\[([^\]]+)\]\)/g;
+  let enumMatch;
+  while ((enumMatch = enumRegex.exec(content)) !== null) {
+    const name = enumMatch[1].replace('Schema', '');
+    const values = enumMatch[2]
+      .split(',')
+      .map(s => s.trim().replace(/['"]/g, ''))
+      .filter(Boolean);
+    result.enums[name] = values;
+  }
+
+  // Extract request schemas (z.object definitions)
+  const schemaRegex = /export const (\w+RequestSchema)\s*=\s*z\s*\.?\s*object\(\{([^}]+(?:\{[^}]*\}[^}]*)*)\}\)/gs;
+  let schemaMatch;
+
+  while ((schemaMatch = schemaRegex.exec(content)) !== null) {
+    const schemaName = schemaMatch[1];
+    const schemaBody = schemaMatch[2];
+    const params = parseSchemaParams(schemaBody, result.enums);
+
+    // Get action name from schema name (e.g., SearchRequestSchema -> search)
+    const actionName = schemaName
+      .replace('RequestSchema', '')
+      .replace(/([A-Z])/g, (m, p1, offset) => offset > 0 ? '_' + p1.toLowerCase() : p1.toLowerCase())
+      .replace(/^_/, '');
+
+    result.schemas[actionName] = {
+      name: schemaName,
+      params: params
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Parse individual parameters from schema body
+ */
+function parseSchemaParams(schemaBody, enums) {
+  const params = [];
+
+  // Split by lines and process each field
+  const lines = schemaBody.split('\n');
+
+  for (const line of lines) {
+    // Match field definitions like: fieldName: z.string().min(1)...
+    const fieldMatch = line.match(/^\s*(\w+)\s*:\s*z\.(.+)/);
+    if (!fieldMatch) continue;
+
+    const [, name, definition] = fieldMatch;
+    const param = {
+      name,
+      type: 'string',
+      required: true,
+      description: '',
+      default: null,
+      enum: null
+    };
+
+    // Determine type
+    if (definition.includes('string()') || definition.includes('literal(')) {
+      param.type = 'string';
+    } else if (definition.includes('number()') || definition.includes('coerce.number()')) {
+      param.type = 'number';
+    } else if (definition.includes('boolean()') || definition.includes('coerce.boolean()')) {
+      param.type = 'boolean';
+    } else if (definition.includes('array(')) {
+      param.type = 'array';
+    }
+
+    // Check if it references an enum
+    for (const [enumName, enumValues] of Object.entries(enums)) {
+      if (definition.includes(enumName + 'Schema')) {
+        param.type = 'enum';
+        param.enum = enumValues;
+        break;
+      }
+    }
+
+    // Check if optional
+    if (definition.includes('.optional()')) {
+      param.required = false;
+    }
+
+    // Extract default value
+    const defaultMatch = definition.match(/\.default\(([^)]+)\)/);
+    if (defaultMatch) {
+      let defaultVal = defaultMatch[1].trim();
+      // Parse the default value
+      if (defaultVal === 'true') param.default = true;
+      else if (defaultVal === 'false') param.default = false;
+      else if (/^\d+$/.test(defaultVal)) param.default = parseInt(defaultVal);
+      else param.default = defaultVal.replace(/['"]/g, '');
+      param.required = false;
+    }
+
+    // Extract description from validation messages
+    const descMatch = definition.match(/['"]([^'"]+is required|[^'"]+too long|[^'"]+invalid)['"]/i);
+    if (descMatch) {
+      param.description = descMatch[1];
+    }
+
+    // Extract min/max for numbers
+    const minMatch = definition.match(/\.min\((\d+)/);
+    const maxMatch = definition.match(/\.max\((\d+)/);
+    if (minMatch) param.min = parseInt(minMatch[1]);
+    if (maxMatch) param.max = parseInt(maxMatch[1]);
+
+    params.push(param);
+  }
+
+  return params;
+}
+
+/**
+ * Generate example value for a parameter
+ */
+function generateExample(param) {
+  if (param.default !== null && param.default !== undefined) {
+    return param.default;
+  }
+
+  if (param.enum && param.enum.length > 0) {
+    return param.enum[0];
+  }
+
+  // Generate based on param name and type
+  const name = param.name.toLowerCase();
+
+  if (param.type === 'number') {
+    if (param.min !== undefined) return param.min;
+    if (name.includes('page')) return 1;
+    if (name.includes('per_page') || name.includes('count')) return 10;
+    return 10;
+  }
+
+  if (param.type === 'boolean') {
+    return true;
+  }
+
+  // String examples based on common param names
+  if (name === 'query' || name === 'q' || name === 'search') return 'nature sunset';
+  if (name.includes('id')) return 'abc123';
+  if (name.includes('url')) return 'https://example.com';
+  if (name.includes('color')) return 'blue';
+  if (name.includes('orientation')) return 'landscape';
+  if (name.includes('size')) return 'regular';
+
+  return 'example';
+}
+
+/**
+ * Generate working examples for an endpoint
+ */
+function generateExamples(action, params, apiId) {
+  const examples = {};
+  const baseUrl = `http://localhost:3000/api/v2/${apiId}`;
+
+  // Build query parts from required params
+  const buildQuery = (includeOptional = false) => {
+    const parts = [`action=${action}`];
+    for (const param of params) {
+      if (param.name === 'action') continue;
+      if (param.required || includeOptional) {
+        const val = generateExample(param);
+        if (val !== null && val !== undefined) {
+          parts.push(`${param.name}=${encodeURIComponent(String(val))}`);
+        }
+      }
+    }
+    return parts.join('&');
+  };
+
+  // Basic example with required params only
+  const basicQuery = buildQuery(false);
+  examples.basic = {
+    description: `Basic ${action} request`,
+    query: basicQuery,
+    curl: `curl -X GET '${baseUrl}?${basicQuery}'`
+  };
+
+  // Full example with all params
+  const fullQuery = buildQuery(true);
+  if (fullQuery !== basicQuery) {
+    examples.full = {
+      description: `${action} with all parameters`,
+      query: fullQuery,
+      curl: `curl -X GET '${baseUrl}?${fullQuery}'`
+    };
+  }
+
+  // If there are enums, generate examples for each enum value
+  for (const param of params) {
+    if (param.enum && param.enum.length > 1) {
+      for (const enumVal of param.enum.slice(0, 3)) { // First 3 enum values
+        const enumQuery = basicQuery.replace(
+          `${param.name}=${encodeURIComponent(String(generateExample(param)))}`,
+          `${param.name}=${encodeURIComponent(enumVal)}`
+        );
+        // Only add if different from basic
+        if (enumQuery !== basicQuery) {
+          examples[`${param.name}_${enumVal}`] = {
+            description: `${action} with ${param.name}=${enumVal}`,
+            query: enumQuery,
+            curl: `curl -X GET '${baseUrl}?${enumQuery}'`
+          };
+        }
+      }
+    }
+  }
+
+  return examples;
+}
+
+/**
+ * Format output for registry.json
+ */
+function formatForRegistry(parsed, apiId = 'api') {
+  const endpoints = {};
+
+  for (const [action, schema] of Object.entries(parsed.schemas)) {
+    const params = schema.params.map(p => ({
+      name: p.name,
+      type: p.type,
+      required: p.required,
+      description: p.description || `The ${p.name} parameter`,
+      default: p.default,
+      enum: p.enum,
+      min: p.min,
+      max: p.max,
+      example: String(generateExample(p))
+    })).filter(p => p.name !== 'action'); // Filter out the action param itself
+
+    endpoints[action] = {
+      method: 'GET', // Default, could be enhanced
+      description: `${action.charAt(0).toUpperCase() + action.slice(1).replace(/_/g, ' ')} action`,
+      params: params,
+      examples: generateExamples(action, params, apiId)
+    };
+  }
+
+  return {
+    actions: parsed.actions,
+    endpoints: endpoints
+  };
+}
+
+// Main execution
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error('Usage: node extract-schema-docs.cjs <schema-file-path> [api-id]');
+    console.error('  api-id: Optional API identifier for generating curl examples (e.g., "unsplash")');
+    process.exit(1);
+  }
+
+  const schemaPath = args[0];
+  const apiId = args[1] || path.basename(schemaPath, '.ts');
+
+  if (!fs.existsSync(schemaPath)) {
+    console.error(`File not found: ${schemaPath}`);
+    process.exit(1);
+  }
+
+  try {
+    const parsed = parseZodSchema(schemaPath);
+    const formatted = formatForRegistry(parsed, apiId);
+    console.log(JSON.stringify(formatted, null, 2));
+  } catch (error) {
+    console.error('Error parsing schema:', error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { parseZodSchema, formatForRegistry, generateExample, generateExamples };

package/templates/api-showcase/_components/APIModal.tsx

@@ -3,10 +3,29 @@
 import { useEffect, useCallback, useState } from "react";
 import { APITester } from "./APITester";
 
+interface EndpointParam {
+  name: string;
+  type: string;
+  description?: string;
+  required?: boolean;
+  default?: string | number | boolean;
+  enum?: string[];
+  example?: string;
+  min?: number;
+  max?: number;
+}
+
+interface EndpointExample {
+  description: string;
+  query: string;
+  curl: string;
+}
+
 interface RegistryAPI {
   name: string;
   description?: string;
   route: string;
+  routeFile?: string;
   schemas?: string;
   tests?: string;
   methods?: string[];
@@ -17,8 +36,11 @@ interface RegistryAPI {
   endpoints?: Record<
     string,
     {
-      methods: string[];
+      methods?: string[];
+      method?: string;
       description?: string;
+      params?: EndpointParam[];
+      examples?: Record<string, EndpointExample>;
     }
   >;
 }
@@ -41,13 +63,15 @@ interface APIModalProps {
  * - Request/response display
  * - Curl example generation
  *
- * Created with Hustle API Dev Tools (v3.9.2)
+ * Created with Hustle API Dev Tools (v3.12.10)
  */
 export function APIModal({ id, type, data, onClose }: APIModalProps) {
   const [activeTab, setActiveTab] = useState<"try-it" | "docs" | "curl">(
     "try-it",
   );
   const [selectedEndpoint, setSelectedEndpoint] = useState<string | null>(null);
+  const [submitRequest, setSubmitRequest] = useState<(() => Promise<void>) | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
 
   // Close on Escape key
   const handleKeyDown = useCallback(
@@ -86,14 +110,26 @@ export function APIModal({ id, type, data, onClose }: APIModalProps) {
   const currentEndpoint = selectedEndpoint
     ? endpoints[selectedEndpoint]
     : endpoints[endpointKeys[0]];
-  const methods = currentEndpoint?.methods || data.methods || ["POST"];
+  // Handle both methods array and single method string
+  const methods = currentEndpoint?.methods ||
+    (currentEndpoint?.method ? [currentEndpoint.method] : null) ||
+    data.methods ||
+    ["POST"];
   const baseUrl =
     typeof window !== "undefined"
       ? window.location.origin
       : "http://localhost:3000";
 
-  // Build endpoint path
+  // Build endpoint path - always use base path for action-based APIs
+  // Actions are passed as query parameters, not sub-paths
   const getEndpointPath = () => {
+    // Check if this API uses action-based routing (has params with action)
+    const hasActionParam = currentEndpoint?.params?.some(p => p.name === "action");
+    if (hasActionParam) {
+      // Action-based APIs use query params, not path segments
+      return `/api/v2/${id}`;
+    }
+    // For true sub-endpoint APIs, include the path
     if (selectedEndpoint && selectedEndpoint !== "default") {
       return `/api/v2/${id}/${selectedEndpoint}`;
     }
@@ -102,10 +138,26 @@ export function APIModal({ id, type, data, onClose }: APIModalProps) {
 
   const endpoint = getEndpointPath();
 
-  // Generate curl example
+  // Generate curl example with proper query params
   const generateCurl = (method: string) => {
+    // Build example query string from params
+    const params = currentEndpoint?.params || [];
+    const queryParts: string[] = [];
+
+    for (const param of params) {
+      if (param.name === "action" && selectedEndpoint) {
+        queryParts.push(`action=${selectedEndpoint}`);
+      } else if (param.required && param.example) {
+        queryParts.push(`${param.name}=${encodeURIComponent(param.example)}`);
+      } else if (param.example) {
+        queryParts.push(`${param.name}=${encodeURIComponent(param.example)}`);
+      }
+    }
+
+    const queryString = queryParts.length > 0 ? `?${queryParts.join("&")}` : "";
+
     if (method === "GET") {
-      return `curl -X GET "${baseUrl}${endpoint}"`;
+      return `curl -X GET "${baseUrl}${endpoint}${queryString}"`;
     }
     return `curl -X ${method} "${baseUrl}${endpoint}" \\
   -H "Content-Type: application/json" \\
@@ -129,7 +181,7 @@ export function APIModal({ id, type, data, onClose }: APIModalProps) {
       />
 
       {/* Modal Content */}
-      <div className="relative z-10 flex max-h-[90vh] w-full max-w-5xl flex-col overflow-hidden border-2 border-black bg-white shadow-xl dark:border-gray-600 dark:bg-gray-900">
+      <div className="relative z-10 flex max-h-[90vh] w-full max-w-7xl flex-col overflow-hidden border-2 border-black bg-white shadow-xl dark:border-gray-600 dark:bg-gray-900">
         {/* Header */}
         <header className="flex items-center justify-between border-b-2 border-black px-6 py-4 dark:border-gray-600">
           <div className="flex items-center gap-4">
@@ -271,6 +323,11 @@ export function APIModal({ id, type, data, onClose }: APIModalProps) {
               methods={methods}
               selectedEndpoint={selectedEndpoint}
               schemaPath={data.schemas}
+              endpointParams={data.endpoints?.[selectedEndpoint || "default"]?.params || data.endpoints?.[Object.keys(data.endpoints || {})[0]]?.params}
+              apiRoute={data.routeFile || data.route}
+              examples={data.endpoints?.[selectedEndpoint || "default"]?.examples || data.endpoints?.[Object.keys(data.endpoints || {})[0]]?.examples}
+              onSubmitRef={(fn) => setSubmitRequest(() => fn)}
+              onLoadingChange={setIsLoading}
             />
           )}
 
@@ -408,10 +465,45 @@ export function APIModal({ id, type, data, onClose }: APIModalProps) {
                     );
                   }
                 }}
-                className="border-2 border-black bg-[#BA0C2F] px-3 py-1.5 text-sm font-medium text-white hover:bg-[#8a0923]"
+                className="border-2 border-black px-3 py-1.5 text-sm font-medium hover:bg-gray-100 dark:border-gray-600 dark:hover:bg-gray-800"
               >
                 Copy Schema Import
               </button>
+              {activeTab === "try-it" && submitRequest && (
+                <button
+                  onClick={() => submitRequest()}
+                  disabled={isLoading}
+                  className="border-2 border-black bg-[#BA0C2F] px-4 py-1.5 text-sm font-bold text-white transition-colors hover:bg-[#8a0923] disabled:opacity-50"
+                >
+                  {isLoading ? (
+                    <span className="flex items-center gap-2">
+                      <svg
+                        className="h-4 w-4 animate-spin"
+                        xmlns="http://www.w3.org/2000/svg"
+                        fill="none"
+                        viewBox="0 0 24 24"
+                      >
+                        <circle
+                          className="opacity-25"
+                          cx="12"
+                          cy="12"
+                          r="10"
+                          stroke="currentColor"
+                          strokeWidth="4"
+                        />
+                        <path
+                          className="opacity-75"
+                          fill="currentColor"
+                          d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"
+                        />
+                      </svg>
+                      Sending...
+                    </span>
+                  ) : (
+                    "Send Request"
+                  )}
+                </button>
+              )}
             </div>
           </div>
         </footer>

package/templates/api-showcase/_components/APIShowcase.tsx

@@ -4,6 +4,33 @@ import { useState, useMemo } from "react";
 import { APICard } from "./APICard";
 import { APIModal } from "./APIModal";
 
+// Import registry - this will be updated by the CLI when APIs are created
+import registryData from "@/../.claude/registry.json";
+
+/**
+ * Parameter documentation from registry.json
+ */
+interface EndpointParam {
+  name: string;
+  type: string;
+  description?: string;
+  required?: boolean;
+  default?: string | number | boolean;
+  enum?: string[];
+  example?: string;
+  min?: number;
+  max?: number;
+}
+
+/**
+ * Example request from registry.json
+ */
+interface EndpointExample {
+  description: string;
+  query: string;
+  curl: string;
+}
+
 /**
  * Registry structure from .claude/registry.json
  */
@@ -11,16 +38,21 @@ interface RegistryAPI {
   name: string;
   description?: string;
   route: string;
+  routeFile?: string;
   schemas?: string;
   tests?: string;
   methods?: string[];
   created_at?: string;
   status?: string;
+  actions?: string[];
   endpoints?: Record<
     string,
     {
-      methods: string[];
+      methods?: string[];
+      method?: string;
       description?: string;
+      params?: EndpointParam[];
+      examples?: Record<string, EndpointExample>;
     }
   >;
 }
@@ -46,7 +78,7 @@ interface APIShowcaseProps {
  *
  * Data source: .claude/registry.json (apis + combined sections)
  *
- * Created with Hustle API Dev Tools (v3.9.2)
+ * Created with Hustle API Dev Tools (v3.12.10)
  */
 export function APIShowcase({ registry: propRegistry }: APIShowcaseProps) {
   const [selectedAPI, setSelectedAPI] = useState<{
@@ -57,8 +89,8 @@ export function APIShowcase({ registry: propRegistry }: APIShowcaseProps) {
   const [filter, setFilter] = useState<"all" | "api" | "combined">("all");
   const [search, setSearch] = useState("");
 
-  // Use prop registry or default empty structure
-  const registry: Registry = propRegistry || {
+  // Use prop registry, imported registry, or default empty structure
+  const registry: Registry = propRegistry || registryData || {
     version: "1.0.0",
     apis: {},
     combined: {},