@hustle-together/api-dev-tools 3.12.3 → 4.5.1

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

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState, useEffect } from "react";
+import { useState, useEffect, useCallback } from "react";
 
 interface ParameterDoc {
   name: string;
@@ -9,6 +9,9 @@ interface ParameterDoc {
   required?: boolean;
   default?: string | number | boolean;
   enum?: string[];
+  example?: string;
+  min?: number;
+  max?: number;
 }
 
 interface SchemaDoc {
@@ -17,6 +20,19 @@ interface SchemaDoc {
   queryParams?: ParameterDoc[];
 }
 
+/** Example request from registry.json */
+interface EndpointExample {
+  description: string;
+  query: string;
+  curl: string;
+}
+
+/** State for each parameter in the interactive builder */
+interface ParamState {
+  enabled: boolean;
+  value: string;
+}
+
 interface APITesterProps {
   id: string;
   endpoint: string;
@@ -24,6 +40,16 @@ interface APITesterProps {
   selectedEndpoint?: string | null;
   schemaPath?: string;
   schema?: SchemaDoc;
+  /** Parameters from registry.json endpoints section */
+  endpointParams?: ParameterDoc[];
+  /** API route file path for reference */
+  apiRoute?: string;
+  /** Pre-built examples from registry.json */
+  examples?: Record<string, EndpointExample>;
+  /** Callback to expose submit function to parent */
+  onSubmitRef?: (submitFn: () => Promise<void>) => void;
+  /** Callback to notify parent of loading state */
+  onLoadingChange?: (isLoading: boolean) => void;
 }
 
 interface RequestState {
@@ -80,7 +106,7 @@ const DEFAULT_QUERY_PARAMS: Record<string, Record<string, string>> = {
  * - Response display with timing
  * - Audio playback for binary responses
  *
- * Created with Hustle API Dev Tools (v3.9.2)
+ * Created with Hustle API Dev Tools (v3.12.12)
  */
 export function APITester({
   id,
@@ -89,7 +115,63 @@ export function APITester({
   selectedEndpoint,
   schemaPath,
   schema,
+  endpointParams,
+  apiRoute,
+  examples,
+  onSubmitRef,
+  onLoadingChange,
 }: APITesterProps) {
+  const [selectedExample, setSelectedExample] = useState<string | null>(null);
+
+  // Interactive parameter builder state
+  const [paramStates, setParamStates] = useState<Record<string, ParamState>>({});
+
+  // Initialize param states from endpointParams
+  const initializeParamStates = useCallback((params: ParameterDoc[] | undefined) => {
+    if (!params) return {};
+    const states: Record<string, ParamState> = {};
+    for (const param of params) {
+      // Default value: example > default > empty
+      const defaultValue = param.example ||
+        (param.default !== undefined ? String(param.default) : "") ||
+        (param.enum?.[0] || "");
+
+      // Required params are enabled by default
+      states[param.name] = {
+        enabled: param.required || false,
+        value: defaultValue,
+      };
+    }
+    return states;
+  }, []);
+
+  // Build query string from param states
+  const buildQueryFromStates = useCallback((states: Record<string, ParamState>) => {
+    const parts: string[] = [];
+    for (const [name, state] of Object.entries(states)) {
+      if (state.enabled && state.value) {
+        parts.push(`${name}=${encodeURIComponent(state.value)}`);
+      }
+    }
+    return parts.join("&");
+  }, []);
+
+  // Update param states from query string (for example buttons)
+  const updateStatesFromQuery = useCallback((query: string, params: ParameterDoc[] | undefined) => {
+    if (!params) return;
+    const searchParams = new URLSearchParams(query);
+    const newStates: Record<string, ParamState> = {};
+
+    for (const param of params) {
+      const value = searchParams.get(param.name);
+      newStates[param.name] = {
+        enabled: value !== null,
+        value: value || param.example || (param.default !== undefined ? String(param.default) : "") || (param.enum?.[0] || ""),
+      };
+    }
+    setParamStates(newStates);
+  }, []);
+
   // Get default body for this API/endpoint
   const getDefaultBody = () => {
     const apiDefaults = DEFAULT_BODIES[id];
@@ -104,10 +186,30 @@ export function APITester({
 
   // Get default query params for GET requests
   const getDefaultQueryParams = () => {
+    // First check hardcoded defaults
     const apiParams = DEFAULT_QUERY_PARAMS[id];
     if (apiParams && selectedEndpoint) {
       return apiParams[selectedEndpoint] || "";
     }
+
+    // Build from endpointParams if available
+    if (endpointParams && endpointParams.length > 0) {
+      const queryParts: string[] = [];
+      for (const param of endpointParams) {
+        if (param.name === "action") {
+          // Add action with the selectedEndpoint or default value
+          queryParts.push(`action=${selectedEndpoint || param.default || ""}`);
+        } else if (param.required && param.example) {
+          // Add required params with example values
+          queryParts.push(`${param.name}=${encodeURIComponent(param.example)}`);
+        } else if (param.required && param.default !== undefined) {
+          // Add required params with defaults
+          queryParts.push(`${param.name}=${encodeURIComponent(String(param.default))}`);
+        }
+      }
+      return queryParts.join("&");
+    }
+
     return "";
   };
 
@@ -132,15 +234,34 @@ export function APITester({
   const [isLoading, setIsLoading] = useState(false);
   const [audioUrl, setAudioUrl] = useState<string | null>(null);
 
+  // Expose submit function to parent for footer button
+  useEffect(() => {
+    if (onSubmitRef) {
+      onSubmitRef(handleSubmit);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [onSubmitRef, request, endpoint]);
+
+  // Notify parent of loading state changes
+  useEffect(() => {
+    if (onLoadingChange) {
+      onLoadingChange(isLoading);
+    }
+  }, [isLoading, onLoadingChange]);
+
   // Update defaults when endpoint changes
   useEffect(() => {
+    const queryParams = endpointParams || schema?.queryParams;
+    const initialStates = initializeParamStates(queryParams);
+    setParamStates(initialStates);
+
     setRequest((prev) => ({
       ...prev,
       method: methods[0] || "POST",
       body: getDefaultBody(),
-      queryParams: getDefaultQueryParams(),
+      queryParams: buildQueryFromStates(initialStates),
     }));
-    // Clear previous response
+    // Clear previous response and example selection
     setResponse({
       status: null,
       statusText: "",
@@ -150,8 +271,17 @@ export function APITester({
       contentType: null,
     });
     setAudioUrl(null);
+    setSelectedExample(null);
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [selectedEndpoint, id]);
+  }, [selectedEndpoint, id, endpointParams, examples, schema]);
+
+  // Auto-update query string when param states change
+  useEffect(() => {
+    if (Object.keys(paramStates).length > 0) {
+      const newQuery = buildQueryFromStates(paramStates);
+      setRequest((prev) => ({ ...prev, queryParams: newQuery }));
+    }
+  }, [paramStates, buildQueryFromStates]);
 
   const handleSubmit = async () => {
     setIsLoading(true);
@@ -298,6 +428,49 @@ export function APITester({
           </div>
         </div>
 
+        {/* Example Selector (for GET requests with examples) */}
+        {request.method === "GET" && examples && Object.keys(examples).length > 0 && (
+          <div>
+            <label className="mb-1 block text-sm font-bold text-black dark:text-white">
+              Example Requests
+            </label>
+            <div className="flex flex-wrap gap-2">
+              {Object.entries(examples).map(([key, example]) => (
+                <button
+                  key={key}
+                  onClick={() => {
+                    setSelectedExample(key);
+                    updateStatesFromQuery(example.query, endpointParams || schema?.queryParams);
+                  }}
+                  className={`border-2 px-3 py-1.5 text-xs font-medium transition-colors ${
+                    selectedExample === key
+                      ? "border-[#BA0C2F] bg-[#BA0C2F] text-white"
+                      : "border-black bg-white text-black hover:border-[#BA0C2F] dark:border-gray-600 dark:bg-gray-800 dark:text-white"
+                  }`}
+                  title={example.description}
+                >
+                  {key.replace(/_/g, " ")}
+                </button>
+              ))}
+            </div>
+            {selectedExample && examples[selectedExample] && (
+              <div className="mt-2 flex items-center gap-2">
+                <p className="text-xs text-gray-600 dark:text-gray-400">
+                  {examples[selectedExample].description}
+                </p>
+                <button
+                  onClick={() => {
+                    navigator.clipboard.writeText(examples[selectedExample].curl);
+                  }}
+                  className="shrink-0 border border-gray-300 bg-gray-100 px-2 py-0.5 text-xs text-gray-600 hover:bg-gray-200 dark:border-gray-600 dark:bg-gray-700 dark:text-gray-300"
+                >
+                  Copy curl
+                </button>
+              </div>
+            )}
+          </div>
+        )}
+
         {/* Query Parameters (for GET requests) */}
         {request.method === "GET" && (
           <div>
@@ -307,14 +480,15 @@ export function APITester({
             <input
               type="text"
               value={request.queryParams}
-              onChange={(e) =>
-                setRequest((prev) => ({ ...prev, queryParams: e.target.value }))
-              }
+              onChange={(e) => {
+                setSelectedExample(null); // Clear example selection when manually editing
+                setRequest((prev) => ({ ...prev, queryParams: e.target.value }));
+              }}
               className="w-full border-2 border-black bg-white px-3 py-2 font-mono text-sm focus:border-[#BA0C2F] focus:outline-none dark:border-gray-600 dark:bg-gray-800 dark:text-white"
               placeholder="key1=value1&key2=value2"
             />
             <p className="mt-1 text-xs text-gray-600 dark:text-gray-400">
-              Add query string parameters (without the ?)
+              Add query string parameters (without the ?) - or select an example above
             </p>
           </div>
         )}
@@ -346,14 +520,22 @@ export function APITester({
           </div>
         )}
 
-        {/* Parameter Documentation */}
-        {schema && (schema.request?.length || schema.queryParams?.length) ? (
-          <ParameterDocs
-            requestParams={schema.request}
-            queryParams={schema.queryParams}
-            isGetRequest={request.method === "GET"}
+        {/* Interactive Parameter Builder (for GET requests with params) */}
+        {request.method === "GET" && (endpointParams?.length || schema?.queryParams?.length) ? (
+          <InteractiveParamBuilder
+            params={endpointParams || schema?.queryParams || []}
+            paramStates={paramStates}
+            setParamStates={setParamStates}
           />
-        ) : null}
+        ) : (
+          /* Static Parameter Documentation (for non-GET requests) */
+          (schema && schema.request?.length) ? (
+            <ParameterDocs
+              requestParams={schema?.request}
+              isGetRequest={false}
+            />
+          ) : null
+        )}
 
         {/* Headers */}
         <div>
@@ -376,41 +558,6 @@ export function APITester({
             API keys loaded from .env automatically
           </p>
         </div>
-
-        {/* Submit Button */}
-        <button
-          onClick={handleSubmit}
-          disabled={isLoading}
-          className="w-full border-2 border-black bg-[#BA0C2F] py-3 font-bold text-white transition-colors hover:bg-[#8a0923] disabled:opacity-50"
-        >
-          {isLoading ? (
-            <span className="flex items-center justify-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.method} Request`
-          )}
-        </button>
       </div>
 
       {/* Response Panel */}
@@ -488,23 +635,170 @@ export function APITester({
   );
 }
 
+/**
+ * Interactive Parameter Builder Component
+ * Allows users to check/uncheck params and edit values to build query strings.
+ */
+function InteractiveParamBuilder({
+  params,
+  paramStates,
+  setParamStates,
+}: {
+  params: ParameterDoc[];
+  paramStates: Record<string, ParamState>;
+  setParamStates: React.Dispatch<React.SetStateAction<Record<string, ParamState>>>;
+}) {
+  const [isExpanded, setIsExpanded] = useState(true);
+
+  if (!params.length) return null;
+
+  const handleToggle = (name: string) => {
+    setParamStates((prev) => ({
+      ...prev,
+      [name]: {
+        ...prev[name],
+        enabled: !prev[name]?.enabled,
+      },
+    }));
+  };
+
+  const handleValueChange = (name: string, value: string) => {
+    setParamStates((prev) => ({
+      ...prev,
+      [name]: {
+        ...prev[name],
+        value,
+        enabled: true, // Auto-enable when value is changed
+      },
+    }));
+  };
+
+  return (
+    <div className="border-2 border-black dark:border-gray-600">
+      <button
+        onClick={() => setIsExpanded(!isExpanded)}
+        className="flex w-full items-center justify-between bg-gray-50 px-3 py-2 text-left dark:bg-gray-800"
+      >
+        <span className="text-sm font-bold text-black dark:text-white">
+          Query Parameters Builder
+        </span>
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="16"
+          height="16"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          className={`text-gray-500 transition-transform ${isExpanded ? "rotate-180" : ""}`}
+        >
+          <polyline points="6 9 12 15 18 9" />
+        </svg>
+      </button>
+
+      {isExpanded && (
+        <div className="divide-y divide-gray-200 bg-white dark:divide-gray-700 dark:bg-gray-900">
+          {params.map((param) => {
+            const state = paramStates[param.name] || { enabled: false, value: "" };
+
+            return (
+              <div key={param.name} className="flex items-start gap-3 px-3 py-2">
+                {/* Checkbox */}
+                <label className="flex h-8 cursor-pointer items-center">
+                  <input
+                    type="checkbox"
+                    checked={state.enabled}
+                    onChange={() => handleToggle(param.name)}
+                    disabled={param.required}
+                    className="h-4 w-4 cursor-pointer accent-[#BA0C2F] disabled:cursor-not-allowed disabled:opacity-50"
+                  />
+                </label>
+
+                {/* Parameter Info */}
+                <div className="min-w-0 flex-1">
+                  <div className="flex flex-wrap items-center gap-2">
+                    <code className="text-sm font-bold text-[#BA0C2F]">
+                      {param.name}
+                    </code>
+                    <span className="border border-gray-300 bg-gray-100 px-1.5 py-0.5 text-xs text-gray-600 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-400">
+                      {param.type}
+                    </span>
+                    {param.required && (
+                      <span className="border border-red-300 bg-red-50 px-1.5 py-0.5 text-xs text-red-600 dark:border-red-800 dark:bg-red-900/30 dark:text-red-400">
+                        required
+                      </span>
+                    )}
+                  </div>
+                  {param.description && (
+                    <p className="mt-0.5 text-xs text-gray-600 dark:text-gray-400">
+                      {param.description}
+                    </p>
+                  )}
+                </div>
+
+                {/* Input Control */}
+                <div className="w-36 shrink-0">
+                  {param.enum ? (
+                    /* Dropdown for enum types */
+                    <select
+                      value={state.value}
+                      onChange={(e) => handleValueChange(param.name, e.target.value)}
+                      className="w-full border border-gray-300 bg-white px-2 py-1.5 text-sm focus:border-[#BA0C2F] focus:outline-none dark:border-gray-600 dark:bg-gray-800 dark:text-white"
+                    >
+                      <option value="">-- none --</option>
+                      {param.enum.map((val) => (
+                        <option key={val} value={val}>
+                          {val}
+                        </option>
+                      ))}
+                    </select>
+                  ) : param.type === "number" || param.type === "integer" ? (
+                    /* Number input for numeric types */
+                    <input
+                      type="number"
+                      value={state.value}
+                      onChange={(e) => handleValueChange(param.name, e.target.value)}
+                      min={param.min}
+                      max={param.max}
+                      placeholder={param.example || (param.default !== undefined ? String(param.default) : "")}
+                      className="w-full border border-gray-300 bg-white px-2 py-1.5 text-sm focus:border-[#BA0C2F] focus:outline-none dark:border-gray-600 dark:bg-gray-800 dark:text-white"
+                    />
+                  ) : (
+                    /* Text input for string types */
+                    <input
+                      type="text"
+                      value={state.value}
+                      onChange={(e) => handleValueChange(param.name, e.target.value)}
+                      placeholder={param.example || (param.default !== undefined ? String(param.default) : "")}
+                      className="w-full border border-gray-300 bg-white px-2 py-1.5 text-sm focus:border-[#BA0C2F] focus:outline-none dark:border-gray-600 dark:bg-gray-800 dark:text-white"
+                    />
+                  )}
+                </div>
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}
+
 /**
  * Parameter Documentation Component
- * Displays request body and query parameter documentation in a collapsible panel.
+ * Displays request body documentation in a collapsible panel (for non-GET requests).
  */
 function ParameterDocs({
   requestParams,
-  queryParams,
   isGetRequest,
 }: {
   requestParams?: ParameterDoc[];
-  queryParams?: ParameterDoc[];
   isGetRequest: boolean;
 }) {
   const [isExpanded, setIsExpanded] = useState(true);
 
-  const paramsToShow = isGetRequest ? queryParams : requestParams;
-  if (!paramsToShow?.length) return null;
+  if (!requestParams?.length) return null;
 
   return (
     <div className="border-2 border-black dark:border-gray-600">
@@ -513,7 +807,7 @@ function ParameterDocs({
         className="flex w-full items-center justify-between bg-gray-50 px-3 py-2 text-left dark:bg-gray-800"
       >
         <span className="text-sm font-bold text-black dark:text-white">
-          {isGetRequest ? "Query Parameters" : "Request Body"} Documentation
+          Request Body Documentation
         </span>
         <svg
           xmlns="http://www.w3.org/2000/svg"
@@ -533,7 +827,7 @@ function ParameterDocs({
 
       {isExpanded && (
         <div className="divide-y divide-gray-200 bg-white dark:divide-gray-700 dark:bg-gray-900">
-          {paramsToShow.map((param) => (
+          {requestParams.map((param) => (
             <div key={param.name} className="px-3 py-2">
               <div className="flex items-center gap-2">
                 <code className="text-sm font-bold text-[#BA0C2F]">
@@ -574,6 +868,21 @@ function ParameterDocs({
                   </code>
                 </p>
               )}
+              {param.example && (
+                <p className="mt-1 text-xs text-gray-500">
+                  Example:{" "}
+                  <code className="text-gray-700 dark:text-gray-300">
+                    {param.example}
+                  </code>
+                </p>
+              )}
+              {(param.min !== undefined || param.max !== undefined) && (
+                <p className="mt-1 text-xs text-gray-500">
+                  {param.min !== undefined && `Min: ${param.min}`}
+                  {param.min !== undefined && param.max !== undefined && " · "}
+                  {param.max !== undefined && `Max: ${param.max}`}
+                </p>
+              )}
             </div>
           ))}
         </div>