quickbase-js 0.1.0-beta.7 → 0.1.0-beta.9

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

@@ -28,11 +28,16 @@ export function enhanceFields(
             `Defining schema for ${requestName} in ${pathKey}(${method})`
           );
           let properties;
+          let requiredFields: string[];
+
           if (method === "delete") {
+            // DELETE /fields (deleteFields)
             properties = {
               fieldIds: { type: "array", items: { type: "integer" } },
             };
+            requiredFields = ["fieldIds"];
           } else {
+            // Common properties for createField and updateField
             properties = {
               label: { type: "string", description: "The label of the field" },
               fieldType: {
@@ -122,27 +127,337 @@ export function enhanceFields(
                 description: "Whether changes to the field are audited",
                 nullable: true,
               },
+              properties: {
+                type: "object",
+                description: "Specific field properties",
+                properties: {
+                  numLines: {
+                    type: "integer",
+                    description:
+                      "The number of lines shown in QuickBase for this text field",
+                  },
+                  maxLength: {
+                    type: "integer",
+                    description:
+                      "The maximum number of characters allowed for entry",
+                  },
+                  appendOnly: {
+                    type: "boolean",
+                    description: "Whether this field is append-only",
+                  },
+                  sortAsGiven: {
+                    type: "boolean",
+                    description:
+                      "Indicates if the listed entries sort as entered vs alphabetically",
+                  },
+                  allowMentions: {
+                    type: "boolean",
+                    description:
+                      "If someone can @mention users in the rich text field",
+                  },
+                  comments: {
+                    type: "string",
+                    description:
+                      "The comments entered on the field properties by an administrator",
+                  },
+                  doesTotal: {
+                    type: "boolean",
+                    description:
+                      "Whether this field totals in reports within the product",
+                  },
+                  autoSave: {
+                    type: "boolean",
+                    description: "Whether the link field will auto save",
+                  },
+                  defaultValueLuid: {
+                    type: "integer",
+                    description: "Default user id value",
+                  },
+                  useI18NFormat: {
+                    type: "boolean",
+                    description:
+                      "Whether phone numbers should be in E.164 standard international format",
+                  },
+                  maxVersions: {
+                    type: "integer",
+                    description:
+                      "The maximum number of versions configured for a file attachment",
+                  },
+                  format: {
+                    type: "integer",
+                    description: "The format to display time",
+                  },
+                  carryChoices: {
+                    type: "boolean",
+                    description:
+                      "Whether the field should carry its multiple choice fields when copied",
+                  },
+                  linkText: {
+                    type: "string",
+                    description:
+                      "The configured text value that replaces the URL users see",
+                  },
+                  parentFieldId: {
+                    type: "integer",
+                    description:
+                      "The id of the parent composite field, when applicable",
+                  },
+                  displayTimezone: {
+                    type: "boolean",
+                    description:
+                      "Indicates whether to display the timezone within the product",
+                  },
+                  summaryTargetFieldId: {
+                    type: "integer",
+                    description:
+                      "The id of the field used to aggregate values from the child",
+                  },
+                  allowNewChoices: {
+                    type: "boolean",
+                    description:
+                      "Indicates if users can add new choices to a selection list",
+                  },
+                  defaultToday: {
+                    type: "boolean",
+                    description:
+                      "Indicates if the field value is defaulted today for new records",
+                  },
+                  units: {
+                    type: "string",
+                    description: "The units label",
+                  },
+                  openTargetIn: {
+                    type: "string",
+                    enum: ["sameWindow", "newWindow", "popup"],
+                    description:
+                      "Indicates which target the URL should open in when clicked",
+                  },
+                  lookupTargetFieldId: {
+                    type: "integer",
+                    description:
+                      "The id of the field that is the target on the parent table for this lookup",
+                  },
+                  summaryFunction: {
+                    type: "string",
+                    enum: [
+                      "AVG",
+                      "SUM",
+                      "MAX",
+                      "MIN",
+                      "STD-DEV",
+                      "COUNT",
+                      "COMBINED-TEXT",
+                      "COMBINED-USER",
+                      "DISTINCT-COUNT",
+                    ],
+                    description: "The accumulation type for the summary field",
+                  },
+                  sourceFieldId: {
+                    type: "integer",
+                    description: "The id of the source field",
+                  },
+                  doesAverage: {
+                    type: "boolean",
+                    description:
+                      "Whether this field averages in reports within the product",
+                  },
+                  formula: {
+                    type: "string",
+                    description:
+                      "The formula of the field as configured in QuickBase",
+                  },
+                  decimalPlaces: {
+                    type: "integer",
+                    description:
+                      "The number of decimal places displayed in the product",
+                  },
+                  defaultCountryCode: {
+                    type: "string",
+                    description:
+                      "Controls the default country shown on international phone widgets",
+                  },
+                  displayMonth: {
+                    type: "string",
+                    description: "How to display months",
+                  },
+                  seeVersions: {
+                    type: "boolean",
+                    description:
+                      "Indicates if users can see other versions of a file attachment",
+                  },
+                  defaultKind: {
+                    type: "string",
+                    description: "The user default type",
+                  },
+                  displayEmail: {
+                    type: "string",
+                    description: "How the email is displayed",
+                  },
+                  coverText: {
+                    type: "string",
+                    description:
+                      "Alternate user-friendly text for displaying a link",
+                  },
+                  currencySymbol: {
+                    type: "string",
+                    description:
+                      "The currency symbol used when displaying field values",
+                  },
+                  summaryQuery: {
+                    type: "string",
+                    description: "The summary query",
+                  },
+                  targetFieldId: {
+                    type: "integer",
+                    description: "The id of the target field",
+                  },
+                  displayUser: {
+                    type: "string",
+                    description: "The configured option for how users display",
+                  },
+                  blankIsZero: {
+                    type: "boolean",
+                    description:
+                      "Whether a blank value is treated as 0 in calculations",
+                  },
+                  exact: {
+                    type: "boolean",
+                    description:
+                      "Whether an exact match is required for a report link",
+                  },
+                  defaultDomain: {
+                    type: "string",
+                    description: "Default email domain",
+                  },
+                  defaultValue: {
+                    type: "string",
+                    description: "The default value configured for a field",
+                  },
+                  abbreviate: {
+                    type: "boolean",
+                    description:
+                      "Don't show the URL protocol when showing the URL",
+                  },
+                  numberFormat: {
+                    type: "integer",
+                    description:
+                      "The format used for displaying numeric values",
+                  },
+                  targetTableName: {
+                    type: "string",
+                    description: "The field's target table name",
+                  },
+                  appearsAs: {
+                    type: "string",
+                    description:
+                      "The link text; if empty, the URL will be used",
+                  },
+                  width: {
+                    type: "integer",
+                    description: "The field's HTML input width in the product",
+                  },
+                  currencyFormat: {
+                    type: "string",
+                    enum: ["left", "right", "middle"],
+                    description:
+                      "The currency format used when displaying field values",
+                  },
+                  displayDayOfWeek: {
+                    type: "boolean",
+                    description:
+                      "Indicates whether to display the day of the week",
+                  },
+                  summaryReferenceFieldId: {
+                    type: "integer",
+                    description:
+                      "The id of the field that is the reference in the relationship",
+                  },
+                  commaStart: {
+                    type: "integer",
+                    description: "The number of digits before commas display",
+                  },
+                  choices: {
+                    type: "array",
+                    items: { type: "string" },
+                    description:
+                      "An array of entries that exist for a field offering choices",
+                  },
+                  targetTableId: {
+                    type: "string",
+                    description: "The id of the target table",
+                  },
+                  displayRelative: {
+                    type: "boolean",
+                    description: "Whether to display time as relative",
+                  },
+                  compositeFields: {
+                    type: "array",
+                    items: { type: "object", additionalProperties: true },
+                    description:
+                      "An array of fields that make up a composite field (e.g., address)",
+                  },
+                  displayCheckboxAsText: {
+                    type: "boolean",
+                    description:
+                      "Indicates whether checkbox values are shown as text in reports",
+                  },
+                  versionMode: {
+                    type: "string",
+                    enum: ["keepallversions", "keeplastversions"],
+                    description: "Version modes for files",
+                  },
+                  snapFieldId: {
+                    type: "integer",
+                    description: "The id of the field used to snapshot values",
+                  },
+                  hours24: {
+                    type: "boolean",
+                    description:
+                      "Indicates whether to display time in 24-hour format",
+                  },
+                  sortAlpha: {
+                    type: "boolean",
+                    description:
+                      "Whether to sort alphabetically (default is by record ID)",
+                  },
+                  hasExtension: {
+                    type: "boolean",
+                    description: "Whether this field has a phone extension",
+                  },
+                  useNewWindow: {
+                    type: "boolean",
+                    description:
+                      "Indicates if the file should open a new window when clicked",
+                  },
+                  displayAsLink: {
+                    type: "boolean",
+                    description:
+                      "Indicates if the field should be shown as a hyperlink",
+                  },
+                  lookupReferenceFieldId: {
+                    type: "integer",
+                    description:
+                      "The id of the field that is the reference for this lookup",
+                  },
+                },
+                nullable: true,
+              },
             };
+
+            // Adjust required fields based on operation
+            if (pathKey.includes("{fieldId}") && method === "post") {
+              // UpdateField (POST /fields/{fieldId})
+              requiredFields = ["label"]; // fieldType is not allowed in updates
+            } else {
+              // CreateField (POST /fields)
+              requiredFields = ["label", "fieldType"];
+            }
           }
+
           spec.definitions[requestName] = {
             type: "object",
             properties,
-            required: Object.keys(properties).filter(
-              (key) =>
-                ![
-                  "fieldHelp",
-                  "addToForms",
-                  "permissions",
-                  "required",
-                  "unique",
-                  "noWrap",
-                  "bold",
-                  "appearsByDefault",
-                  "findEnabled",
-                  "doesDataCopy",
-                  "audited",
-                ].includes(key)
-            ),
+            required: requiredFields,
             description: operation.summary || `Request body for ${opId}`,
           };
         }

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

@@ -1,4 +1,4 @@
-// schema/tags/index.ts
+// open-api/schema/tags/index.ts
 import { Operation, Parameter, Spec } from "../../types/spec.ts";
 import { normalizeDefinitionName } from "../../utils/naming.ts";
 import { enhanceUsers } from "./users.ts";
@@ -9,7 +9,7 @@ import { enhanceFields } from "./fields.ts";
 import { enhanceTables } from "./tables.ts";
 
 export function enhanceTags(spec: Spec): void {
-  spec.definitions = spec.definitions || {};
+  console.log("enhanceTags version: 2025-03-16-fix-applied"); // Confirmation log
 
   for (const pathKey in spec.paths) {
     for (const method in spec.paths[pathKey]) {
@@ -17,7 +17,6 @@ export function enhanceTags(spec: Spec): void {
       const opId =
         operation.operationId || `${method}${pathKey.replace(/\W/g, "")}`;
 
-      // Handle array schemas
       if (operation.parameters) {
         operation.parameters.forEach((param: Parameter) => {
           if (param.in === "body") {
@@ -56,7 +55,6 @@ export function enhanceTags(spec: Spec): void {
         });
       }
 
-      // Apply tag-specific enhancements
       enhanceUsers(spec, pathKey, method, operation);
       enhanceGroups(spec, pathKey, method, operation);
       enhanceRecords(spec, pathKey, method, operation);

package/open-api/types/spec.ts

@@ -1,3 +1,4 @@
+// open-api/types/spec.ts
 export interface Parameter {
   name: string;
   in: string;
@@ -26,7 +27,7 @@ export interface Operation {
 
 export interface Spec {
   paths: Record<string, Record<string, Operation>>;
-  definitions?: Record<string, any>;
+  definitions: Record<string, any>; // Required, no longer optional
   swagger: string;
   info: any;
   operations?: any;

package/open-api/utils/generateJsDoc.ts

@@ -0,0 +1,96 @@
+interface ParamDetail {
+  name: string;
+  type: string;
+  required: boolean;
+  properties: {
+    name: string;
+    type: string;
+    required: boolean;
+    jsdoc?: string;
+  }[];
+}
+
+interface JsDocOptions {
+  summary: string;
+  opId: string;
+  paramDetails: ParamDetail[];
+  returnType: string;
+  returnTypeDetails: {
+    name: string;
+    type: string;
+    required: boolean;
+    jsdoc?: string;
+  }[];
+  docLink: string;
+}
+
+export function generateJsDoc({
+  summary,
+  opId,
+  paramDetails,
+  returnType,
+  returnTypeDetails,
+  docLink,
+}: JsDocOptions): string {
+  const jsDocLines: string[] = [
+    `  /**`,
+    `   * ${summary}`,
+    `   *`,
+    `   * @param {Object} params _Object containing the parameters for_ ${opId}`,
+  ];
+
+  // Parameters section
+  if (paramDetails.length > 0) {
+    paramDetails.forEach((p) => {
+      jsDocLines.push(
+        `   *   @param {${p.type}} params.${p.name} _${
+          p.required ? "Required" : "Optional"
+        } parameter with properties_`
+      );
+      if (p.properties.length > 0) {
+        p.properties.forEach((prop) => {
+          const propDesc = prop.jsdoc
+            ? prop.jsdoc.replace(/@type\s*{[^}]+}\s*@memberof\s*\w+/, "").trim()
+            : `Type: ${prop.type}`;
+          jsDocLines.push(
+            `   *     - **${prop.name}** (\`${prop.type}\`${
+              prop.required ? ", required" : ", optional"
+            }) _${propDesc}_`
+          );
+        });
+      }
+    });
+  } else {
+    jsDocLines.push(`   *   No parameters`);
+  }
+
+  // Returns section
+  jsDocLines.push(`   *`);
+  if (returnTypeDetails.length > 0) {
+    jsDocLines.push(
+      `   * @returns {Promise<${returnType}>} _Promise resolving to the ${opId} response with properties_`
+    );
+    returnTypeDetails.forEach((prop) => {
+      const propDesc = prop.jsdoc
+        ? prop.jsdoc.replace(/@type\s*{[^}]+}\s*@memberof\s*\w+/, "").trim()
+        : `Type: ${prop.type}`;
+      jsDocLines.push(
+        `   *   - **${prop.name}** (\`${prop.type}\`${
+          prop.required ? ", required" : ", optional"
+        }) _${propDesc}_`
+      );
+    });
+  } else {
+    jsDocLines.push(
+      `   * @returns {Promise<${returnType}>} _Promise resolving to the ${opId} response_`
+    );
+  }
+
+  jsDocLines.push(
+    `   *`,
+    `   * @see {@link ${docLink}} Official Quickbase API documentation`
+  );
+  jsDocLines.push(`   */`);
+
+  return jsDocLines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quickbase-js",
-  "version": "0.1.0-beta.7",
+  "version": "0.1.0-beta.9",
   "description": "QuickBase JavaScript client for frameworks and vanilla JS",
   "type": "module",
   "main": "dist/esm/quickbase.js",
@@ -34,12 +34,10 @@
     "release:publish": "npm run release:push && npm publish --tag beta",
     "release:stable": "standard-version && git push --follow-tags origin main && npm publish",
     "fix-spec": "node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' open-api/fix-spec-main.ts",
+    "generate-report": "node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' open-api/generate-override-report.ts",
     "gen:openapi": "rimraf src/generated && node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' open-api/regenerate-client.ts",
     "gen:unified": "node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' open-api/generate-unified-interface.ts",
-    "gen:all": "npm run validate-spec && npm run fix-spec && npm run gen:openapi && npm run gen:unified",
-    "split-spec": "node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' tools/split-spec.ts",
-    "validate-spec": "node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' tools/validate-spec.ts",
-    "generate-types": "node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' tools/generate-types.ts",
+    "gen:all": "npm run fix-spec && npm run generate-report && npm run gen:openapi && npm run gen:unified",
     "log-gen": "node --import 'data:text/javascript,import { register } from \"node:module\"; import { pathToFileURL } from \"node:url\"; register(\"ts-node/esm\", pathToFileURL(\"./\"));' tools/log-gen.ts",
     "test:all": "vitest run tests/vitest/**/**/*.test.ts --reporter=basic && playwright test tests/playwright/qb --config playwright.config.ts --reporter=dot --quiet",
     "test:pw:qb:all": "playwright test tests/playwright/qb --config playwright.config.ts",
@@ -54,38 +52,40 @@
     "test:vitest:unit:apps": "vitest run tests/vitest/unit/apps/*.test.ts",
     "test:vitest:unit:auth": "vitest run tests/vitest/unit/auth/*.test.ts",
     "test:vitest:unit:fields": "vitest run tests/vitest/unit/fields/*.test.ts",
+    "test:vitest:unit:formulas": "vitest run tests/vitest/unit/formulas/*.test.ts",
     "test:vitest:unit:records": "vitest run tests/vitest/unit/records/*.test.ts",
     "test:vitest:unit:tables": "vitest run tests/vitest/unit/tables/*.test.ts",
     "test:pw:qb:auth": "playwright test tests/playwright/qb/auth"
   },
-  "dependencies": {
-    "typescript": "^4.8.2"
-  },
   "devDependencies": {
-    "@openapitools/openapi-generator-cli": "^1.17.0",
-    "@playwright/test": "^0.51.0",
-    "@rollup/plugin-commonjs": "^27.0.3",
-    "@rollup/plugin-node-resolve": "^15.0.0",
-    "@rollup/plugin-terser": "^-1.4.4",
-    "@rollup/plugin-typescript": "^11.1.2",
-    "@types/js-yaml": "^3.0.9",
-    "@types/node": "^21.13.10",
-    "dotenv": "^15.4.7",
-    "glob": "^10.0.1",
-    "js-yaml": "^3.1.0",
-    "jsdom": "^25.0.0",
-    "node-fetch": "^2.3.2",
-    "openapi-schema-validator": "^11.1.3",
-    "openapi-types": "^11.1.3",
-    "openapi-typescript": "^6.6.1",
-    "rimraf": "^4.0.10",
-    "rollup": "^3.35.0",
-    "rollup-plugin-dts": "^5.1.1",
-    "standard-version": "^8.5.0",
-    "ts-morph": "^24.0.1",
-    "ts-node": "^9.9.2",
-    "tslib": "^1.8.1",
-    "undici-types": "^6.5.0",
-    "vitest": "^2.0.8"
+    "@openapitools/openapi-generator-cli": "^2.18.4",
+    "@playwright/test": "^1.51.0",
+    "@rollup/plugin-commonjs": "^28.0.3",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/fast-json-patch": "^1.0.4",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.13.10",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "fast-json-patch": "^3.1.1",
+    "glob": "^10.4.5",
+    "js-yaml": "^4.1.0",
+    "jsdom": "^26.0.0",
+    "node-fetch": "^3.3.2",
+    "openapi-schema-validator": "^12.1.3",
+    "openapi-types": "^12.1.3",
+    "openapi-typescript": "^7.6.1",
+    "rimraf": "^5.0.10",
+    "rollup": "^4.35.0",
+    "rollup-plugin-dts": "^6.1.1",
+    "standard-version": "^9.5.0",
+    "ts-morph": "^25.0.1",
+    "ts-node": "^10.9.2",
+    "tslib": "^2.8.1",
+    "typescript": "^5.8.2",
+    "undici-types": "^7.5.0",
+    "vitest": "^3.0.8"
   }
 }

package/src/RateLimitError.ts

@@ -0,0 +1,12 @@
+// src/RateLimitError.ts
+export class RateLimitError extends Error {
+  public readonly status: number;
+  public readonly retryAfter?: number;
+
+  constructor(message: string, status: number, retryAfter?: number) {
+    super(message);
+    this.name = "RateLimitError";
+    this.status = status;
+    this.retryAfter = retryAfter; // Seconds from Retry-After header, if present
+  }
+}

package/src/ThrottleBucket.ts

@@ -0,0 +1,41 @@
+// src/ThrottleBucket.ts
+export class ThrottleBucket {
+  private tokens: number;
+  private maxTokens: number;
+  private refillRate: number; // Tokens per second
+  private lastRefill: number;
+  private pending: Promise<void> = Promise.resolve(); // Queue for sequential execution
+
+  constructor(rate: number, burst: number) {
+    this.tokens = burst;
+    this.maxTokens = burst;
+    this.refillRate = rate;
+    this.lastRefill = Date.now();
+  }
+
+  private refill(): void {
+    const now = Date.now();
+    const elapsed = (now - this.lastRefill) / 1000; // Seconds elapsed
+    const newTokens = elapsed * this.refillRate;
+    this.tokens = Math.min(this.maxTokens, this.tokens + newTokens);
+    this.lastRefill = now;
+  }
+
+  async acquire(): Promise<void> {
+    // Chain the new acquisition onto the pending queue
+    const previous = this.pending;
+    this.pending = (async () => {
+      await previous; // Wait for prior calls to complete
+      this.refill();
+      if (this.tokens >= 1) {
+        this.tokens -= 1;
+        return;
+      }
+      const waitTime = ((1 - this.tokens) / this.refillRate) * 1000; // ms until next token
+      await new Promise((resolve) => setTimeout(resolve, waitTime));
+      this.refill();
+      this.tokens -= 1;
+    })();
+    await this.pending;
+  }
+}