quickbase-js 1.1.0-beta.0 → 1.1.0-beta.2

package/src/code-generation/fix-spec-definitions.ts

@@ -79,10 +79,7 @@ export const definitions = {
         type: "string",
         description: "The unique identifier for this application.",
       },
-      name: {
-        type: "string",
-        description: "The app name.",
-      },
+      name: { type: "string", description: "The app name." },
       description: {
         type: "string",
         description: "The description for the app.",
@@ -197,10 +194,7 @@ export const definitions = {
         type: "string",
         description: "The unique identifier (dbid) of the table.",
       },
-      name: {
-        type: "string",
-        description: "The name of the table.",
-      },
+      name: { type: "string", description: "The name of the table." },
       alias: {
         type: "string",
         description: "The automatically-created table alias for the table.",
@@ -275,10 +269,7 @@ export const definitions = {
   UpdateTableRequest: {
     type: "object",
     properties: {
-      name: {
-        type: "string",
-        description: "The new name for the table.",
-      },
+      name: { type: "string", description: "The new name for the table." },
       singleRecordName: {
         type: "string",
         description:
@@ -301,10 +292,7 @@ export const definitions = {
   DeleteTableResponse: {
     type: "object",
     properties: {
-      deletedTableId: {
-        type: "string",
-        description: "The deleted table id.",
-      },
+      deletedTableId: { type: "string", description: "The deleted table id." },
     },
   },
   Record: {
@@ -358,9 +346,7 @@ export const definitions = {
           type: "object",
           additionalProperties: {
             type: "object",
-            properties: {
-              value: { type: "any" },
-            },
+            properties: { value: { type: "any" } },
           },
         },
         description: "Array of upserted records with field IDs and values.",
@@ -401,9 +387,7 @@ export const definitions = {
           type: "object",
           additionalProperties: {
             type: "object",
-            properties: {
-              value: { type: "any" },
-            },
+            properties: { value: { type: "any" } },
           },
         },
         description: "Array of successfully upserted records (may be empty).",
@@ -411,29 +395,15 @@ export const definitions = {
       metadata: {
         type: "object",
         properties: {
-          createdRecordIds: {
-            type: "array",
-            items: { type: "integer" },
-          },
-          updatedRecordIds: {
-            type: "array",
-            items: { type: "integer" },
-          },
-          unchangedRecordIds: {
-            type: "array",
-            items: { type: "integer" },
-          },
+          createdRecordIds: { type: "array", items: { type: "integer" } },
+          updatedRecordIds: { type: "array", items: { type: "integer" } },
+          unchangedRecordIds: { type: "array", items: { type: "integer" } },
           lineErrors: {
             type: "object",
-            additionalProperties: {
-              type: "array",
-              items: { type: "string" },
-            },
+            additionalProperties: { type: "array", items: { type: "string" } },
             description: "Errors by line number (1-based index).",
           },
-          totalNumberOfRecordsProcessed: {
-            type: "integer",
-          },
+          totalNumberOfRecordsProcessed: { type: "integer" },
         },
         required: ["totalNumberOfRecordsProcessed"],
       },
@@ -482,4 +452,92 @@ export const definitions = {
     required: ["numberDeleted"],
     description: "Response body for successful deletion of records.",
   },
+  RunQueryRequest: {
+    type: "object",
+    required: ["from"],
+    properties: {
+      from: { type: "string", description: "Table ID (dbid)" },
+      select: {
+        type: "array",
+        items: { type: "integer" },
+        description: "Field IDs to return",
+      },
+      where: { type: "string", description: "Query string" },
+      sortBy: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            fieldId: { type: "integer" },
+            order: { type: "string", enum: ["ASC", "DESC"] },
+          },
+        },
+        description: "Sort criteria",
+      },
+      groupBy: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            fieldId: { type: "integer" },
+            grouping: { type: "string", enum: ["equal-values"] },
+          },
+        },
+        description: "Grouping criteria",
+      },
+      options: {
+        type: "object",
+        properties: {
+          skip: { type: "integer", description: "Number of records to skip" },
+          top: {
+            type: "integer",
+            description: "Max number of records to return",
+          },
+          compareWithAppLocalTime: {
+            type: "boolean",
+            description: "Compare times with app local time",
+          },
+        },
+      },
+    },
+  },
+  RunQueryResponse: {
+    type: "object",
+    properties: {
+      data: {
+        type: "array",
+        items: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            properties: { value: { type: "any" } },
+          },
+        },
+        description: "Array of record data with field IDs as keys",
+      },
+      fields: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            id: { type: "integer" },
+            label: { type: "string" },
+            type: { type: "string" },
+          },
+        },
+        description: "Field metadata",
+      },
+      metadata: {
+        type: "object",
+        properties: {
+          numFields: { type: "integer" },
+          numRecords: { type: "integer" },
+          skip: { type: "integer" },
+          top: { type: "integer" },
+          totalRecords: { type: "integer" },
+        },
+        description: "Query metadata",
+      },
+    },
+  },
 };

package/src/code-generation/fix-spec-paths.ts

@@ -280,34 +280,21 @@ export const paths = {
   },
   "/records/query": {
     post: {
-      operationId: "upsertRecords",
-      summary: "Upsert records (alternative endpoint)",
+      operationId: "runQuery",
+      summary: "Query records in a table",
       tags: ["Records"],
       parameters: [
         {
-          name: "generated",
+          name: "body",
           in: "body",
           required: true,
-          schema: {
-            type: "array",
-            items: { $ref: "#/definitions/Record" },
-          },
+          schema: { $ref: "#/definitions/RunQueryRequest" },
         },
       ],
       responses: {
         200: {
-          description: "Success",
-          schema: {
-            type: "array",
-            items: { $ref: "#/definitions/Upsert200Response" },
-          },
-        },
-        207: {
-          description: "Multi-Status (partial success)",
-          schema: {
-            type: "array",
-            items: { $ref: "#/definitions/Upsert207Response" },
-          },
+          description: "Success - records returned",
+          schema: { $ref: "#/definitions/RunQueryResponse" },
         },
       },
     },

package/src/code-generation/generate-unified-interface.ts

@@ -48,20 +48,15 @@ function generateInterface() {
         })
         .map((p) => {
           const param = p as OpenAPIV2.ParameterObject;
-          let type = param.type
+          const type = param.type
             ? mapOpenApiTypeToTs(param.type)
             : param.schema
             ? mapRefToType(param.schema, modelImports)
             : "any";
-          // Special handling for upsertRecords 'generated' parameter
-          if (opId === "upsertRecords" && param.name === "generated") {
-            type = "{ [key: string]: string }[]";
-          }
           return `${param.name}${param.required ? "" : "?"}: ${type}`;
         })
         .join("; ");
 
-      // Handle responses, ensuring distinct types for 200 and 207
       const successResponses = ["200", "207"]
         .map((code) => ({
           code,
@@ -73,7 +68,6 @@ function generateInterface() {
       const returnTypes = successResponses.map(({ response }) =>
         mapRefToType(response!.schema, modelImports)
       );
-      // Deduplicate return types and join with " | ", default to "void" if empty
       const uniqueReturnTypes = [...new Set(returnTypes)];
       const returnType =
         uniqueReturnTypes.length > 0 ? uniqueReturnTypes.join(" | ") : "void";
@@ -84,7 +78,6 @@ function generateInterface() {
     }
   }
 
-  // Generate import statements for all model types
   const importStatement =
     modelImports.size > 0
       ? `import { ${Array.from(modelImports)

package/src/code-generation/output/quickbase-fixed.json

@@ -4095,41 +4095,26 @@
     },
     "/records/query": {
       "post": {
-        "operationId": "upsertRecords",
-        "summary": "Upsert records (alternative endpoint)",
+        "operationId": "runQuery",
+        "summary": "Query records in a table",
         "tags": [
           "Records"
         ],
         "parameters": [
           {
-            "name": "generated",
+            "name": "body",
             "in": "body",
             "required": true,
             "schema": {
-              "type": "array",
-              "items": {
-                "$ref": "#/definitions/Record"
-              }
+              "$ref": "#/definitions/RunQueryRequest"
             }
           }
         ],
         "responses": {
           "200": {
-            "description": "Success",
-            "schema": {
-              "type": "array",
-              "items": {
-                "$ref": "#/definitions/Upsert200Response"
-              }
-            }
-          },
-          "207": {
-            "description": "Multi-Status (partial success)",
+            "description": "Success - records returned",
             "schema": {
-              "type": "array",
-              "items": {
-                "$ref": "#/definitions/Upsert207Response"
-              }
+              "$ref": "#/definitions/RunQueryResponse"
             }
           }
         }
@@ -7954,6 +7939,142 @@
         "numberDeleted"
       ],
       "description": "Response body for successful deletion of records."
+    },
+    "RunQueryRequest": {
+      "type": "object",
+      "required": [
+        "from"
+      ],
+      "properties": {
+        "from": {
+          "type": "string",
+          "description": "Table ID (dbid)"
+        },
+        "select": {
+          "type": "array",
+          "items": {
+            "type": "integer"
+          },
+          "description": "Field IDs to return"
+        },
+        "where": {
+          "type": "string",
+          "description": "Query string"
+        },
+        "sortBy": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "fieldId": {
+                "type": "integer"
+              },
+              "order": {
+                "type": "string",
+                "enum": [
+                  "ASC",
+                  "DESC"
+                ]
+              }
+            }
+          },
+          "description": "Sort criteria"
+        },
+        "groupBy": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "fieldId": {
+                "type": "integer"
+              },
+              "grouping": {
+                "type": "string",
+                "enum": [
+                  "equal-values"
+                ]
+              }
+            }
+          },
+          "description": "Grouping criteria"
+        },
+        "options": {
+          "type": "object",
+          "properties": {
+            "skip": {
+              "type": "integer",
+              "description": "Number of records to skip"
+            },
+            "top": {
+              "type": "integer",
+              "description": "Max number of records to return"
+            },
+            "compareWithAppLocalTime": {
+              "type": "boolean",
+              "description": "Compare times with app local time"
+            }
+          }
+        }
+      }
+    },
+    "RunQueryResponse": {
+      "type": "object",
+      "properties": {
+        "data": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "properties": {
+                "value": {
+                  "type": "any"
+                }
+              }
+            }
+          },
+          "description": "Array of record data with field IDs as keys"
+        },
+        "fields": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "integer"
+              },
+              "label": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string"
+              }
+            }
+          },
+          "description": "Field metadata"
+        },
+        "metadata": {
+          "type": "object",
+          "properties": {
+            "numFields": {
+              "type": "integer"
+            },
+            "numRecords": {
+              "type": "integer"
+            },
+            "skip": {
+              "type": "integer"
+            },
+            "top": {
+              "type": "integer"
+            },
+            "totalRecords": {
+              "type": "integer"
+            }
+          },
+          "description": "Query metadata"
+        }
+      }
     }
   }
 }

package/src/generated-unified/QuickbaseClient.ts

@@ -1,5 +1,5 @@
-// Generated on 2025-03-11T02:50:18.896Z
-import { App, CreateApp200Response, CreateAppRequest, DeleteRecords200Response, DeleteRecordsRequest, DeleteTableResponse, Field, GetTempTokenDBID200Response, Record, ReportRunResponse, Table, UpdateTableRequest, Upsert200Response, Upsert207Response, UpsertRequest } from "../generated/models";
+// Generated on 2025-03-11T14:12:45.650Z
+import { App, CreateApp200Response, CreateAppRequest, DeleteRecords200Response, DeleteRecordsRequest, DeleteTableResponse, Field, GetTempTokenDBID200Response, ReportRunResponse, RunQueryRequest, RunQueryResponse, Table, UpdateTableRequest, Upsert200Response, Upsert207Response, UpsertRequest } from "../generated/models";
 
 export interface QuickbaseClient {
   createApp: (params: { body: CreateAppRequest }) => Promise<CreateApp200Response>;
@@ -26,7 +26,7 @@ export interface QuickbaseClient {
   runFormula: (params: { generated?: any }) => Promise<{ [key: string]: any }>;
   upsert: (params: { body: UpsertRequest }) => Promise<Upsert200Response | Upsert207Response>;
   deleteRecords: (params: { body: DeleteRecordsRequest }) => Promise<DeleteRecords200Response>;
-  upsertRecords: (params: { generated: { [key: string]: string }[] }) => Promise<Upsert200Response[] | Upsert207Response[]>;
+  runQuery: (params: { body: RunQueryRequest }) => Promise<RunQueryResponse>;
   getTempTokenDBID: (params: { dbid: string }) => Promise<GetTempTokenDBID200Response>;
   exchangeSsoToken: (params: { generated?: any }) => Promise<{ [key: string]: any }>;
   cloneUserToken: (params: { generated?: any }) => Promise<{ [key: string]: any }>;

package/tests/playwright/qb/auth/cacheSwitching.test.ts

@@ -67,13 +67,13 @@ test.describe("QuickbaseClient Integration - Cache Switching with Temp Tokens",
     console.log("Starting cacheSwitching test");
     const realm = process.env.QB_REALM;
     const appId = process.env.QB_APP_ID;
-    const tableId = process.env.QB_TABLE_ID;
+    const tableId = process.env.QB_TABLE_ID_1;
     const username = process.env.QB_USERNAME;
     const password = process.env.QB_PASSWORD;
 
     if (!realm) throw new Error("QB_REALM is not defined in .env");
     if (!appId) throw new Error("QB_APP_ID is not defined in .env");
-    if (!tableId) throw new Error("QB_TABLE_ID is not defined in .env");
+    if (!tableId) throw new Error("QB_TABLE_ID_1 is not defined in .env");
     if (!username) throw new Error("QB_USERNAME is not defined in .env");
     if (!password) throw new Error("QB_PASSWORD is not defined in .env");
 

package/tests/setup.ts

@@ -2,26 +2,46 @@
 import { vi } from "vitest";
 import { quickbase } from "../src/quickbaseClient.ts";
 import type { QuickbaseConfig } from "../src/quickbaseClient.ts";
+import dotenv from "dotenv";
+
+// Load environment variables from .env file
+dotenv.config({ path: "./.env" }); // Assumes .env is at project root
 
 export const mockFetch = vi.fn();
 
+export const QB_REALM = process.env.QB_REALM || "test-realm";
+export const QB_USER_TOKEN =
+  process.env.QB_USER_TOKEN || "user-token-1234567890";
+export const QB_APP_ID = process.env.QB_APP_ID || "app-id-1234567890";
+export const QB_TABLE_ID_1 = process.env.QB_TABLE_ID_1 || "table-id-1234567890";
+
+// Mock env variables for consistency, using .env values if available
+vi.stubEnv("QB_REALM", QB_REALM);
+vi.stubEnv("QB_USER_TOKEN", QB_USER_TOKEN);
+vi.stubEnv("QB_APP_ID", QB_APP_ID);
+vi.stubEnv("QB_TABLE_ID_1", QB_TABLE_ID_1);
+
 export const createClient = (
   fetchApi?: any,
   config: Partial<QuickbaseConfig> = {}
 ) => {
+  // Use loaded env vars with fallbacks for safety
+  const realm = QB_REALM;
+  const userToken = QB_USER_TOKEN;
+
   const client = quickbase({
-    realm: process.env.QB_REALM || "test-realm", // Match upsert.test.ts
-    userToken: process.env.QB_USER_TOKEN || "test-token", // Match upsert.test.ts
+    realm,
+    userToken,
     debug: true,
     fetchApi,
+    ...config, // Allow overrides if provided
+  });
+  console.log("[createClient] Config:", {
+    realm,
+    userToken,
+    debug: true,
     ...config,
   });
-  console.log("[createClient] Config:", config); // Debug config
-  console.log("[createClient] Returning:", client); // Debug client
+  console.log("[createClient] Returning:", client);
   return client;
 };
-
-// Mock env variables for consistency
-vi.stubEnv("QB_REALM", "builderprogram-dbradford6815");
-vi.stubEnv("QB_USER_TOKEN", "b9f3pk_q4jd_0_b4qu5eebyvuix3xs57ysd7zn3");
-vi.stubEnv("QB_APP_ID", "buwai2zpe");

package/tests/vitest/qb/fields/getFields.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { createClient } from "../../../setup.ts";
+import { createClient, QB_TABLE_ID_1 } from "../../../setup.ts";
 
 describe("QuickbaseClient Integration - getFields", () => {
   const client = createClient();
@@ -7,8 +7,6 @@ describe("QuickbaseClient Integration - getFields", () => {
   it(
     "fetches real field data from QuickBase",
     async () => {
-      const tableId = "buwai2z3s";
-      if (!tableId) throw new Error("Table ID is not defined");
       if (!process.env.QB_REALM)
         throw new Error("QB_REALM is not defined in .env");
       if (!process.env.QB_USER_TOKEN)
@@ -17,10 +15,10 @@ describe("QuickbaseClient Integration - getFields", () => {
       console.log("Config used:", {
         realm: process.env.QB_REALM,
         userToken: process.env.QB_USER_TOKEN,
-        tableId,
+        tableId: QB_TABLE_ID_1,
       });
       const result = await client.getFields({
-        tableId,
+        tableId: QB_TABLE_ID_1,
         includeFieldPerms: true,
       });
       console.log("Real API response:", result);

package/tests/vitest/qb/records/runQuery.test.ts

@@ -0,0 +1,82 @@
+// tests/vitest/qb/records/runQuery.test.ts
+import { describe, it, expect } from "vitest";
+import { createClient, QB_TABLE_ID_1 } from "../../../setup.ts"; // Import QB_TABLE_ID_1
+import { RunQueryRequest, RunQueryResponse } from "@/generated/models";
+
+describe("QuickbaseClient Integration - runQuery", () => {
+  let createdRecordId: number;
+
+  it(
+    "queries real records from QuickBase",
+    async () => {
+      const client = createClient();
+
+      // Upsert a test record to query later
+      const upsertResponse = await client.upsert({
+        body: {
+          to: QB_TABLE_ID_1,
+          data: [
+            {
+              "6": { value: "Test Task " + Date.now() }, // Assuming field 6 is a text field
+            },
+          ],
+          fieldsToReturn: [3, 6], // Record ID# and the text field
+        },
+      });
+      createdRecordId = upsertResponse.metadata.createdRecordIds[0];
+      console.log("Created test record with ID:", createdRecordId);
+
+      // Query the record
+      const queryRequest: RunQueryRequest = {
+        from: QB_TABLE_ID_1,
+        select: [3, 6], // Query Record ID# and the text field
+        where: `{3.EX.${createdRecordId}}`, // Filter by the created record
+        sortBy: [{ fieldId: 6, order: "ASC" }],
+        options: { skip: 0, top: 1 },
+      };
+
+      console.log("Config used:", {
+        realm: process.env.QB_REALM,
+        userToken: process.env.QB_USER_TOKEN,
+        tableId: QB_TABLE_ID_1,
+      });
+      console.log("Query request:", queryRequest);
+      const response: RunQueryResponse = await client.runQuery({
+        body: queryRequest,
+      });
+      console.log("Real API response:", response);
+
+      // Assertions
+      expect(response.data).toHaveLength(1);
+      expect(response.data[0]["3"].value).toBe(createdRecordId);
+      expect(response.data[0]["6"].value).toContain("Test Task");
+      expect(response.fields).toContainEqual({
+        id: 3,
+        label: expect.any(String),
+        type: expect.any(String),
+      });
+      expect(response.fields).toContainEqual({
+        id: 6,
+        label: expect.any(String),
+        type: expect.any(String),
+      });
+      expect(response.metadata).toMatchObject({
+        numFields: 2,
+        numRecords: 1,
+        skip: 0,
+        top: 1,
+        totalRecords: expect.any(Number),
+      });
+
+      // Cleanup: Delete the test record
+      await client.deleteRecords({
+        body: {
+          from: QB_TABLE_ID_1,
+          where: `{3.EX.${createdRecordId}}`, // Assuming field 3 is Record ID#
+        },
+      });
+      console.log("Cleaned up test record with ID:", createdRecordId);
+    },
+    { timeout: 10000 }
+  );
+});