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

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

@@ -0,0 +1,174 @@
+// tests/vitest/qb/fields/getFieldUsage.test.ts
+import { describe, it, expect, afterAll } from "vitest";
+import {
+  createClient,
+  QB_REALM,
+  QB_USER_TOKEN,
+  QB_TABLE_ID_1,
+} from "../../../setup.ts";
+import { FieldUsage } from "@/generated/models";
+
+describe("QuickbaseClient Integration - getFieldUsage", () => {
+  const client = createClient();
+  const createdFieldIds: number[] = [];
+
+  afterAll(async () => {
+    if (createdFieldIds.length > 0) {
+      try {
+        const response = await client.deleteFields({
+          tableId: QB_TABLE_ID_1,
+          body: { fieldIds: createdFieldIds },
+        });
+        console.log(
+          `Cleaned up fields: ${JSON.stringify(response.deletedFieldIds)}`,
+          response.errors && response.errors.length > 0
+            ? `Errors: ${response.errors}`
+            : ""
+        );
+      } catch (error) {
+        console.error("Cleanup failed:", error);
+        console.log(`Fields left in table: ${createdFieldIds}`);
+      }
+    } else {
+      console.log("No fields to clean up.");
+    }
+  });
+
+  it(
+    "creates a field, retrieves its usage statistics, and deletes it",
+    async () => {
+      // Step 1: Create a field
+      const uniqueLabel = `TestField_${Date.now()}`;
+      console.log("Creating field with label:", uniqueLabel);
+      const createResponse = await client.createField({
+        tableId: QB_TABLE_ID_1,
+        body: {
+          label: uniqueLabel,
+          fieldType: "text",
+          fieldHelp: "Created for getFieldUsage integration test",
+          addToForms: true,
+        },
+      });
+
+      expect(createResponse.id).toBeDefined();
+      const fieldId = createResponse.id;
+      createdFieldIds.push(fieldId);
+      console.log(`Created field ${uniqueLabel} with ID ${fieldId}`);
+
+      // Brief delay to ensure field is registered
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+
+      // Step 2: Get field usage with raw response logging
+      console.log("Fetching field usage for:", {
+        tableId: QB_TABLE_ID_1,
+        fieldId,
+      });
+      const rawResponse = await fetch(
+        `https://api.quickbase.com/v1/fields/usage/${fieldId}?tableId=${QB_TABLE_ID_1}`,
+        {
+          method: "GET",
+          headers: {
+            "QB-Realm-Hostname": `${QB_REALM}.quickbase.com`,
+            Authorization: `QB-USER-TOKEN ${QB_USER_TOKEN}`,
+            "Content-Type": "application/json",
+          },
+        }
+      );
+      const rawBody = await rawResponse.text();
+      console.log("Raw API response:", {
+        status: rawResponse.status,
+        statusText: rawResponse.statusText,
+        body: rawBody,
+      });
+
+      const responseArray: FieldUsage[] = await client.getFieldUsage({
+        fieldId,
+        tableId: QB_TABLE_ID_1,
+      });
+      console.log("Parsed API response (array):", responseArray);
+
+      // Validate response structure (unwrap the array)
+      expect(responseArray).toBeDefined();
+      expect(responseArray).toHaveLength(1); // Expect a single-item array
+      const response = responseArray[0];
+
+      expect(response).toBeDefined();
+      expect(response.field).toHaveProperty("id", fieldId);
+      expect(response.field).toHaveProperty("name", uniqueLabel);
+      expect(response.field).toHaveProperty("type", "text");
+      expect(typeof response.field.name).toBe("string");
+      expect(typeof response.field.type).toBe("string");
+
+      expect(response.usage).toBeDefined();
+      expect(typeof response.usage).toBe("object");
+      expect(response.usage).toHaveProperty("actions");
+      expect(response.usage.actions).toHaveProperty("count");
+      expect(typeof response.usage.actions.count).toBe("number");
+      expect(response.usage).toHaveProperty("appHomePages");
+      expect(response.usage).toHaveProperty("dashboards");
+      expect(response.usage).toHaveProperty("defaultReports");
+      expect(response.usage).toHaveProperty("exactForms");
+      expect(response.usage).toHaveProperty("fields");
+      expect(response.usage).toHaveProperty("forms");
+      expect(response.usage).toHaveProperty("notifications");
+      expect(response.usage).toHaveProperty("personalReports");
+      expect(response.usage).toHaveProperty("pipelines");
+      expect(response.usage).toHaveProperty("relationships");
+      expect(response.usage).toHaveProperty("reminders");
+      expect(response.usage).toHaveProperty("reports");
+      expect(response.usage).toHaveProperty("roles");
+      expect(response.usage).toHaveProperty("tableImports");
+      expect(response.usage).toHaveProperty("tableRules");
+      expect(response.usage).toHaveProperty("webhooks");
+
+      // Since it’s a new field, expect minimal usage
+      expect(response.usage.forms.count).toBeGreaterThanOrEqual(0); // May be 1 if addToForms worked
+    },
+    { timeout: 30000 } // 30-second timeout for create + get + delete
+  );
+
+  it("fails with non-existent field ID", { timeout: 15000 }, async () => {
+    const nonExistentFieldId = 999999;
+
+    console.log("Attempting to fetch usage for non-existent field:", {
+      tableId: QB_TABLE_ID_1,
+      fieldId: nonExistentFieldId,
+    });
+    await expect(
+      client.getFieldUsage({
+        fieldId: nonExistentFieldId,
+        tableId: QB_TABLE_ID_1,
+      })
+    ).rejects.toMatchObject({
+      message: expect.stringContaining(
+        "API Error: No such field (Status: 404)"
+      ),
+    });
+
+    console.log(
+      `Confirmed 404 for non-existent field ID ${nonExistentFieldId}`
+    );
+  });
+
+  it("fails with invalid table ID", { timeout: 15000 }, async () => {
+    const invalidTableId = "invalid_dbid";
+    const fieldId = 6;
+
+    console.log("Attempting to fetch usage with invalid table ID:", {
+      tableId: invalidTableId,
+      fieldId,
+    });
+    await expect(
+      client.getFieldUsage({
+        fieldId,
+        tableId: invalidTableId,
+      })
+    ).rejects.toMatchObject({
+      message: expect.stringContaining(
+        "API Error: Access denied (Status: 401)"
+      ),
+    });
+
+    console.log(`Confirmed 401 for invalid table ID ${invalidTableId}`);
+  });
+});

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

@@ -0,0 +1,77 @@
+// tests/vitest/qb/fields/getFieldsUsage.test.ts
+import { describe, it, expect } from "vitest";
+import { createClient, QB_TABLE_ID_1 } from "../../../setup.ts";
+import { FieldUsage } from "@/generated/models";
+
+describe("QuickbaseClient Integration - getFieldsUsage", () => {
+  const client = createClient();
+
+  it("retrieves field usage statistics for a valid table", async () => {
+    console.log("Starting retrieval of full field usage list");
+    const response = await client.getFieldsUsage({
+      tableId: QB_TABLE_ID_1,
+    });
+
+    expect(response).toBeInstanceOf(Array);
+    expect(response.length).toBeGreaterThan(0); // Assumes the table has fields
+    response.forEach((usage: FieldUsage) => {
+      expect(usage.field).toHaveProperty("id");
+      expect(usage.field).toHaveProperty("name");
+      expect(usage.field).toHaveProperty("type");
+      expect(usage.usage).toHaveProperty("actions");
+      expect(usage.usage.actions).toHaveProperty("count");
+      expect(typeof usage.usage.actions.count).toBe("number");
+      expect(usage.usage).toHaveProperty("dashboards");
+      expect(usage.usage).toHaveProperty("forms");
+      expect(usage.usage).toHaveProperty("reports");
+    });
+    console.log(
+      `Retrieved ${response.length} field usage entries for table ${QB_TABLE_ID_1}`
+    );
+  }, 15000); // 15-second timeout
+
+  it("retrieves field usage with skip and top parameters", async () => {
+    console.log(
+      "Starting retrieval of full field usage list for skip/top test"
+    );
+    const fullResponse = await client.getFieldsUsage({
+      tableId: QB_TABLE_ID_1,
+    });
+    console.log(`Full list retrieved: ${fullResponse.length} fields`);
+
+    const totalFields = fullResponse.length;
+    if (totalFields <= 1) {
+      console.log("Skipping skip/top test: table has too few fields");
+      return; // Skip if not enough fields to test pagination
+    }
+
+    console.log("Starting retrieval with skip=1 and top=1");
+    const response = await client.getFieldsUsage({
+      tableId: QB_TABLE_ID_1,
+      skip: 1,
+      top: 1,
+    });
+
+    expect(response).toBeInstanceOf(Array);
+    expect(response.length).toBe(1); // Should return exactly 1 field
+    expect(response[0].field.id).not.toBe(fullResponse[0].field.id); // Should skip the first field
+    console.log(
+      `Retrieved ${response.length} field usage entries with skip=1 and top=1`
+    );
+  }, 15000); // 15-second timeout
+
+  it("fails with invalid table ID", async () => {
+    const invalidTableId = "invalid_dbid";
+    console.log(`Starting retrieval with invalid table ID ${invalidTableId}`);
+    await expect(
+      client.getFieldsUsage({
+        tableId: invalidTableId,
+      })
+    ).rejects.toMatchObject({
+      message: expect.stringContaining(
+        "API Error: Access denied (Status: 401)"
+      ),
+    });
+    console.log(`Confirmed 401 for invalid table ID ${invalidTableId}`);
+  }, 15000); // 15-second timeout
+});

package/tests/vitest/qb/index.ts

@@ -1,4 +1,28 @@
-// Optional: Only add if you need to export tests
+// tests/vitest/qb/index.ts
+
+// Apps
+export * from "./apps/copyApp.test.ts";
+export * from "./apps/createApp.test.ts";
+export * from "./apps/deleteApp.test.ts";
 export * from "./apps/getApp.test.ts";
+
+// Fields
+export * from "./fields/createField.test.ts";
+export * from "./fields/deleteFields.test.ts";
 export * from "./fields/getFields.test.ts";
+export * from "./fields/getField.test.ts"; // Added new getField test
+export * from "./fields/getFieldsUsage.test.ts";
+export * from "./fields/getFieldUsage.test.ts";
+
+// Records
+export * from "./records/deleteRecords.test.ts";
+export * from "./records/runQuery.test.ts";
+export * from "./records/upsert.test.ts";
+
+// Tables
+export * from "./tables/createTable.test.ts";
+export * from "./tables/deleteTable.test.ts";
 export * from "./tables/getAppTables.test.ts";
+export * from "./tables/getRelationships.test.ts";
+export * from "./tables/getTable.test.ts";
+export * from "./tables/updateTable.test.ts";

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

@@ -1,6 +1,10 @@
 // tests/vitest/qb/records/deleteRecords.test.ts
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { quickbase } from "@/quickbaseClient.ts";
+import {
+  Upsert200Response,
+  Upsert207Response,
+} from "/home/drew/Projects/quickbase-js/src/generated/models";
 
 const TABLE_ID = "buwai2zws";
 const UNIQUE_FIELD_ID = 3; // Record ID field
@@ -40,16 +44,44 @@ describe("QuickbaseClient - DeleteRecords Integration", () => {
   test(
     "deletes a newly upserted record",
     async () => {
-      const upsertResponse = await qb.upsert({
-        body: {
-          to: TABLE_ID,
-          data: [{ [MARKER_FIELD_ID]: { value: "test-marker-delete" } }],
-          fieldsToReturn: [UNIQUE_FIELD_ID], // Return record ID
-        },
-      });
-      const recordId = upsertResponse.metadata.createdRecordIds[0];
-      expect(recordId).toBeDefined();
-      expect(upsertResponse.data[0][UNIQUE_FIELD_ID].value).toBe(recordId);
+      const upsertResponse: Upsert200Response | Upsert207Response =
+        await qb.upsert({
+          body: {
+            to: TABLE_ID,
+            data: [{ [MARKER_FIELD_ID]: { value: "test-marker-delete" } }],
+            fieldsToReturn: [UNIQUE_FIELD_ID], // Return record ID
+          },
+        });
+
+      // Check metadata and createdRecordIds
+      expect(
+        upsertResponse.metadata,
+        "Expected metadata to be defined"
+      ).toBeDefined();
+      expect(
+        upsertResponse.metadata?.createdRecordIds,
+        "Expected createdRecordIds to be defined"
+      ).toBeDefined();
+
+      const createdRecordIds = upsertResponse.metadata?.createdRecordIds;
+      if (!createdRecordIds || createdRecordIds.length === 0) {
+        throw new Error("Expected at least one created record ID");
+      }
+
+      const recordId = createdRecordIds[0];
+      expect(recordId, "Expected recordId to be defined").toBeDefined();
+
+      // Check data
+      expect(upsertResponse.data, "Expected data to be defined").toBeDefined();
+      if (!upsertResponse.data || upsertResponse.data.length === 0) {
+        throw new Error("Expected at least one data entry");
+      }
+
+      const recordData = upsertResponse.data[0];
+      expect(
+        recordData[UNIQUE_FIELD_ID]?.value,
+        "Expected record ID in data to match created record ID"
+      ).toBe(recordId);
 
       const deleteResponse = await qb.deleteRecords({
         body: { from: TABLE_ID, where: `{${UNIQUE_FIELD_ID}.EX.${recordId}}` },

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

@@ -1,7 +1,17 @@
 // 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";
+import { createClient, QB_TABLE_ID_1 } from "../../../setup.ts";
+import {
+  RunQueryRequest,
+  RunQueryResponse,
+  Upsert200Response,
+  Upsert207Response,
+} from "@/generated/models";
+
+// Define a type for field data with a value property (matches generated Record type)
+interface FieldData {
+  value: any; // Adjust type based on your needs (e.g., string | number)
+}
 
 describe("QuickbaseClient Integration - runQuery", () => {
   let createdRecordId: number;
@@ -12,18 +22,39 @@ describe("QuickbaseClient Integration - runQuery", () => {
       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];
+      const upsertResponse: Upsert200Response | Upsert207Response =
+        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
+          },
+        });
+
+      // Check metadata and createdRecordIds with null safety
+      expect(
+        upsertResponse.metadata,
+        "Expected metadata to be defined"
+      ).toBeDefined();
+      expect(
+        upsertResponse.metadata?.createdRecordIds,
+        "Expected createdRecordIds to be defined"
+      ).toBeDefined();
+
+      const createdRecordIds = upsertResponse.metadata?.createdRecordIds;
+      if (!createdRecordIds || createdRecordIds.length === 0) {
+        throw new Error("Expected at least one created record ID from upsert");
+      }
+
+      createdRecordId = createdRecordIds[0];
+      expect(
+        createdRecordId,
+        "Expected createdRecordId to be defined"
+      ).toBeDefined();
       console.log("Created test record with ID:", createdRecordId);
 
       // Query the record
@@ -46,10 +77,35 @@ describe("QuickbaseClient Integration - runQuery", () => {
       });
       console.log("Real API response:", response);
 
-      // Assertions
+      // Assertions with safety checks and type assertion
+      expect(
+        response.data,
+        "Expected response.data to be defined"
+      ).toBeDefined();
+      if (!response.data || response.data.length === 0) {
+        throw new Error(
+          "Expected response.data to contain at least one record"
+        );
+      }
+
       expect(response.data).toHaveLength(1);
-      expect(response.data[0]["3"].value).toBe(createdRecordId);
-      expect(response.data[0]["6"].value).toContain("Test Task");
+      const record = response.data[0] as { [key: string]: FieldData };
+      expect(
+        record["3"]?.value,
+        "Expected field 3 to match createdRecordId"
+      ).toBe(createdRecordId);
+      expect(
+        record["6"]?.value,
+        "Expected field 6 to contain 'Test Task'"
+      ).toContain("Test Task");
+
+      expect(
+        response.fields,
+        "Expected response.fields to be defined"
+      ).toBeDefined();
+      if (!response.fields) {
+        throw new Error("Expected response.fields to contain field metadata");
+      }
       expect(response.fields).toContainEqual({
         id: 3,
         label: expect.any(String),
@@ -60,6 +116,14 @@ describe("QuickbaseClient Integration - runQuery", () => {
         label: expect.any(String),
         type: expect.any(String),
       });
+
+      expect(
+        response.metadata,
+        "Expected response.metadata to be defined"
+      ).toBeDefined();
+      if (!response.metadata) {
+        throw new Error("Expected response.metadata to be present");
+      }
       expect(response.metadata).toMatchObject({
         numFields: 2,
         numRecords: 1,

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

@@ -1,6 +1,10 @@
 // tests/vitest/qb/records/upsert.test.ts
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import { quickbase } from "@/quickbaseClient.ts";
+import {
+  Upsert200Response,
+  Upsert207Response,
+} from "/home/drew/Projects/quickbase-js/src/generated/models";
 
 const TABLE_ID = "buwai2zws";
 const MARKER_FIELD_ID = 6; // Text field for marking test records
@@ -39,7 +43,7 @@ describe("QuickbaseClient - Upsert Integration", () => {
   test(
     "creates a new record successfully",
     async () => {
-      const response = await qb.upsert({
+      const response: Upsert200Response | Upsert207Response = await qb.upsert({
         body: {
           to: TABLE_ID,
           data: [{ [MARKER_FIELD_ID]: { value: "test-marker-upsert" } }],
@@ -47,12 +51,38 @@ describe("QuickbaseClient - Upsert Integration", () => {
         },
       });
 
+      // Check metadata with null safety
+      expect(
+        response.metadata,
+        "Expected metadata to be defined"
+      ).toBeDefined();
+      if (!response.metadata) {
+        throw new Error("Expected metadata to be present in upsert response");
+      }
+
+      expect(
+        response.metadata.createdRecordIds,
+        "Expected createdRecordIds to be defined"
+      ).toBeDefined();
+      if (!response.metadata.createdRecordIds) {
+        throw new Error(
+          "Expected createdRecordIds to be present in upsert response"
+        );
+      }
       expect(response.metadata.createdRecordIds.length).toBe(1);
+
+      // Check data with null safety
+      expect(response.data, "Expected data to be defined").toBeDefined();
+      if (!response.data || response.data.length === 0) {
+        throw new Error("Expected at least one record in data");
+      }
       expect(response.data).toHaveLength(1);
-      expect(response.data[0][MARKER_FIELD_ID].value).toBe(
+      expect(response.data[0][MARKER_FIELD_ID]?.value).toBe(
         "test-marker-upsert"
       );
-      expect(response.data[0][3].value).toBeDefined(); // Record ID assigned by QuickBase
+      expect(response.data[0][3]?.value).toBeDefined(); // Record ID assigned by QuickBase
+
+      // Check totalNumberOfRecordsProcessed
       expect(response.metadata.totalNumberOfRecordsProcessed).toBe(1);
     },
     { timeout: 10000 }

package/tests/vitest/qb/tables/getRelationships.test.ts

@@ -0,0 +1,80 @@
+// tests/vitest/qb/tables/getRelationships.test.ts
+import { describe, test, expect } from "vitest";
+import { quickbase } from "/home/drew/Projects/quickbase-js/src/quickbaseClient.ts";
+import { QB_TABLE_ID_1 } from "/home/drew/Projects/quickbase-js/tests/setup.ts";
+import { GetRelationships200Response } from "/home/drew/Projects/quickbase-js/src/generated/models";
+
+describe("QuickbaseClient Integration - getRelationships", () => {
+  const qb = quickbase({
+    realm: process.env.QB_REALM || "builderprogram-dbradford6815",
+    userToken: process.env.QB_USER_TOKEN || "",
+    debug: true,
+  });
+
+  test("fetches real relationships from QuickBase", async () => {
+    // Ensure environment variables are set
+    if (!process.env.QB_REALM)
+      throw new Error("QB_REALM is not defined in .env");
+    if (!process.env.QB_USER_TOKEN)
+      throw new Error("QB_USER_TOKEN is not defined in .env");
+
+    console.log("Config used:", {
+      realm: process.env.QB_REALM,
+      userToken: process.env.QB_USER_TOKEN,
+      tableId: QB_TABLE_ID_1,
+    });
+
+    const response: GetRelationships200Response = await qb.getRelationships({
+      tableId: QB_TABLE_ID_1, // Query relationships for QB_TABLE_ID_1 (e.g., "buwai2zws")
+      skip: 0,
+    });
+
+    console.log("Real API response:", JSON.stringify(response, null, 2));
+
+    // Basic structure validation
+    expect(response).toBeDefined();
+    expect(response.metadata).toBeDefined();
+    expect(response.metadata).toHaveProperty(
+      "numRelationships",
+      expect.any(Number)
+    );
+    expect(response.metadata).toHaveProperty("skip", 0);
+    expect(response.metadata).toHaveProperty(
+      "totalRelationships",
+      expect.any(Number)
+    );
+    expect(response.relationships).toBeDefined();
+    expect(Array.isArray(response.relationships)).toBe(true);
+
+    // If relationships exist, validate the first one
+    if (response.relationships.length > 0) {
+      const relationship = response.relationships[0];
+      expect(relationship).toHaveProperty("id", expect.any(Number));
+      expect(relationship).toHaveProperty("parentTableId", expect.any(String));
+      expect(relationship).toHaveProperty("childTableId", QB_TABLE_ID_1);
+      expect(relationship).toHaveProperty("foreignKeyField");
+      expect(relationship.foreignKeyField).toHaveProperty(
+        "id",
+        expect.any(Number)
+      );
+      expect(relationship.foreignKeyField).toHaveProperty(
+        "label",
+        expect.any(String)
+      );
+      expect(relationship.foreignKeyField).toHaveProperty(
+        "type",
+        expect.any(String)
+      );
+      expect(relationship).toHaveProperty("isCrossApp", expect.any(Boolean));
+      expect(relationship).toHaveProperty("lookupFields", expect.any(Array));
+
+      // summaryFields is optional; only validate if present
+      if (
+        "summaryFields" in relationship &&
+        relationship.summaryFields !== undefined
+      ) {
+        expect(Array.isArray(relationship.summaryFields)).toBe(true);
+      }
+    }
+  }, 10000); // Timeout as second argument
+});