quickbase-js 1.1.0-beta.3 → 1.1.0-beta.5

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

@@ -0,0 +1,391 @@
+// tests/vitest/unit/fields/createField.test.ts
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import {
+  createClient,
+  mockFetch,
+  QB_REALM,
+  QB_USER_TOKEN,
+  QB_TABLE_ID_1,
+} from "@tests/setup.ts";
+import { CreateFieldRequest, CreateField200Response } from "@/generated/models";
+
+describe("QuickbaseClient Unit - createField", () => {
+  let client: ReturnType<typeof createClient>;
+
+  beforeEach(() => {
+    mockFetch.mockClear();
+  });
+
+  it("initializes without errors and has createField method", () => {
+    client = createClient(mockFetch, { debug: true });
+    expect(client).toBeDefined();
+    expect(typeof client.createField).toBe("function");
+  });
+
+  it("creates a field successfully with user token", async () => {
+    client = createClient(mockFetch, { debug: true });
+
+    const request: CreateFieldRequest = {
+      label: "TestField",
+      fieldType: "text",
+      fieldHelp: "A test field",
+      addToForms: true,
+      permissions: [
+        { role: "Viewer", permissionType: "View", roleId: 10 },
+        { role: "Administrator", permissionType: "Modify", roleId: 12 },
+      ],
+    };
+
+    const mockResponse: CreateField200Response = {
+      id: 100,
+      label: "TestField",
+      fieldType: "text",
+      mode: "",
+      noWrap: false,
+      bold: false,
+      required: false,
+      appearsByDefault: true,
+      findEnabled: true,
+      unique: false,
+      doesDataCopy: false,
+      fieldHelp: "A test field",
+      audited: false,
+      properties: {
+        primaryKey: false,
+        foreignKey: false,
+        numLines: 1,
+        maxLength: 0,
+        appendOnly: false,
+        allowHTML: false,
+        allowMentions: false,
+        sortAsGiven: false,
+        carryChoices: true,
+        allowNewChoices: false,
+        formula: "",
+        defaultValue: "",
+      },
+      permissions: [
+        { permissionType: "View", role: "Viewer", roleId: 10 },
+        { permissionType: "Modify", role: "Administrator", roleId: 12 },
+      ],
+    };
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve(mockResponse),
+    });
+
+    const result = await client.createField({
+      tableId: QB_TABLE_ID_1,
+      body: request,
+    });
+
+    expect(result).toEqual(mockResponse);
+    expect(mockFetch).toHaveBeenCalledWith(
+      `https://api.quickbase.com/v1/fields?tableId=${QB_TABLE_ID_1}`,
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          "QB-Realm-Hostname": `${QB_REALM}.quickbase.com`,
+          Authorization: `QB-USER-TOKEN ${QB_USER_TOKEN}`,
+          "Content-Type": "application/json",
+        }),
+        credentials: "omit",
+        body: expect.any(String), // Allow any string for body
+      })
+    );
+
+    // Additional check to ensure the body matches the request object, ignoring property order
+    const callArgs = mockFetch.mock.calls[0];
+    const receivedBody = JSON.parse(callArgs[1].body as string);
+    expect(receivedBody).toEqual(request);
+  });
+
+  it("creates a field successfully with temp token", async () => {
+    client = createClient(mockFetch, { useTempTokens: true, debug: true });
+
+    const request: CreateFieldRequest = {
+      label: "TempField",
+      fieldType: "numeric",
+      addToForms: false,
+    };
+
+    const mockResponse: CreateField200Response = {
+      id: 101,
+      label: "TempField",
+      fieldType: "numeric",
+      mode: "",
+      noWrap: false,
+      bold: false,
+      required: false,
+      appearsByDefault: true,
+      findEnabled: true,
+      unique: false,
+      doesDataCopy: false,
+      fieldHelp: "",
+      audited: false,
+      properties: {
+        primaryKey: false,
+        foreignKey: false,
+        numLines: 1,
+        maxLength: 0,
+        appendOnly: false,
+        allowHTML: false,
+        allowMentions: false,
+        sortAsGiven: false,
+        carryChoices: true,
+        allowNewChoices: false,
+        formula: "",
+        defaultValue: "",
+      },
+      permissions: [],
+    };
+
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve({ temporaryAuthorization: "temp_token" }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve(mockResponse),
+      });
+
+    const result = await client.createField({
+      tableId: QB_TABLE_ID_1,
+      body: request,
+    });
+
+    expect(result).toEqual(mockResponse);
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+    expect(mockFetch).toHaveBeenNthCalledWith(
+      1,
+      `https://api.quickbase.com/v1/auth/temporary/${QB_TABLE_ID_1}`,
+      expect.objectContaining({
+        method: "GET",
+        headers: expect.objectContaining({
+          "QB-Realm-Hostname": `${QB_REALM}.quickbase.com`,
+          "Content-Type": "application/json",
+        }),
+        credentials: "include",
+      })
+    );
+    expect(mockFetch).toHaveBeenNthCalledWith(
+      2,
+      `https://api.quickbase.com/v1/fields?tableId=${QB_TABLE_ID_1}`,
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          "QB-Realm-Hostname": `${QB_REALM}.quickbase.com`,
+          Authorization: "QB-TEMP-TOKEN temp_token",
+          "Content-Type": "application/json",
+        }),
+        body: JSON.stringify(request),
+      })
+    );
+  });
+
+  it("retries successfully after 401 with temp token", async () => {
+    client = createClient(mockFetch, { useTempTokens: true, debug: true });
+
+    const request: CreateFieldRequest = {
+      label: "RetryField",
+      fieldType: "checkbox",
+    };
+
+    const mockResponse: CreateField200Response = {
+      id: 102,
+      label: "RetryField",
+      fieldType: "checkbox",
+      mode: "",
+      noWrap: false,
+      bold: false,
+      required: false,
+      appearsByDefault: true,
+      findEnabled: true,
+      unique: false,
+      doesDataCopy: false,
+      fieldHelp: "",
+      audited: false,
+      properties: {
+        primaryKey: false,
+        foreignKey: false,
+        numLines: 1,
+        maxLength: 0,
+        appendOnly: false,
+        allowHTML: false,
+        allowMentions: false,
+        sortAsGiven: false,
+        carryChoices: true,
+        allowNewChoices: false,
+        formula: "",
+        defaultValue: "",
+      },
+      permissions: [],
+    };
+
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: () =>
+          Promise.resolve({ temporaryAuthorization: "initial_token" }),
+      })
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 401,
+        json: () => Promise.resolve({ message: "Unauthorized" }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve({ temporaryAuthorization: "new_token" }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve(mockResponse),
+      });
+
+    const consoleSpy = vi.spyOn(console, "log");
+    const result = await client.createField({
+      tableId: QB_TABLE_ID_1,
+      body: request,
+    });
+
+    expect(result).toEqual(mockResponse);
+    expect(mockFetch).toHaveBeenCalledTimes(4);
+    expect(mockFetch).toHaveBeenNthCalledWith(
+      1,
+      `https://api.quickbase.com/v1/auth/temporary/${QB_TABLE_ID_1}`,
+      expect.any(Object)
+    );
+    expect(mockFetch).toHaveBeenNthCalledWith(
+      2,
+      `https://api.quickbase.com/v1/fields?tableId=${QB_TABLE_ID_1}`,
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: "QB-TEMP-TOKEN initial_token",
+        }),
+      })
+    );
+    expect(mockFetch).toHaveBeenNthCalledWith(
+      3,
+      `https://api.quickbase.com/v1/auth/temporary/${QB_TABLE_ID_1}`,
+      expect.any(Object)
+    );
+    expect(mockFetch).toHaveBeenNthCalledWith(
+      4,
+      `https://api.quickbase.com/v1/fields?tableId=${QB_TABLE_ID_1}`,
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: "QB-TEMP-TOKEN new_token",
+        }),
+      })
+    );
+    expect(consoleSpy).toHaveBeenCalledWith(
+      "Authorization error for createField, refreshing token:",
+      expect.any(String)
+    );
+    expect(consoleSpy).toHaveBeenCalledWith(
+      "Retrying createField with new token"
+    );
+    consoleSpy.mockRestore();
+  });
+
+  it("handles 400 error for invalid request", async () => {
+    client = createClient(mockFetch, { debug: true });
+
+    const request: CreateFieldRequest = {
+      label: "", // Invalid: label is required
+      fieldType: "text",
+    };
+
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 400,
+      json: () => Promise.resolve({ message: "Label is required" }),
+    });
+
+    await expect(
+      client.createField({ tableId: QB_TABLE_ID_1, body: request })
+    ).rejects.toThrow("API Error: Label is required (Status: 400)");
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      `https://api.quickbase.com/v1/fields?tableId=${QB_TABLE_ID_1}`,
+      expect.objectContaining({
+        method: "POST",
+        headers: expect.objectContaining({
+          "QB-Realm-Hostname": `${QB_REALM}.quickbase.com`,
+          Authorization: `QB-USER-TOKEN ${QB_USER_TOKEN}`,
+          "Content-Type": "application/json",
+        }),
+        body: JSON.stringify(request),
+      })
+    );
+  });
+
+  it("handles 401 with failed temp token retry", async () => {
+    client = createClient(mockFetch, { useTempTokens: true, debug: true });
+
+    const request: CreateFieldRequest = {
+      label: "FailField",
+      fieldType: "text",
+    };
+
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: () =>
+          Promise.resolve({ temporaryAuthorization: "initial_token" }),
+      })
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 401,
+        json: () => Promise.resolve({ message: "Unauthorized" }),
+      })
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 401,
+        json: () =>
+          Promise.resolve({ message: "Unauthorized in fetchTempToken" }),
+      });
+
+    const consoleSpy = vi.spyOn(console, "log");
+    await expect(
+      client.createField({ tableId: QB_TABLE_ID_1, body: request })
+    ).rejects.toThrow(
+      "API Error: Unauthorized in fetchTempToken (Status: 401)"
+    );
+
+    expect(mockFetch).toHaveBeenCalledTimes(3);
+    expect(mockFetch).toHaveBeenNthCalledWith(
+      1,
+      `https://api.quickbase.com/v1/auth/temporary/${QB_TABLE_ID_1}`,
+      expect.any(Object)
+    );
+    expect(mockFetch).toHaveBeenNthCalledWith(
+      2,
+      `https://api.quickbase.com/v1/fields?tableId=${QB_TABLE_ID_1}`,
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: "QB-TEMP-TOKEN initial_token",
+        }),
+      })
+    );
+    expect(mockFetch).toHaveBeenNthCalledWith(
+      3,
+      `https://api.quickbase.com/v1/auth/temporary/${QB_TABLE_ID_1}`,
+      expect.any(Object)
+    );
+    expect(consoleSpy).toHaveBeenCalledWith(
+      "Authorization error for createField, refreshing token:",
+      expect.any(String)
+    );
+    consoleSpy.mockRestore();
+  });
+});