quickbase-js 0.1.0-beta.10

package/open-api/schema/tags/records.ts

@@ -0,0 +1,115 @@
+// open-api/schema/tags/records.ts
+import { Operation, Parameter, Spec } from "../../types/spec.ts";
+import { normalizeDefinitionName } from "../../utils/naming.ts"; // Ensure this import is present
+
+export function enhanceRecords(
+  spec: Spec,
+  pathKey: string,
+  method: string,
+  operation: Operation
+): void {
+  const opId =
+    operation.operationId || `${method}${pathKey.replace(/\W/g, "")}`;
+  if (operation.parameters && operation.tags?.includes("Records")) {
+    operation.parameters.forEach((param: Parameter) => {
+      if (param.in === "body") {
+        if (!param.schema) param.schema = {};
+        let requestName =
+          param.schema.$ref?.split("/").pop() || `${opId}Request`;
+        requestName = normalizeDefinitionName(requestName);
+
+        if (
+          !spec.definitions[requestName] ||
+          !spec.definitions[requestName].type ||
+          Object.keys(spec.definitions[requestName]?.properties || {})
+            .length === 0
+        ) {
+          console.log(
+            `Defining schema for ${requestName} in ${pathKey}(${method})`
+          );
+          let properties;
+          // Upsert endpoint (/records)
+          if (pathKey === "/records" && method === "post") {
+            properties = {
+              data: { type: "array", items: { $ref: "#/definitions/Record" } },
+              to: { type: "string" },
+              fieldsToReturn: { type: "array", items: { type: "integer" } },
+            };
+          }
+          // Query endpoint (/records/query)
+          else if (pathKey === "/records/query" && method === "post") {
+            properties = {
+              from: { type: "string", description: "The table identifier." },
+              select: {
+                type: "array",
+                items: { type: "integer" },
+                description: "An array of field ids...",
+              },
+              where: {
+                type: "string",
+                description:
+                  "The filter, using the Quickbase query language...",
+              },
+              sortBy: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    fieldId: { type: "integer" },
+                    order: {
+                      type: "string",
+                      enum: ["ASC", "DESC", "equal-values"],
+                    },
+                  },
+                  required: ["fieldId", "order"],
+                },
+                description: "An array of field IDs and sort directions...",
+              },
+              groupBy: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    fieldId: { type: "integer" },
+                    grouping: { type: "string", enum: ["equal-values"] },
+                  },
+                  required: ["fieldId", "grouping"],
+                },
+                description:
+                  "An array that contains the fields to group the records by.",
+              },
+              options: {
+                type: "object",
+                properties: {
+                  skip: { type: "integer" },
+                  top: { type: "integer" },
+                  compareWithAppLocalTime: { type: "boolean" },
+                },
+                description: "Additional query options.",
+              },
+            };
+          }
+          // Delete endpoint (/records)
+          else if (method === "delete") {
+            properties = {
+              from: { type: "string" },
+              where: { type: "string" },
+            };
+          }
+          if (properties) {
+            spec.definitions[requestName] = {
+              type: "object",
+              properties,
+              required: ["from"], // Only 'from' is required per the spec
+              description: operation.summary || `Request body for ${opId}`,
+            };
+          }
+        }
+        param.schema = { $ref: `#/definitions/${requestName}` };
+        console.log(
+          `Ensured ${requestName} in definitions for ${pathKey}(${method})`
+        );
+      }
+    });
+  }
+}

package/open-api/schema/tags/tables.ts

@@ -0,0 +1,211 @@
+// schema/tags/tables.ts
+import { Operation, Parameter, Spec } from "../../types/spec.ts";
+import { normalizeDefinitionName } from "../../utils/naming.ts";
+
+export function enhanceTables(
+  spec: Spec,
+  pathKey: string,
+  method: string,
+  operation: Operation
+): void {
+  const opId =
+    operation.operationId || `${method}${pathKey.replace(/\W/g, "")}`;
+  if (operation.parameters && operation.tags?.includes("Tables")) {
+    operation.parameters.forEach((param: Parameter) => {
+      if (param.in === "body") {
+        if (!param.schema) param.schema = {};
+        let requestName =
+          param.schema.$ref?.split("/").pop() || `${opId}Request`;
+        requestName = normalizeDefinitionName(requestName);
+
+        if (
+          !spec.definitions[requestName] ||
+          !spec.definitions[requestName].type ||
+          Object.keys(spec.definitions[requestName]?.properties || {})
+            .length === 0
+        ) {
+          console.log(
+            `Defining schema for ${requestName} in ${pathKey}(${method})`
+          );
+          let properties;
+
+          // Existing logic for other endpoints remains unchanged
+          if (pathKey === "/tables" && method === "post") {
+            properties = {
+              name: {
+                type: "string",
+                description: "The name for the table.",
+                minLength: 1,
+              },
+              description: {
+                type: "string",
+                description: "The description for the table...",
+              },
+              singleRecordName: {
+                type: "string",
+                description: "The singular noun for records...",
+              },
+              pluralRecordName: {
+                type: "string",
+                description: "The plural noun for records...",
+              },
+            };
+          } else if (pathKey === "/tables/{tableId}" && method === "post") {
+            properties = {
+              name: {
+                type: "string",
+                description: "The updated name of the table.",
+              },
+              description: {
+                type: "string",
+                description: "The updated description for the table.",
+              },
+            };
+          }
+          // Add minimal fix for relationship endpoints
+          else if (
+            pathKey === "/tables/{tableId}/relationship" &&
+            method === "post"
+          ) {
+            requestName = "CreateRelationshipRequest"; // Force correct name
+            if (!spec.definitions[requestName]) {
+              properties = {
+                parentTableId: {
+                  type: "string",
+                  description: "The parent table id for the relationship.",
+                },
+                foreignKeyField: {
+                  type: "object",
+                  properties: {
+                    label: {
+                      type: "string",
+                      description: "The label for the foreign key field.",
+                    },
+                  },
+                  additionalProperties: true,
+                },
+                lookupFieldIds: {
+                  type: "array",
+                  items: { type: "integer" },
+                  description: "Array of field ids...",
+                },
+                summaryFields: {
+                  type: "array",
+                  items: {
+                    type: "object",
+                    properties: {
+                      summaryFid: {
+                        type: "number",
+                        description: "The field id to summarize.",
+                      },
+                      label: {
+                        type: "string",
+                        description: "The label for the summary field.",
+                      },
+                      accumulationType: {
+                        type: "string",
+                        enum: [
+                          "AVG",
+                          "SUM",
+                          "MAX",
+                          "MIN",
+                          "STD-DEV",
+                          "COUNT",
+                          "COMBINED-TEXT",
+                          "COMBINED-USER",
+                          "DISTINCT-COUNT",
+                        ],
+                        description: "The accumulation type...",
+                      },
+                      where: { type: "string", description: "The filter..." },
+                    },
+                    required: ["accumulationType"],
+                    additionalProperties: true,
+                  },
+                  description: "Array of summary field objects...",
+                },
+              };
+            }
+          } else if (
+            pathKey === "/tables/{tableId}/relationship/{relationshipId}" &&
+            method === "post"
+          ) {
+            requestName = "UpdateRelationshipRequest"; // Force correct name
+            if (!spec.definitions[requestName]) {
+              properties = {
+                parentTableId: {
+                  type: "string",
+                  description: "The updated parent table id...",
+                },
+                foreignKeyField: {
+                  type: "object",
+                  properties: {
+                    label: {
+                      type: "string",
+                      description: "The updated label...",
+                    },
+                  },
+                  additionalProperties: true,
+                },
+                lookupFieldIds: {
+                  type: "array",
+                  items: { type: "integer" },
+                  description: "Updated array of field ids...",
+                },
+                summaryFields: {
+                  type: "array",
+                  items: {
+                    type: "object",
+                    properties: {
+                      summaryFid: { type: "number" },
+                      label: { type: "string" },
+                      accumulationType: {
+                        type: "string",
+                        enum: [
+                          "AVG",
+                          "SUM",
+                          "MAX",
+                          "MIN",
+                          "STD-DEV",
+                          "COUNT",
+                          "COMBINED-TEXT",
+                          "COMBINED-USER",
+                          "DISTINCT-COUNT",
+                        ],
+                      },
+                      where: { type: "string" },
+                    },
+                    required: ["accumulationType"],
+                    additionalProperties: true,
+                  },
+                },
+              };
+            }
+          }
+
+          if (properties) {
+            spec.definitions[requestName] = {
+              type: "object",
+              properties,
+              required:
+                pathKey.includes("relationship") &&
+                pathKey.endsWith("/relationship")
+                  ? ["parentTableId"]
+                  : pathKey === "/tables"
+                  ? ["name"]
+                  : [],
+              additionalProperties: pathKey.includes("relationship")
+                ? false
+                : true, // Match raw spec
+              description: operation.summary || `Request body for ${opId}`,
+            };
+          }
+        }
+        param.schema = { $ref: `#/definitions/${requestName}` };
+        console.log(
+          `Ensured ${requestName} in definitions for ${pathKey}(${method})`
+        );
+      }
+    });
+  }
+}

package/open-api/schema/tags/users.ts

@@ -0,0 +1,47 @@
+// schema/tags/users.ts
+import { Operation, Parameter, Spec } from "../../types/spec.ts";
+import { normalizeDefinitionName } from "../../utils/naming.ts";
+
+export function enhanceUsers(
+  spec: Spec,
+  pathKey: string,
+  method: string,
+  operation: Operation
+): void {
+  const opId =
+    operation.operationId || `${method}${pathKey.replace(/\W/g, "")}`;
+  if (operation.parameters && operation.tags?.includes("Users")) {
+    operation.parameters.forEach((param: Parameter) => {
+      if (param.in === "body") {
+        if (!param.schema) param.schema = {};
+        let requestName =
+          param.schema.$ref?.split("/").pop() || `${opId}Request`;
+        requestName = normalizeDefinitionName(requestName);
+
+        if (
+          !spec.definitions[requestName] ||
+          !spec.definitions[requestName].type ||
+          Object.keys(spec.definitions[requestName]?.properties || {})
+            .length === 0
+        ) {
+          console.log(
+            `Defining schema for ${requestName} in ${pathKey}(${method})`
+          );
+          const properties = {
+            userIds: { type: "array", items: { type: "string" } },
+          };
+          spec.definitions[requestName] = {
+            type: "object",
+            properties,
+            required: Object.keys(properties),
+            description: operation.summary || `Request body for ${opId}`,
+          };
+        }
+        param.schema = { $ref: `#/definitions/${requestName}` };
+        console.log(
+          `Ensured ${requestName} in definitions for ${pathKey}(${method})`
+        );
+      }
+    });
+  }
+}

package/open-api/types/spec.ts

@@ -0,0 +1,42 @@
+// open-api/types/spec.ts
+export interface Parameter {
+  name: string;
+  in: string;
+  required?: boolean;
+  type?: string;
+  schema?: {
+    type?: string;
+    items?: any;
+    $ref?: string;
+    properties?: any;
+    example?: any;
+  };
+  example?: any;
+}
+
+export interface Operation {
+  parameters?: Parameter[];
+  responses?: Record<
+    string,
+    { description: string; schema?: any; "x-amf-mediaType"?: string }
+  >;
+  operationId?: string;
+  summary?: string;
+  tags?: string[];
+}
+
+export interface Spec {
+  paths: Record<string, Record<string, Operation>>;
+  definitions: Record<string, any>; // Required, no longer optional
+  swagger: string;
+  info: any;
+  operations?: any;
+  groups?: any;
+  components?: any;
+}
+
+export interface FixSpecConfig {
+  applyOverrides?: boolean;
+  overridePaths?: string[];
+  overrideDefinitions?: string[];
+}

package/open-api/utils/common.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { dirname } from "path";
+
+export function writeFileSafe(
+  filePath: string,
+  content: string,
+  encoding: BufferEncoding = "utf8"
+): void {
+  console.log(`writeFileSafe: Writing to ${filePath}`);
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    console.log(`writeFileSafe: Creating directory ${dir}`);
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(filePath, content, encoding);
+}
+
+export function runTask(taskName: string, task: () => void): void {
+  console.log(`runTask: Starting ${taskName}`);
+  try {
+    task();
+    console.log(`runTask: ${taskName} completed`);
+  } catch (error) {
+    console.error(`runTask: Error in ${taskName}:`, error);
+    process.exit(1);
+  }
+}

package/open-api/utils/generateJsDoc.ts

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+import { ParamDetail, PropertyDetail, JsDocOptions } from "./sharedUtils.ts";
+import { getPropertyDescription } from "./sharedUtils.ts";
+
+export function generateJsDoc({
+  summary,
+  opId,
+  paramDetails,
+  returnType,
+  returnTypeDetails,
+  docLink,
+}: JsDocOptions): string {
+  const jsDocLines: string[] = [`  /**`, `   * ${summary}`, `   *`];
+
+  if (paramDetails.length > 0) {
+    jsDocLines.push(
+      `   * @param {Object} params - Object containing the parameters for ${opId}.`
+    );
+    paramDetails.forEach((p) => {
+      const paramDesc = p.description || "No description provided.";
+      const optionalMark = p.required ? "" : " (Optional)";
+      jsDocLines.push(
+        `   * @param {${p.type}} ${p.required ? "" : "["}params.${p.name}${
+          p.required ? "" : "]"
+        } - ${paramDesc}${optionalMark}`
+      );
+      if (p.properties.length > 0) {
+        p.properties.forEach((prop) => {
+          const propDesc = getPropertyDescription(prop);
+          jsDocLines.push(
+            `   *   - **${prop.name}** (\`${prop.type}\`, ${
+              prop.required ? "required" : "optional"
+            }) - ${propDesc}`
+          );
+        });
+      }
+    });
+  } else {
+    jsDocLines.push(`   * No parameters.`);
+  }
+
+  jsDocLines.push(`   *`);
+  if (returnTypeDetails.length > 0) {
+    jsDocLines.push(
+      `   * @returns {Promise<${returnType}>} - Promise resolving to the ${opId} response.`
+    );
+    const renderProperties = (props: PropertyDetail[], indent: string) => {
+      props.forEach((prop) => {
+        const propDesc = getPropertyDescription(prop);
+        jsDocLines.push(
+          `${indent}*   - **${prop.name}** (\`${prop.type}\`, ${
+            prop.required ? "required" : "optional"
+          }) - ${propDesc}`
+        );
+        if (prop.properties && prop.properties.length > 0) {
+          renderProperties(prop.properties, `${indent}*     `);
+        }
+      });
+    };
+    renderProperties(returnTypeDetails, `   `);
+  } else {
+    jsDocLines.push(
+      `   * @returns {Promise<${returnType}>} - Promise resolving to the ${opId} response.`
+    );
+  }
+
+  jsDocLines.push(
+    `   *`,
+    `   * @see ${docLink} - Official Quickbase API documentation`
+  );
+  jsDocLines.push(`   */`);
+  return jsDocLines.join("\n");
+}

package/open-api/utils/infer-schema.ts

@@ -0,0 +1,40 @@
+// utils/infer-schema.ts
+export function inferSchema(example: any, operationId?: string): any {
+  if (!example || typeof example !== "object") {
+    return { type: "string" };
+  }
+  if (Array.isArray(example)) {
+    return {
+      type: "array",
+      items:
+        example.length > 0
+          ? inferSchema(example[0], operationId)
+          : { type: "string" },
+    };
+  }
+  const properties: Record<string, any> = {};
+  for (const [key, value] of Object.entries(example)) {
+    if (Array.isArray(value)) {
+      properties[key] = {
+        type: "array",
+        items:
+          value.length > 0
+            ? inferSchema(value[0], operationId)
+            : { type: "string" },
+      };
+    } else if (typeof value === "object" && value !== null) {
+      properties[key] = inferSchema(value, operationId);
+    } else {
+      properties[key] = {
+        type:
+          typeof value === "object" && value === null
+            ? "object"
+            : typeof value || "string",
+      };
+    }
+  }
+  if (operationId && operationId.endsWith("200Response")) {
+    return { type: "array", items: { type: "object", properties } };
+  }
+  return { type: "object", properties };
+}

package/open-api/utils/naming.ts

@@ -0,0 +1,10 @@
+// utils/naming.ts
+export function toCamelCase(str: string): string {
+  return str
+    .replace(/[-_](.)/g, (_, char) => char.toUpperCase())
+    .replace(/^./, (str) => str.toLowerCase());
+}
+
+export function normalizeDefinitionName(name: string): string {
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}