quickbase-js 0.1.0-beta.9 → 1.0.0

package/examples/vanillajs.html

@@ -1,47 +0,0 @@
-<!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/open-api/fix-spec-main.ts

@@ -1,97 +0,0 @@
-#!/usr/bin/env node
-import { promises as fs } from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
-import * as glob from "glob";
-import { Spec } from "./types/spec.ts";
-import { toCamelCase } from "./utils/naming.ts";
-
-async function fixQuickBaseSpec(): Promise<void> {
-  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"));
-  console.log("Spec files:", specFiles);
-
-  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");
-  console.log("File read successfully");
-  const spec: Spec = JSON.parse(specContent);
-  console.log("JSON parsed successfully");
-
-  if (!spec.definitions || typeof spec.definitions !== "object") {
-    spec.definitions = {};
-  }
-  console.log("Spec definitions after initialization:", spec.definitions);
-
-  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}`
-              );
-            }
-            return param;
-          });
-      }
-    }
-  }
-
-  console.log("Spec definitions before enhanceTags:", spec.definitions);
-  console.log("Enhancing raw spec with tags...");
-  const { enhanceTags } = await import("./schema/tags/index.ts"); // Updated to index.ts
-  enhanceTags(spec);
-  console.log("Enhancing raw spec with general enhancements...");
-  const { enhanceGeneral } = await import("./schema/enhance-general.ts");
-  enhanceGeneral(spec);
-  console.log("Fixing array schemas...");
-  const { fixArrays } = await import("./schema/fix-arrays.ts");
-  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);
-}
-
-async function main() {
-  try {
-    console.log("Starting...");
-    await fixQuickBaseSpec();
-  } catch (error) {
-    console.error("Error:", error);
-    process.exit(1);
-  }
-}
-
-main();

package/open-api/generate-override-report.ts

@@ -1,214 +0,0 @@
-#!/usr/bin/env node
-
-import { promises as fs } from "fs";
-import * as path from "path";
-import { fileURLToPath } from "url";
-import fastJsonPatch, { AddOperation } from "fast-json-patch";
-import { Spec } from "./types/spec";
-
-const { compare, applyPatch } = fastJsonPatch;
-
-// Basic CSS for readability
-const HTML_STYLE = `
-  <style>
-    .jsondiffpatch-delta { font-family: monospace; }
-    .jsondiffpatch-added { background-color: #e6ffe6; color: #006400; }
-    .jsondiffpatch-deleted { background-color: #ffe6e6; color: #8b0000; text-decoration: line-through; }
-    .jsondiffpatch-modified { background-color: #fff3e6; }
-    .jsondiffpatch-unchanged { color: #666; }
-    .jsondiffpatch-key { font-weight: bold; }
-    .jsondiffpatch-tags { color: purple; font-style: italic; }
-  </style>
-`;
-
-// Helper to decode JSON Pointer paths
-function decodeJsonPointer(jsonPointerSegment: string): string {
-  // Split the full path and decode each segment
-  const segments = jsonPointerSegment.split("/").filter(Boolean);
-  const decodedSegments = segments.map((seg) =>
-    seg.replace("~1", "/").replace("~0", "~")
-  );
-  // Remove "paths" prefix and join with a single leading slash
-  const pathIndex = decodedSegments.indexOf("paths");
-  const relevantSegments =
-    pathIndex !== -1 && pathIndex + 1 < decodedSegments.length
-      ? decodedSegments.slice(pathIndex + 1)
-      : decodedSegments;
-  return "/" + relevantSegments.join("/"); // Ensure single leading slash
-}
-
-// Enhanced HTML formatter with clean paths, tags, and old vs. new values
-function formatPatchToHtml(patch: any[], spec: Spec): string {
-  let html = `<html><head><title>Override Report Diff</title>${HTML_STYLE}</head><body><h1>Override Report Diff</h1>`;
-  patch.forEach((op) => {
-    const pathParts = op.path.split("/").filter(Boolean);
-    const lastPart = pathParts[pathParts.length - 1];
-    let oldValue = "N/A";
-    let context = decodeJsonPointer(op.path);
-    let method = op.method ? op.method.toUpperCase() : "";
-
-    if (method) context = context.replace(`/${method}`, "") + ` [${method}]`;
-
-    if (op.op === "replace" || op.op === "remove") {
-      const reversePatch: AddOperation<any>[] = [
-        { op: "add", path: op.path, value: op.value },
-      ];
-      const tempSpec = JSON.parse(JSON.stringify(spec));
-      applyPatch(tempSpec, reversePatch);
-      const pathSegments = op.path.split("/").slice(1);
-      oldValue =
-        pathSegments.reduce((obj: any, key: string) => obj?.[key], tempSpec) ||
-        "N/A";
-      oldValue = JSON.stringify(oldValue);
-    }
-
-    const tagDisplay =
-      op.tags && op.tags.length > 0 ? ` (Tags: ${op.tags.join(", ")})` : "";
-
-    if (op.op === "replace") {
-      html += `<h2>Path: ${context}${tagDisplay}</h2><p>Modified: <span class="jsondiffpatch-deleted">${oldValue}</span> → <span class="jsondiffpatch-added">${JSON.stringify(
-        op.value
-      )}</span></p>`;
-    } else if (op.op === "add") {
-      html += `<h2>Path: ${context}${tagDisplay}</h2><p>Added: <span class="jsondiffpatch-added">${JSON.stringify(
-        op.value
-      )}</span></p>`;
-    } else if (op.op === "remove") {
-      html += `<h2>Path: ${context}${tagDisplay}</h2><p>Removed: <span class="jsondiffpatch-deleted">${oldValue}</span></p>`;
-    }
-  });
-  html += "</body></html>";
-  return html;
-}
-
-async function generateOverrideReport(): Promise<void> {
-  try {
-    const CODEGEN_DIR: string = path.dirname(fileURLToPath(import.meta.url));
-    const SPECS_DIR: string = path.join(CODEGEN_DIR, "..", "specs");
-    const OUTPUT_DIR: string = path.join(CODEGEN_DIR, "output");
-    const RAW_SPEC: string = path.join(
-      SPECS_DIR,
-      "QuickBase_RESTful_API_2025-03-04T06_22_39.725Z.json"
-    );
-    const FIXED_SPEC: string = path.join(OUTPUT_DIR, "quickbase-fixed.json");
-    const JSON_OUTPUT_FILE: string = path.join(
-      OUTPUT_DIR,
-      "override-report.json"
-    );
-    const HTML_OUTPUT_FILE: string = path.join(
-      OUTPUT_DIR,
-      "override-report.html"
-    );
-
-    console.log("Cleaning up old override report...");
-    if (
-      await fs
-        .stat(JSON_OUTPUT_FILE)
-        .then(() => true)
-        .catch(() => false)
-    ) {
-      await fs.unlink(JSON_OUTPUT_FILE);
-      console.log(`Removed ${JSON_OUTPUT_FILE}`);
-    }
-    if (
-      await fs
-        .stat(HTML_OUTPUT_FILE)
-        .then(() => true)
-        .catch(() => false)
-    ) {
-      await fs.unlink(HTML_OUTPUT_FILE);
-      console.log(`Removed ${HTML_OUTPUT_FILE}`);
-    } else {
-      console.log("No old override reports found to remove.");
-    }
-
-    if (
-      !(await fs
-        .stat(RAW_SPEC)
-        .then(() => true)
-        .catch(() => false))
-    ) {
-      console.error(`Raw spec ${RAW_SPEC} not found.`);
-      process.exit(1);
-    }
-    if (
-      !(await fs
-        .stat(FIXED_SPEC)
-        .then(() => true)
-        .catch(() => false))
-    ) {
-      console.error(
-        `Fixed spec ${FIXED_SPEC} not found. Run 'npm run fix-spec' first.`
-      );
-      process.exit(1);
-    }
-
-    console.log(`Reading raw spec from ${RAW_SPEC}...`);
-    const rawContent = await fs.readFile(RAW_SPEC, "utf8");
-    const rawSpec: Spec = JSON.parse(rawContent);
-
-    console.log(`Reading fixed spec from ${FIXED_SPEC}...`);
-    const fixedContent = await fs.readFile(FIXED_SPEC, "utf8");
-    const fixedSpec: Spec = JSON.parse(fixedContent);
-
-    console.log("Generating patch...");
-    const patch = compare(rawSpec, fixedSpec);
-
-    // Enhance patch with decoded paths and tags inferred from parent operation
-    const enhancedPatch = patch.map((op) => {
-      let decodedPath = decodeJsonPointer(op.path);
-      let tags: string[] = [];
-      let method: string = "";
-
-      if (op.path.startsWith("/paths")) {
-        const pathParts = op.path.split("/").filter(Boolean);
-        if (
-          pathParts.length >= 3 &&
-          ["get", "post", "put", "delete"].includes(pathParts[2].toLowerCase())
-        ) {
-          const fullPathSegment = "/paths/" + pathParts[1];
-          const basePath = decodeJsonPointer(fullPathSegment);
-          method = pathParts[2];
-          console.log(`Debug: basePath=${basePath}, method=${method}`); // Debug log
-          if (rawSpec.paths[basePath]?.[method]?.tags) {
-            tags = rawSpec.paths[basePath][method].tags || [];
-          } else if (rawSpec.paths[basePath]?.[method]) {
-            console.log(`No tags found for ${basePath} [${method}]`);
-          } else {
-            console.log(`Operation not found: ${basePath} [${method}]`);
-          }
-        }
-      }
-
-      return {
-        ...op,
-        decodedPath,
-        tags: tags.length > 0 ? tags : undefined,
-        method,
-      };
-    });
-
-    console.log("Writing JSON override report...");
-    await fs.mkdir(OUTPUT_DIR, { recursive: true });
-    await fs.writeFile(
-      JSON_OUTPUT_FILE,
-      JSON.stringify(enhancedPatch, null, 2),
-      "utf8"
-    );
-
-    console.log("Writing HTML override report...");
-    const htmlContent = formatPatchToHtml(enhancedPatch, rawSpec);
-    await fs.writeFile(HTML_OUTPUT_FILE, htmlContent, "utf8");
-
-    console.log("Override report generated successfully!");
-  } catch (error) {
-    console.error("Failed to generate override report:", error);
-    process.exit(1);
-  }
-}
-
-async function main() {
-  await generateOverrideReport();
-}
-
-main();

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

@@ -1,336 +0,0 @@
-#!/usr/bin/env node
-console.log("Script started");
-
-import {
-  readFileSync,
-  writeFileSync,
-  mkdirSync,
-  existsSync,
-  readdirSync,
-} from "fs";
-console.log("FS modules imported");
-
-import { join, dirname } from "path";
-console.log("Path modules imported");
-
-import { fileURLToPath } from "url";
-console.log("URL module imported");
-
-import { OpenAPIV2 } from "openapi-types";
-console.log("openapi-types imported");
-
-import { Project } from "ts-morph";
-console.log("ts-morph imported");
-
-import { generateJsDoc } from "./utils/generateJsDoc.js";
-
-const simplifyName = (str: string): string => str;
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-console.log("__dirname set:", __dirname);
-
-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);
-    if (availableModels.includes(pascalModel)) {
-      modelImports.add(pascalModel);
-      return pascalModel;
-    }
-    missingTypes.add(pascalModel);
-    console.warn(`Type ${pascalModel} not found, defaulting to 'any'`);
-    return "any";
-  }
-
-  if ("type" in schema) {
-    if (schema.type === "object" && schema.properties) {
-      const props = schema.properties;
-      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}[]`;
-    }
-    return mapOpenApiTypeToTs(schema.type);
-  }
-
-  return "any";
-}
-
-interface PropertyDetail {
-  name: string;
-  type: string;
-  required: boolean;
-  jsdoc?: string;
-}
-
-function parseInterfaceProperties(
-  modelName: string,
-  modelsDir: string
-): PropertyDetail[] {
-  const project = new Project();
-  const filePath = join(modelsDir, `${modelName}.ts`);
-  if (!existsSync(filePath)) {
-    console.warn(`Model file ${filePath} not found for ${modelName}`);
-    return [];
-  }
-
-  const sourceFile = project.addSourceFileAtPath(filePath);
-  const interfaceDec = sourceFile.getInterface(modelName);
-  if (!interfaceDec) {
-    console.warn(`Interface ${modelName} not found in ${filePath}`);
-    return [];
-  }
-
-  return interfaceDec.getProperties().map((prop) => {
-    const jsDocs = prop.getJsDocs();
-    const jsdocText =
-      jsDocs.length > 0 ? jsDocs[0].getDescription().trim() : undefined;
-    return {
-      name: prop.getName(),
-      type: prop.getType().getText(prop),
-      required: !prop.hasQuestionToken(),
-      jsdoc: jsdocText,
-    };
-  });
-}
-
-interface ParamDetail {
-  name: string;
-  type: string;
-  required: boolean;
-  properties: PropertyDetail[];
-}
-
-function generateInterface(includeResponseProperties: boolean = false): void {
-  console.log(
-    "Generating interface with includeResponseProperties:",
-    includeResponseProperties
-  );
-
-  console.log("Checking spec file:", SPEC_FILE);
-  if (!existsSync(SPEC_FILE)) {
-    console.error(
-      `Spec file ${SPEC_FILE} not found. Run 'npm run fix-spec' first.`
-    );
-    process.exit(1);
-  }
-
-  console.log("Reading spec file...");
-  const specContent = readFileSync(SPEC_FILE, "utf8");
-  const spec: OpenAPIV2.Document = JSON.parse(specContent);
-  console.log("Spec parsed, keys:", Object.keys(spec));
-
-  const { paths } = spec;
-  if (!paths) {
-    console.error("No 'paths' in spec");
-    process.exit(1);
-  }
-
-  console.log("Checking models directory:", MODELS_DIR);
-  if (!existsSync(MODELS_DIR)) {
-    console.error(
-      `Models directory ${MODELS_DIR} not found. Run 'npm run gen:openapi' first.`
-    );
-    process.exit(1);
-  }
-  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.";
-      const docLink = `https://developer.quickbase.com/operation/${op.operationId}`;
-
-      const paramDetails: ParamDetail[] = (op.parameters || [])
-        .filter((p: OpenAPIV2.ParameterObject | OpenAPIV2.ReferenceObject) => {
-          const param = p as OpenAPIV2.ParameterObject;
-          return !["QB-Realm-Hostname", "Authorization", "User-Agent"].includes(
-            param.name || ""
-          );
-        })
-        .map((param: OpenAPIV2.ParameterObject | OpenAPIV2.ReferenceObject) => {
-          const p = param as OpenAPIV2.ParameterObject;
-          if (!p.name) return null;
-          let type = "any";
-          let properties: PropertyDetail[] = [];
-          if ("schema" in p && p.schema) {
-            type = mapRefToType(
-              p.schema,
-              modelImports,
-              spec,
-              1,
-              availableModels,
-              missingTypes
-            );
-            if ("$ref" in p.schema && p.schema.$ref) {
-              const refParts = p.schema.$ref.split("/");
-              const model = refParts[refParts.length - 1];
-              const pascalModel =
-                model.charAt(0).toUpperCase() + model.slice(1);
-              properties = parseInterfaceProperties(pascalModel, MODELS_DIR);
-            }
-          } else if ("type" in p && p.type) {
-            type = mapOpenApiTypeToTs(p.type);
-          }
-          const paramName = p.in === "body" ? "body" : p.name;
-          return {
-            name: paramName,
-            type,
-            required: p.required || false,
-            properties,
-          };
-        })
-        .filter((p): p is ParamDetail => p !== null);
-
-      const params = paramDetails
-        .map((p) => `${p.name}${p.required ? "" : "?"}: ${p.type}`)
-        .join("; ");
-
-      const returnTypes = ["200", "207"]
-        .map(
-          (code) => op.responses?.[code] as OpenAPIV2.ResponseObject | undefined
-        )
-        .filter((response) => response?.schema)
-        .map((response) =>
-          mapRefToType(
-            response!.schema,
-            modelImports,
-            spec,
-            1,
-            availableModels,
-            missingTypes
-          )
-        );
-      const returnType =
-        returnTypes.length > 1
-          ? returnTypes.join(" | ")
-          : returnTypes[0] || "void";
-
-      const returnTypeDetails: PropertyDetail[] =
-        includeResponseProperties &&
-        returnTypes.length === 1 &&
-        returnTypes[0] !== "void"
-          ? parseInterfaceProperties(returnTypes[0], MODELS_DIR)
-          : [];
-
-      const jsDoc = generateJsDoc({
-        summary,
-        opId,
-        paramDetails,
-        returnType,
-        returnTypeDetails,
-        docLink,
-      });
-
-      methods.push(
-        `${jsDoc}\n  ${opId}: (params: { ${params} }) => Promise<${returnType}>;`
-      );
-    }
-  }
-
-  console.log("Writing missing types report...");
-  writeFileSync(
-    join(OUTPUT_DIR, "missing-types-report.json"),
-    JSON.stringify({ missingTypes: Array.from(missingTypes) }, null, 2)
-  );
-
-  const importStatement =
-    modelImports.size > 0
-      ? `import { ${Array.from(modelImports)
-          .sort()
-          .join(", ")} } from "../generated/models";`
-      : "";
-  const interfaceContent = `// Generated on ${new Date().toISOString()}\n${importStatement}\n\nexport interface QuickbaseClient {\n${methods.join(
-    "\n"
-  )}\n}\n`;
-
-  console.log("Ensuring output directory exists...");
-  if (!existsSync(OUTPUT_DIR)) {
-    mkdirSync(OUTPUT_DIR, { recursive: true });
-  }
-  writeFileSync(OUTPUT_FILE, interfaceContent, "utf8");
-  console.log("Generated:", OUTPUT_FILE);
-}
-
-console.log("Entering try block");
-try {
-  generateInterface(true); // Toggle response properties here
-} catch (error) {
-  console.error("Error in generateInterface:", error);
-  process.exit(1);
-}
-
-console.log("Script completed");