quickbase-js 0.1.0-beta.10

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

@@ -0,0 +1,82 @@
+// 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}`);
+    const startTime = Date.now();
+    await expect(
+      client.getFieldsUsage({
+        tableId: invalidTableId,
+      })
+    ).rejects.toMatchObject({
+      message: expect.stringContaining(
+        "API Error: Access denied (Status: 401)"
+      ),
+    });
+    const duration = Date.now() - startTime;
+    console.log(
+      `Confirmed 401 for invalid table ID ${invalidTableId} in ${duration}ms`
+    );
+  }, 30000); // Increased to 30-second timeout
+});

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

@@ -0,0 +1,232 @@
+import { describe, it, expect } from "vitest";
+import { createClient, QB_TABLE_ID_1 } from "../../../setup.ts";
+
+describe("QuickbaseClient Integration - getFields", () => {
+  const client = createClient();
+
+  it(
+    "fetches real field data from QuickBase",
+    async () => {
+      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 result = await client.getFields({
+        tableId: QB_TABLE_ID_1,
+        includeFieldPerms: true,
+      });
+      console.log("Real API response:", result);
+      expect(result).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            id: 1,
+            label: "Date Created",
+            fieldType: "timestamp",
+            noWrap: true,
+            bold: false,
+            required: false,
+            appearsByDefault: false,
+            findEnabled: false,
+            unique: false,
+            doesDataCopy: false,
+            fieldHelp: "",
+            audited: false,
+            properties: expect.objectContaining({
+              primaryKey: false,
+              foreignKey: false,
+              sortAsGiven: true,
+              carryChoices: true,
+              allowNewChoices: false,
+              formula: "",
+              defaultValue: "",
+            }),
+            permissions: expect.arrayContaining([
+              expect.objectContaining({
+                permissionType: "Modify",
+                role: "Viewer",
+                roleId: 10,
+              }),
+              expect.objectContaining({
+                permissionType: "Modify",
+                role: "Participant",
+                roleId: 11,
+              }),
+              expect.objectContaining({
+                permissionType: "Modify",
+                role: "Administrator",
+                roleId: 12,
+              }),
+            ]),
+          }),
+          expect.objectContaining({
+            id: 2,
+            label: "Date Modified",
+            fieldType: "timestamp",
+            noWrap: true,
+            bold: false,
+            required: false,
+            appearsByDefault: false,
+            findEnabled: false,
+            unique: false,
+            doesDataCopy: false,
+            fieldHelp: "",
+            audited: false,
+            properties: expect.objectContaining({
+              primaryKey: false,
+              foreignKey: false,
+              sortAsGiven: true,
+              carryChoices: true,
+              allowNewChoices: false,
+              formula: "",
+              defaultValue: "",
+            }),
+            permissions: expect.arrayContaining([
+              expect.objectContaining({
+                permissionType: "Modify",
+                role: "Viewer",
+                roleId: 10,
+              }),
+              expect.objectContaining({
+                permissionType: "Modify",
+                role: "Participant",
+                roleId: 11,
+              }),
+              expect.objectContaining({
+                permissionType: "Modify",
+                role: "Administrator",
+                roleId: 12,
+              }),
+            ]),
+          }),
+          expect.objectContaining({
+            id: 3,
+            label: "Record ID#",
+            fieldType: "recordid",
+            noWrap: true,
+            bold: false,
+            required: false,
+            appearsByDefault: false,
+            findEnabled: false,
+            unique: true,
+            doesDataCopy: false,
+            fieldHelp: "",
+            audited: false,
+            properties: expect.objectContaining({
+              primaryKey: true,
+              foreignKey: false,
+              sortAsGiven: true,
+              carryChoices: true,
+              allowNewChoices: false,
+              formula: "",
+              defaultValue: "",
+            }),
+            permissions: expect.arrayContaining([
+              expect.objectContaining({
+                permissionType: "Modify",
+                role: "Viewer",
+                roleId: 10,
+              }),
+              expect.objectContaining({
+                permissionType: "Modify",
+                role: "Participant",
+                roleId: 11,
+              }),
+              expect.objectContaining({
+                permissionType: "Modify",
+                role: "Administrator",
+                roleId: 12,
+              }),
+            ]),
+          }),
+          expect.objectContaining({
+            id: 4,
+            label: "Record Owner",
+            fieldType: "user",
+            noWrap: true,
+            bold: false,
+            required: false,
+            appearsByDefault: false,
+            findEnabled: true,
+            unique: false,
+            doesDataCopy: false,
+            fieldHelp: "",
+            audited: false,
+            properties: expect.objectContaining({
+              primaryKey: false,
+              foreignKey: false,
+              sortAsGiven: true,
+              carryChoices: true,
+              allowNewChoices: true,
+              formula: "",
+              defaultValue: "",
+            }),
+            permissions: expect.arrayContaining([
+              expect.objectContaining({
+                permissionType: "Modify",
+                role: "Viewer",
+                roleId: 10,
+              }),
+              expect.objectContaining({
+                permissionType: "Modify",
+                role: "Participant",
+                roleId: 11,
+              }),
+              expect.objectContaining({
+                permissionType: "Modify",
+                role: "Administrator",
+                roleId: 12,
+              }),
+            ]),
+          }),
+          expect.objectContaining({
+            id: 5,
+            label: "Last Modified By",
+            fieldType: "user",
+            noWrap: true,
+            bold: false,
+            required: false,
+            appearsByDefault: false,
+            findEnabled: true,
+            unique: false,
+            doesDataCopy: false,
+            fieldHelp: "",
+            audited: false,
+            properties: expect.objectContaining({
+              primaryKey: false,
+              foreignKey: false,
+              sortAsGiven: true,
+              carryChoices: true,
+              allowNewChoices: true,
+              formula: "",
+              defaultValue: "",
+            }),
+            permissions: expect.arrayContaining([
+              expect.objectContaining({
+                permissionType: "Modify",
+                role: "Viewer",
+                roleId: 10,
+              }),
+              expect.objectContaining({
+                permissionType: "Modify",
+                role: "Participant",
+                roleId: 11,
+              }),
+              expect.objectContaining({
+                permissionType: "Modify",
+                role: "Administrator",
+                roleId: 12,
+              }),
+            ]),
+          }),
+        ])
+      );
+    },
+    { timeout: 10000 }
+  );
+});

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/fields/updateField.test.ts

@@ -0,0 +1,93 @@
+// tests/vitest/qb/fields/updateField.test.ts
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { createClient, QB_TABLE_ID_1 } from "../../../setup.ts";
+
+describe("QuickbaseClient Integration - updateField", () => {
+  const client = createClient();
+  let fieldIdToUpdate: number;
+
+  // Setup: Create a test field to update
+  beforeAll(async () => {
+    try {
+      const response = await client.createField({
+        tableId: QB_TABLE_ID_1,
+        body: {
+          label: "UpdateTestField",
+          fieldType: "text",
+          fieldHelp: "Test field for updating",
+        },
+      });
+      fieldIdToUpdate = response.id;
+      console.log(`Created field UpdateTestField with ID ${fieldIdToUpdate}`);
+    } catch (error) {
+      console.error("beforeAll failed:", error);
+      throw error; // Fail the suite if setup fails
+    }
+  });
+
+  // Teardown: Delete the test field
+  afterAll(async () => {
+    try {
+      if (fieldIdToUpdate) {
+        const response = await client.deleteFields({
+          tableId: QB_TABLE_ID_1,
+          body: { fieldIds: [fieldIdToUpdate] },
+        });
+        console.log(
+          `Deleted field ${fieldIdToUpdate}:`,
+          JSON.stringify(response, null, 2)
+        );
+      }
+    } catch (error) {
+      console.error("afterAll cleanup failed:", error);
+      // Don’t throw here to avoid masking test results
+    }
+  });
+
+  it(
+    "updates a field successfully with user token",
+    { timeout: 10000 },
+    async () => {
+      try {
+        const updatedLabel = "UpdatedTestField";
+        console.log("Sending updateField request at:", new Date());
+        const response = await client.updateField({
+          tableId: QB_TABLE_ID_1,
+          fieldId: fieldIdToUpdate,
+          body: {
+            label: updatedLabel,
+            fieldHelp: "Updated help text",
+          },
+        });
+        console.log("updateField response received at:", new Date());
+        console.log("Response:", JSON.stringify(response, null, 2));
+
+        // Verify the update was successful
+        expect(response).toBeDefined();
+        expect(response.id).toBe(fieldIdToUpdate);
+        expect(response.label).toBe(updatedLabel);
+        expect(response.fieldHelp).toBe("Updated help text");
+      } catch (error) {
+        console.error("updateField failed:", error);
+        throw error; // Re-throw to fail the test with details
+      }
+    }
+  );
+
+  it("fails with invalid field ID", { timeout: 10000 }, async () => {
+    try {
+      await expect(
+        client.updateField({
+          tableId: QB_TABLE_ID_1,
+          fieldId: 999999, // Invalid field ID
+          body: {
+            label: "InvalidUpdate",
+          },
+        })
+      ).rejects.toThrow("API Error: Item not found (Status: 404)"); // Updated to match actual error
+    } catch (error) {
+      console.error("updateField with invalid ID failed unexpectedly:", error);
+      throw error;
+    }
+  });
+});

package/tests/vitest/qb/formulas/runFormula.test.ts

@@ -0,0 +1,96 @@
+// tests/vitest/qb/formulas/runFormula.test.ts
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import {
+  createClient,
+  QB_REALM,
+  QB_USER_TOKEN,
+  QB_TABLE_ID_1,
+} from "@tests/setup.ts";
+import {
+  RunFormulaRequest,
+  RunFormula200Response,
+  Upsert200Response,
+} from "@/generated/models";
+
+describe("QuickbaseClient Integration - runFormula", () => {
+  let client: ReturnType<typeof createClient>;
+  let testRecordId: number;
+
+  beforeAll(async () => {
+    // Validate environment variables
+    if (!QB_REALM) throw new Error("QB_REALM is not defined in .env");
+    if (!QB_USER_TOKEN) throw new Error("QB_USER_TOKEN is not defined in .env");
+    if (!QB_TABLE_ID_1) throw new Error("QB_TABLE_ID_1 is not defined in .env");
+
+    // Initialize client with user token only
+    client = createClient(undefined, {
+      realm: QB_REALM,
+      userToken: QB_USER_TOKEN,
+      debug: true,
+    });
+
+    // Upsert a test record to ensure we have a valid rid
+    const upsertResponse: Upsert200Response = await client.upsert({
+      body: {
+        to: QB_TABLE_ID_1,
+        data: [
+          {
+            "6": { value: `Test Record ${Date.now()}` }, // Assuming field 6 is a text field (e.g., "Task Name")
+          },
+        ],
+        fieldsToReturn: [3], // Return Record ID# (field ID 3)
+      },
+    });
+
+    // Extract the created record ID
+    testRecordId = upsertResponse.data[0]["3"].value as number;
+    console.log(`Upserted test record with ID: ${testRecordId}`);
+  });
+
+  afterAll(async () => {
+    // Clean up the test record
+    if (testRecordId) {
+      await client.deleteRecords({
+        body: {
+          from: QB_TABLE_ID_1,
+          where: `{3.EX.${testRecordId}}`, // Delete by Record ID#
+        },
+      });
+      console.log(`Cleaned up test record with ID: ${testRecordId}`);
+    }
+  });
+
+  it("runs simple formula without rid and returns correct result", async () => {
+    const request: RunFormulaRequest = {
+      from: QB_TABLE_ID_1,
+      formula: "1 + 1", // Simple arithmetic to verify functionality
+    };
+
+    const response: RunFormula200Response = await client.runFormula({
+      body: request,
+    });
+
+    console.log("Real API response (no rid):", response);
+
+    expect(response).toHaveProperty("result");
+    expect(response.result).toBe("2"); // Expect "2" as a string
+  }, 10000);
+
+  it("runs formula with rid and field ID 3, returns correct numeric result", async () => {
+    const request: RunFormulaRequest = {
+      from: QB_TABLE_ID_1,
+      formula: "Sum([Record ID#], 20)", // Field ID 3 is "Record ID#"
+      rid: testRecordId, // Use the upserted record ID
+    };
+
+    const response: RunFormula200Response = await client.runFormula({
+      body: request,
+    });
+
+    console.log("Real API response (with rid):", response);
+
+    expect(response).toHaveProperty("result");
+    expect(response.result).toBe(String(testRecordId + 20)); // Dynamic result based on the record ID
+  }, 10000);
+});

package/tests/vitest/qb/index.ts

@@ -0,0 +1,29 @@
+// 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";
+export * from "./tables/updateRelationship.test.ts";