quickbase-js 0.1.0-beta.7

package/examples/quicbase-jsCDN.html

@@ -0,0 +1,36 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+    <title>Quickbase</title>
+    <script src="https://cdn.jsdelivr.net/npm/quickbase-js@1.1.0-beta.6/dist/umd/quickbase.umd.min.js"></script>
+</head>
+
+<body>
+    <div>
+        <h1>Quickbase-js CDN Example</h1>
+        <p id="result">Loading...</p>
+    </div>
+    <script>
+        var realm = "xxxxxxxxxxxxxxxxxxxx"; // replace with your realm
+        var appId = "xxxxxxxxxxxxxxxxxxxx"; // replace with your app ID
+        if (typeof QuickbaseJS === "undefined") {
+            document.getElementById("result").textContent = "Error: Failed to load QuickbaseJS library.";
+        } else {
+            var qbClient = QuickbaseJS.quickbase({
+                realm,
+                useTempTokens: true
+            });
+
+            qbClient.getApp({ appId })
+                .then(function (app) {
+                    document.getElementById("result").textContent = "App Name: " + app.name;
+                })
+                .catch(function (err) {
+                    document.getElementById("result").textContent = "Error: " + (err.message || "Failed to load app");
+                });
+        }
+    </script>
+</body>
+
+</html>

package/examples/react.js

@@ -0,0 +1,48 @@
+import React, { useState, useEffect } from "react";
+import { quickbase } from "quickbase-js";
+
+const App = () => {
+  const [appName, setAppName] = useState < string > "Loading...";
+  const [error, setError] = (useState < string) | (null > null);
+
+  useEffect(() => {
+    // Initialize the QuickBase client
+    const qb = quickbase({
+      realm: "your-realm", // Replace with actual QuickBase realm
+      // ## ------------------------------
+      // ## Authentication Options
+      // ## ------------------------------
+      // ## OPTION 1: User Token Authentication
+      // ## - Use this if you have a QuickBase user token (get it from "My Profile" > "Manage User Tokens")
+      // ## - Works in Node.js or browsers, ideal for standalone apps or testing outside QuickBase
+      // ## - Use the line below and replace with your token; comment out 'useTempTokens'
+      // userToken: "your-user-token",
+
+      // ## ------------------------------
+      // ## OPTION 2: Temporary Token Authentication
+      // ## - Use this for QuickBase code pages, leveraging the browser’s authenticated session
+      // ## - No user token needed; requires running in a QuickBase browser context
+      // ## - Uncomment the line below and comment out 'userToken' if using this option
+      // useTempTokens: true,
+    });
+
+    // Fetch the app
+    qb.getApp({ appId: "your-app-id" }) // Replace with actual app ID
+      .then((app) => {
+        setAppName(app.name);
+      })
+      .catch((err) => {
+        console.error("Error fetching app:", err);
+        setError("Failed to load app");
+      });
+  }, []); // Empty dependency array to run once on mount
+
+  return (
+    <div>
+      <h1>Quickbase Test</h1>
+      {error ? <p>{error}</p> : <p>App Name: {appName}</p>}
+    </div>
+  );
+};
+
+export default App;

package/examples/vanillajs.html

@@ -0,0 +1,47 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <title>Quickbase Test</title>
+</head>
+
+<body>
+  <div>
+    <h1>Quickbase Test</h1>
+    <p id="result">Loading...</p>
+  </div>
+  <script type="module">
+    import { quickbase } from 'quickbase-js';
+    // Initalize the QuickBase client
+    const qb = quickbase({
+      realm: 'your-realm', // Replace with actual QuickBase realm
+      // ## ------------------------------
+      // ## Authentication Options
+      // ## ----------------------------
+      // ## OPTION 1: User Token Authentication
+      // ## - Use this if you have a QuickBase user token (get it from "My Profile" > "Manage User Tokens")
+      // ## - Works in Node.js or browsers, ideal for standalone apps or testing outside QuickBase
+      // ## - Uncomment the line below and replace with your token; comment out 'useTempTokens'
+      // userToken: "your-user-token",
+
+      // ## ----------------------------
+      // ## OPTION 2: Temporary Token Authentication
+      // ## - Use this for QuickBase code pages, leveraging the browser’s authenticated session
+      // ## - No user token needed; requires running in a QuickBase browser context
+      // ## - Uncomment the line below and comment out 'userToken' if using this option
+      // useTempTokens: true,
+    });
+
+    // Fetch the app
+    qb.getApp({ appId: 'your-app-id' }) // Replace with actual app ID
+      .then((app) => {
+        document.getElementById('result').textContent = `App Name: ${app.name}`;
+      })
+      .catch((err) => {
+        console.error('Error fetching app:', err);
+        document.getElementById('result').textContent = err.message || 'Failed to load app';
+      });
+  </script>
+</body>
+
+</html>

package/notes.txt

@@ -0,0 +1,158 @@
+At the core of my challenge is to update the QuickbaseClient.ts file with the correct types signatures, removing "any" types.Right now the way I have been doing that is by adding spec overrides to the raw specs/QuickBase_RESTful_API_*.json file by creating open-api/paths/* and open-api/definitions/* files based on the quickbase documentation that override the raw specs file. I think this has been working okay, its fairly manual, and I feel like I am duplicating a lot of work that exists in the raw specs file. The reason I'm doing this is because the raw specs file has been difficult to work with in the past.Please give me a detailed summary of how the QuickbaseClient.ts is generated,
+
+Yes, I understand your concern, and you're correct to point out that enhancing raw spec processing represents a shift from your current strategy of using path/* and definitions/* folder overrides. Let's clarify the relationship between these approaches and why enhancing raw spec processing could be a complementary or alternative strategy.
+Current Strategy (Path/* and Definitions/* Overrides):
+Manual overrides in open-api/paths/* and open-api/definitions/*
+
+Directly modifies specific endpoints and types
+
+Pros:
+Precise control over problematic endpoints
+
+Immediate fixes for known issues
+
+Cons:
+Manual and time-consuming
+
+Duplicates information from raw spec
+
+Doesn't scale well for large APIs
+
+Maintenance burden as API evolves
+
+Proposed Strategy (Enhanced Raw Spec Processing):
+Focuses on improving the initial processing of QuickBase_RESTful_API_*.json
+
+Aims to extract better type information from the raw spec
+
+Pros:
+Addresses root causes of "any" types
+
+Scales better for large APIs
+
+Reduces need for manual overrides
+
+More maintainable long-term
+
+Cons:
+Requires more upfront development
+
+May need validation to ensure accuracy
+
+Still might require some manual overrides for edge cases
+
+Relationship Between Strategies:
+Complementary Nature:
+Enhanced raw spec processing can reduce the need for manual overrides
+
+Overrides can still be used for edge cases or QuickBase-specific quirks
+
+Better raw spec processing makes overrides more targeted and efficient
+
+Evolution, Not Replacement:
+We're not abandoning the override system entirely
+
+Instead, we're adding a new layer of processing to make overrides less necessary
+
+The goal is to shift from heavy reliance on manual overrides to automated type extraction
+
+Strategic Shift:
+Moving from reactive (fixing issues after they're found) to proactive (preventing issues at the source)
+
+Investing in better raw spec processing now will reduce maintenance costs later
+
+Allows for more systematic type improvements across the entire API
+
+Implementation Plan for Enhanced Raw Spec Processing:
+Spec Analysis Tool:
+Develop a tool to analyze QuickBase_RESTful_API_*.json
+
+Identify:
+Endpoints with incomplete type information
+
+Patterns leading to "any" types
+
+Common schema structures
+
+Output a type inventory report
+
+Enhanced fix-spec-main.ts:
+Implement partial spec loading for efficiency
+
+Add type validation and inference:
+Detect missing schema information
+
+Infer types from examples or patterns
+
+Flag areas needing manual review
+
+Enhance array and object schema processing
+
+Type Mapping Improvements:
+Extend mapOpenApiTypeToTs in generate-unified-interface.ts:
+Handle more OpenAPI type variations
+
+Add fallback type inference
+
+Improve mapRefToType:
+Handle complex schema compositions
+
+Better reference resolution
+
+Validation and Reporting:
+Add type quality validation in generate-unified-interface.ts
+
+Generate reports on:
+"any" type occurrences
+
+Missing type information
+
+Suggested manual overrides
+
+Integration with Existing Overrides:
+Modify fix-spec-main.ts to:
+Apply automated fixes first
+
+Then merge path/* and definitions/* overrides
+
+Create a report comparing automated vs. manual type definitions
+
+Transition Strategy:
+Parallel Development:
+Continue using current overrides while developing new processing
+
+Run both systems in parallel for validation
+
+Gradual Migration:
+Start with automated processing for new endpoints
+
+Gradually reduce manual overrides as confidence grows
+
+Maintain overrides for edge cases
+
+Validation and Feedback:
+Compare generated types from both approaches
+
+Identify areas where overrides are still necessary
+
+Refine automated processing based on findings
+
+Next Steps:
+Given that this is a strategic shift, I recommend:
+Starting with the spec analysis tool to understand raw spec patterns
+
+Implementing basic enhancements to fix-spec-main.ts
+
+Running parallel generation (old vs. new) for comparison
+
+Gradually reducing reliance on manual overrides
+
+Would you like to:
+See a detailed implementation plan for the spec analysis tool?
+
+Start with specific enhancements to fix-spec-main.ts?
+
+Develop a validation process to compare old vs. new approaches?
+
+Discuss how to maintain both strategies during transition?
+

package/open-api/fix-spec-main.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+import { promises as fs } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import * as glob from "glob";
+import { enhanceTags } from "./schema/tags/index.ts";
+import { enhanceGeneral } from "./schema/enhance-general.ts";
+import { fixArrays } from "./schema/fix-arrays.ts";
+import { Spec } from "./types/spec.ts";
+import { toCamelCase } from "./utils/naming.ts";
+
+// Removed FixSpecConfig since applyOverrides is no longer needed
+async function fixQuickBaseSpec(): Promise<void> {
+  try {
+    const CODEGEN_DIR = path.dirname(fileURLToPath(import.meta.url));
+    const SPECS_DIR = path.join(CODEGEN_DIR, "..", "specs");
+    const OUTPUT_DIR = path.join(CODEGEN_DIR, "output");
+    console.log("Finding latest QuickBase RESTful API spec...");
+    const specFiles = glob.sync(
+      path.join(SPECS_DIR, "QuickBase_RESTful_*.json")
+    );
+    if (specFiles.length === 0) {
+      throw new Error(
+        "No QuickBase_RESTful_*.json files found in specs/ folder."
+      );
+    }
+    const inputFile = specFiles.sort().pop() as string;
+    const outputFile = path.join(OUTPUT_DIR, "quickbase-fixed.json");
+
+    console.log(`Reading ${path.basename(inputFile)} from specs/...`);
+    const specContent = await fs.readFile(inputFile, "utf8");
+    const spec: Spec = JSON.parse(specContent);
+
+    console.log("Fixing parameters...");
+    for (const pathKey in spec.paths) {
+      for (const method in spec.paths[pathKey]) {
+        const operation = spec.paths[pathKey][method];
+        if (operation.parameters) {
+          operation.parameters = operation.parameters
+            .filter(
+              (param) =>
+                !["QB-Realm-Hostname", "Authorization", "User-Agent"].includes(
+                  param.name
+                )
+            )
+            .map((param) => {
+              param.name = toCamelCase(param.name);
+              if ("example" in param) delete param.example;
+              if ("schema" in param && param.in !== "body") delete param.schema;
+              if (!param.type && param.in !== "body") {
+                param.type = param.name.includes("Id") ? "string" : "string";
+                console.log(
+                  `Set default type 'string' for ${pathKey}(${method}).${param.name} in initial pass`
+                );
+              }
+              return param;
+            });
+        }
+      }
+    }
+
+    // Removed applyOverrides conditional logic
+    console.log("Enhancing raw spec with tags...");
+    enhanceTags(spec);
+    console.log("Enhancing raw spec with general enhancements...");
+    enhanceGeneral(spec);
+
+    console.log("Fixing array schemas...");
+    fixArrays(spec);
+
+    console.log("Removing unexpected top-level attributes...");
+    delete spec.operations;
+    delete spec.groups;
+    delete spec.components;
+
+    console.log(`Writing fixed spec to ${path.basename(outputFile)}...`);
+    await fs.mkdir(OUTPUT_DIR, { recursive: true });
+    await fs.writeFile(outputFile, JSON.stringify(spec, null, 2), "utf8");
+    console.log("Spec fixed successfully! Output written to:", outputFile);
+  } catch (error) {
+    console.error("Failed to fix spec:", error);
+    process.exit(1);
+  }
+}
+
+async function main() {
+  try {
+    await fixQuickBaseSpec();
+  } catch (error) {
+    console.error("Fatal error in script execution:", error);
+    process.exit(1);
+  }
+}
+
+main();

package/open-api/generate-unified-interface.ts

@@ -0,0 +1,277 @@
+// open-api/generate-unified-interface.ts
+
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  readdirSync,
+} from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { OpenAPIV2 } from "openapi-types";
+import { simplifyName } from "../src/utils.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SPEC_FILE = join(__dirname, "output", "quickbase-fixed.json");
+const OUTPUT_DIR = join(__dirname, "..", "src", "generated-unified");
+const OUTPUT_FILE = join(OUTPUT_DIR, "QuickbaseClient.ts");
+const MODELS_DIR = join(__dirname, "..", "src", "generated", "models");
+
+function mapOpenApiTypeToTs(
+  openApiType: string | string[] | undefined
+): string {
+  const type = Array.isArray(openApiType)
+    ? openApiType[0]
+    : openApiType || "any";
+  switch (type.toLowerCase()) {
+    case "integer":
+    case "int":
+    case "number":
+      return "number";
+    case "string":
+      return "string";
+    case "boolean":
+      return "boolean";
+    default:
+      return "any";
+  }
+}
+
+function mapRefToType(
+  schema: OpenAPIV2.SchemaObject | OpenAPIV2.ReferenceObject | undefined,
+  modelImports: Set<string>,
+  spec: OpenAPIV2.Document,
+  depth: number = 0,
+  availableModels: string[],
+  missingTypes: Set<string>
+): string {
+  if (!schema) return "any";
+
+  if ("$ref" in schema && schema.$ref) {
+    const refParts = schema.$ref.split("/");
+    const model = refParts[refParts.length - 1];
+    const pascalModel = model.charAt(0).toUpperCase() + model.slice(1);
+    const camelModel = model.charAt(0).toLowerCase() + model.slice(1);
+    if (availableModels.includes(pascalModel)) {
+      modelImports.add(pascalModel);
+      return pascalModel;
+    } else if (availableModels.includes(camelModel)) {
+      modelImports.add(camelModel);
+      return camelModel;
+    }
+    missingTypes.add(pascalModel);
+    console.warn(
+      `Type ${pascalModel} not found in /generated/models, defaulting to 'any'`
+    );
+    return "any";
+  }
+
+  if ("type" in schema) {
+    if (schema.type === "object" && schema.properties) {
+      const props = schema.properties;
+      if (props.data && props.data.format === "binary") {
+        return "ArrayBuffer"; // Map binary object to ArrayBuffer
+      }
+      if (props.content && props.content.format === "yaml") {
+        return "string"; // Map YAML object to string
+      }
+      const propTypes = Object.entries(props).map(([key, prop]) => {
+        const propSchema = prop as OpenAPIV2.SchemaObject;
+        const propType = mapRefToType(
+          propSchema,
+          modelImports,
+          spec,
+          depth + 1,
+          availableModels,
+          missingTypes
+        );
+        return `${key}${propSchema.required ? "" : "?"}: ${propType}`;
+      });
+      return `{ ${propTypes.join("; ")} }`;
+    }
+    if (schema.type === "array" && schema.items) {
+      const items = schema.items as
+        | OpenAPIV2.SchemaObject
+        | OpenAPIV2.ReferenceObject;
+      const itemType = mapRefToType(
+        items,
+        modelImports,
+        spec,
+        depth + 1,
+        availableModels,
+        missingTypes
+      );
+      return `${itemType}[]`;
+    }
+    if (schema.type === "object" && schema.additionalProperties) {
+      const additionalProps = schema.additionalProperties as
+        | OpenAPIV2.SchemaObject
+        | OpenAPIV2.ReferenceObject
+        | boolean;
+      if (typeof additionalProps === "boolean") {
+        return "{ [key: string]: any }";
+      }
+      const valueType = mapRefToType(
+        additionalProps,
+        modelImports,
+        spec,
+        depth + 1,
+        availableModels,
+        missingTypes
+      );
+      return `{ [key: string]: ${valueType} }`;
+    }
+    return mapOpenApiTypeToTs(schema.type);
+  }
+
+  return "any";
+}
+
+function generateInterface() {
+  if (!existsSync(SPEC_FILE)) {
+    console.error(
+      `Spec file ${SPEC_FILE} not found. Run 'npm run fix-spec' first.`
+    );
+    process.exit(1);
+  }
+
+  console.log("Generating unified QuickbaseClient interface...");
+  const spec = JSON.parse(
+    readFileSync(SPEC_FILE, "utf8")
+  ) as OpenAPIV2.Document;
+  const { paths } = spec;
+
+  const availableModels = readdirSync(MODELS_DIR)
+    .filter((file) => file.endsWith(".ts") && !file.startsWith("index"))
+    .map((file) => file.replace(".ts", ""));
+  console.log("Available models:", availableModels);
+
+  const modelImports = new Set<string>();
+  const missingTypes = new Set<string>();
+  const methods: string[] = [];
+
+  for (const [path, methodsObj] of Object.entries(
+    paths as OpenAPIV2.PathsObject
+  )) {
+    if (!methodsObj) continue;
+
+    for (const [method, operation] of Object.entries(
+      methodsObj as OpenAPIV2.PathItemObject
+    )) {
+      const op = operation as OpenAPIV2.OperationObject | undefined;
+      if (!op || !op.operationId) continue;
+
+      const opId = simplifyName(op.operationId);
+      const summary = op.summary || "No description available.";
+      const params = (op.parameters || [])
+        .filter((p) => {
+          const param = p as OpenAPIV2.Parameter;
+          return !["QB-Realm-Hostname", "Authorization", "User-Agent"].includes(
+            "name" in param ? param.name : ""
+          );
+        })
+        .map((param: OpenAPIV2.Parameter) => {
+          if (!("name" in param)) return "";
+          let type: string;
+          if ("schema" in param && param.schema) {
+            type = mapRefToType(
+              param.schema,
+              modelImports,
+              spec,
+              1,
+              availableModels,
+              missingTypes
+            );
+          } else if ("type" in param && param.type) {
+            type = mapOpenApiTypeToTs(param.type);
+          } else {
+            console.warn(
+              `Parameter ${param.name} in ${opId} has no type or schema, defaulting to 'any'`
+            );
+            type = "any";
+          }
+          const paramName = param.in === "body" ? "body" : param.name;
+          return `${paramName}${param.required ? "" : "?"}: ${type}`;
+        })
+        .filter((param) => param !== "")
+        .join("; ");
+
+      const successResponses = ["200", "207"]
+        .map((code) => ({
+          code,
+          response: op.responses?.[code] as
+            | OpenAPIV2.ResponseObject
+            | undefined,
+        }))
+        .filter(({ response }) => response?.schema);
+      const returnTypes = successResponses.map(({ response }) =>
+        mapRefToType(
+          response!.schema,
+          modelImports,
+          spec,
+          1,
+          availableModels,
+          missingTypes
+        )
+      );
+      const uniqueReturnTypes = [...new Set(returnTypes)];
+      const returnType =
+        uniqueReturnTypes.length > 1
+          ? uniqueReturnTypes.join(" | ")
+          : uniqueReturnTypes[0] || "void";
+
+      const jsDoc = [
+        `  /**`,
+        `   * ${summary}`,
+        `   * @param params - Parameters for the ${opId} operation`,
+        `   * @returns A promise resolving to the ${opId} response`,
+        `   */`,
+      ].join("\n");
+
+      methods.push(
+        `${jsDoc}\n  ${opId}: (params: { ${params} }) => Promise<${returnType}>;`
+      );
+    }
+  }
+
+  // Always write the missing-types-report.json to reflect the current state
+  if (missingTypes.size > 0) {
+    console.log(
+      "Missing types detected (defaulted to 'any'):",
+      Array.from(missingTypes)
+    );
+  } else {
+    console.log("No missing types detected.");
+  }
+  writeFileSync(
+    join(OUTPUT_DIR, "missing-types-report.json"),
+    JSON.stringify({ missingTypes: Array.from(missingTypes) }, null, 2)
+  );
+  console.log("Missing types report saved to missing-types-report.json");
+
+  const importStatement =
+    modelImports.size > 0
+      ? `import { ${Array.from(modelImports)
+          .sort()
+          .join(", ")} } from "../generated/models";`
+      : "";
+  console.log(`Imports: ${Array.from(modelImports).join(", ")}`);
+
+  const interfaceContent = `// Generated on ${new Date().toISOString()}\n${importStatement}\n\nexport interface QuickbaseClient {\n${methods.join(
+    "\n"
+  )}\n}\n`;
+
+  if (!existsSync(OUTPUT_DIR)) {
+    mkdirSync(OUTPUT_DIR, { recursive: true });
+  }
+  writeFileSync(OUTPUT_FILE, interfaceContent, "utf8");
+  console.log(`Generated ${OUTPUT_FILE}`);
+}
+
+try {
+  generateInterface();
+} catch (error) {
+  console.error("Generation failed:", error);
+  process.exit(1);
+}