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

package/tests/vitest/unit/rateLimit.test.ts

@@ -0,0 +1,189 @@
+// tests/vitest/unit/rateLimit.test.ts
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  createClient,
+  mockFetch,
+  QB_APP_ID,
+  QB_REALM,
+  QB_USER_TOKEN,
+} from "@tests/setup.ts";
+import { RateLimitError } from "@/RateLimitError";
+import { GetApp200Response } from "@/generated/models";
+
+describe("QuickbaseClient Unit - Rate Limit Handling", () => {
+  let client: ReturnType<typeof createClient>;
+
+  beforeEach(() => {
+    mockFetch.mockClear();
+  });
+
+  it("succeeds after retrying on 429 Too Many Requests", async () => {
+    client = createClient(mockFetch, {
+      realm: QB_REALM,
+      userToken: QB_USER_TOKEN,
+      debug: true,
+      maxRetries: 2,
+      retryDelay: 100,
+      throttle: { rate: 10, burst: 10 },
+    });
+
+    const appId = QB_APP_ID;
+
+    const mockResponse: GetApp200Response = {
+      id: appId,
+      name: "TestApp",
+      created: "2025-01-01T00:00:00Z",
+      updated: "2025-01-02T00:00:00Z",
+      description: "Test app",
+      timeZone: "(UTC-08:00) Pacific Time (US & Canada)",
+      dateFormat: "MM-DD-YYYY",
+      hasEveryoneOnTheInternet: false,
+      memoryInfo: { estMemory: 0, estMemoryInclDependentApps: 0 },
+      securityProperties: {
+        allowClone: false,
+        allowExport: true,
+        enableAppTokens: true,
+        hideFromPublic: false,
+        mustBeRealmApproved: false,
+        useIPFilter: false,
+      },
+    };
+
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 429,
+        headers: new Headers({ "Retry-After": "1" }),
+        json: () => Promise.resolve({ message: "Too Many Requests" }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve(mockResponse),
+      });
+
+    const result = await client.getApp({ appId });
+
+    expect(result).toEqual({
+      ...mockResponse,
+      created: new Date("2025-01-01T00:00:00Z"),
+      updated: new Date("2025-01-02T00:00:00Z"),
+    });
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+    expect(mockFetch).toHaveBeenNthCalledWith(
+      1,
+      `https://api.quickbase.com/v1/apps/${appId}`,
+      expect.objectContaining({
+        method: "GET",
+        headers: expect.objectContaining({
+          "QB-Realm-Hostname": `${QB_REALM}.quickbase.com`,
+          Authorization: `QB-USER-TOKEN ${QB_USER_TOKEN}`,
+          "Content-Type": "application/json",
+        }),
+        credentials: "omit",
+      })
+    );
+    expect(mockFetch).toHaveBeenNthCalledWith(
+      2,
+      `https://api.quickbase.com/v1/apps/${appId}`,
+      expect.objectContaining({
+        method: "GET",
+        headers: expect.objectContaining({
+          "QB-Realm-Hostname": `${QB_REALM}.quickbase.com`,
+          Authorization: `QB-USER-TOKEN ${QB_USER_TOKEN}`,
+          "Content-Type": "application/json",
+        }),
+        credentials: "omit",
+      })
+    );
+  });
+
+  it("throws RateLimitError after max retries on 429", async () => {
+    client = createClient(mockFetch, {
+      realm: QB_REALM,
+      userToken: QB_USER_TOKEN,
+      debug: true,
+      maxRetries: 1,
+      retryDelay: 100,
+      throttle: { rate: 10, burst: 10 },
+    });
+
+    const appId = QB_APP_ID;
+
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 429,
+        headers: new Headers({ "Retry-After": "1" }),
+        json: () => Promise.resolve({ message: "Too Many Requests" }),
+      })
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 429,
+        headers: new Headers({ "Retry-After": "1" }),
+        json: () => Promise.resolve({ message: "Too Many Requests" }),
+      });
+
+    await expect(client.getApp({ appId })).rejects.toMatchObject({
+      name: "RateLimitError",
+      message: "API Error: Too Many Requests (Status: 429)",
+      status: 429,
+      retryAfter: 1,
+    });
+
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it("respects throttle limits without exceeding rate", async () => {
+    client = createClient(mockFetch, {
+      realm: QB_REALM,
+      userToken: QB_USER_TOKEN,
+      debug: true,
+      throttle: { rate: 5, burst: 5 },
+    });
+
+    const appId = QB_APP_ID;
+
+    const mockResponse: GetApp200Response = {
+      id: appId,
+      name: "TestApp",
+      created: "2025-01-01T00:00:00Z",
+      updated: "2025-01-02T00:00:00Z",
+      description: "Test app",
+      timeZone: "(UTC-08:00) Pacific Time (US & Canada)",
+      dateFormat: "MM-DD-YYYY",
+      hasEveryoneOnTheInternet: false,
+      memoryInfo: { estMemory: 0, estMemoryInclDependentApps: 0 },
+      securityProperties: {
+        allowClone: false,
+        allowExport: true,
+        enableAppTokens: true,
+        hideFromPublic: false,
+        mustBeRealmApproved: false,
+        useIPFilter: false,
+      },
+    };
+
+    mockFetch.mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve(mockResponse),
+    });
+
+    const startTime = Date.now();
+    await Promise.all([
+      client.getApp({ appId }),
+      client.getApp({ appId }),
+      client.getApp({ appId }),
+      client.getApp({ appId }),
+      client.getApp({ appId }),
+      client.getApp({ appId }), // 6th call triggers throttle
+    ]);
+    const endTime = Date.now();
+    const durationMs = endTime - startTime;
+
+    expect(mockFetch).toHaveBeenCalledTimes(6);
+    expect(durationMs).toBeGreaterThanOrEqual(200);
+    expect(durationMs).toBeLessThan(1000);
+  });
+});

package/tests/vitest/unit/tables/updateRelationship.test.ts

@@ -0,0 +1,305 @@
+// tests/vitest/unit/tables/updateRelationship.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 {
+  UpdateRelationshipRequest,
+  UpdateRelationship200Response,
+} from "@/generated/models";
+
+describe("QuickbaseClient Unit - updateRelationship", () => {
+  let client: ReturnType<typeof createClient>;
+
+  beforeEach(() => {
+    mockFetch.mockClear();
+  });
+
+  it("initializes without errors and has updateRelationship method", () => {
+    client = createClient(mockFetch, { debug: true });
+    expect(client).toBeDefined();
+    expect(typeof client.updateRelationship).toBe("function");
+  });
+
+  it("updates relationship successfully with user token", async () => {
+    client = createClient(mockFetch, { debug: true });
+
+    const tableId = QB_TABLE_ID_1;
+    const relationshipId = 6;
+
+    const request: UpdateRelationshipRequest = {
+      lookupFieldIds: [4, 5, 6],
+      summaryFields: [
+        {
+          summaryFid: 3,
+          label: "my summary field",
+          accumulationType: "COUNT",
+          where: "{'3'.EX.'1'}",
+        },
+      ],
+    };
+
+    const mockResponse: UpdateRelationship200Response = {
+      id: relationshipId,
+      parentTableId: "bck7gp3q2",
+      childTableId: tableId,
+      foreignKeyField: {
+        id: relationshipId,
+        label: "Related record",
+        type: "numeric",
+      },
+      isCrossApp: false,
+      lookupFields: [
+        { id: 4, label: "Field 4", type: "text" },
+        { id: 5, label: "Field 5", type: "numeric" },
+        { id: 6, label: "Field 6", type: "date" },
+      ],
+      summaryFields: [{ id: 8, label: "my summary field", type: "numeric" }],
+    };
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve(mockResponse),
+    });
+
+    const result = await client.updateRelationship({
+      tableId,
+      relationshipId,
+      body: request,
+    });
+
+    expect(result).toEqual(mockResponse);
+    expect(mockFetch).toHaveBeenCalledWith(
+      `https://api.quickbase.com/v1/tables/${tableId}/relationship/${relationshipId}`, // Changed to singular
+      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),
+        credentials: "omit",
+      })
+    );
+  });
+
+  it("updates relationship successfully with temp token", async () => {
+    client = createClient(mockFetch, { useTempTokens: true, debug: true });
+
+    const tableId = QB_TABLE_ID_1;
+    const relationshipId = 6;
+
+    const request: UpdateRelationshipRequest = {
+      lookupFieldIds: [7],
+      summaryFields: [
+        {
+          summaryFid: 0,
+          label: "Count of Records",
+          accumulationType: "COUNT",
+          where: "{'3'.GT.0}",
+        },
+      ],
+    };
+
+    const mockResponse: UpdateRelationship200Response = {
+      id: relationshipId,
+      parentTableId: "bck7gp3q2",
+      childTableId: tableId,
+      foreignKeyField: {
+        id: relationshipId,
+        label: "Related record",
+        type: "numeric",
+      },
+      isCrossApp: false,
+      lookupFields: [{ id: 7, label: "record - text field", type: "text" }],
+      summaryFields: [{ id: 9, label: "Count of Records", type: "numeric" }],
+    };
+
+    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.updateRelationship({
+      tableId,
+      relationshipId,
+      body: request,
+    });
+
+    expect(result).toEqual(mockResponse);
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+    expect(mockFetch).toHaveBeenNthCalledWith(
+      1,
+      `https://api.quickbase.com/v1/auth/temporary/${tableId}`,
+      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/tables/${tableId}/relationship/${relationshipId}`, // Changed to singular
+      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),
+        credentials: "omit",
+      })
+    );
+  });
+
+  it("retries successfully after 401 with temp token", async () => {
+    client = createClient(mockFetch, { useTempTokens: true, debug: true });
+
+    const tableId = QB_TABLE_ID_1;
+    const relationshipId = 6;
+
+    const request: UpdateRelationshipRequest = {
+      lookupFieldIds: [4],
+    };
+
+    const mockResponse: UpdateRelationship200Response = {
+      id: relationshipId,
+      parentTableId: "bck7gp3q2",
+      childTableId: tableId,
+      foreignKeyField: {
+        id: relationshipId,
+        label: "Related record",
+        type: "numeric",
+      },
+      isCrossApp: false,
+      lookupFields: [{ id: 4, label: "Field 4", type: "text" }],
+      summaryFields: [],
+    };
+
+    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.updateRelationship({
+      tableId,
+      relationshipId,
+      body: request,
+    });
+
+    expect(result).toEqual(mockResponse);
+    expect(mockFetch).toHaveBeenCalledTimes(4);
+    expect(mockFetch).toHaveBeenNthCalledWith(
+      1,
+      `https://api.quickbase.com/v1/auth/temporary/${tableId}`,
+      expect.any(Object)
+    );
+    expect(mockFetch).toHaveBeenNthCalledWith(
+      2,
+      `https://api.quickbase.com/v1/tables/${tableId}/relationship/${relationshipId}`, // Changed to singular
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: "QB-TEMP-TOKEN initial_token",
+        }),
+      })
+    );
+    expect(mockFetch).toHaveBeenNthCalledWith(
+      3,
+      `https://api.quickbase.com/v1/auth/temporary/${tableId}`,
+      expect.any(Object)
+    );
+    expect(mockFetch).toHaveBeenNthCalledWith(
+      4,
+      `https://api.quickbase.com/v1/tables/${tableId}/relationship/${relationshipId}`, // Changed to singular
+      expect.objectContaining({
+        headers: expect.objectContaining({
+          Authorization: "QB-TEMP-TOKEN new_token",
+        }),
+      })
+    );
+    expect(consoleSpy).toHaveBeenCalledWith(
+      "Authorization error for updateRelationship (temp token), refreshing token:",
+      expect.any(String)
+    );
+    expect(consoleSpy).toHaveBeenCalledWith(
+      "Retrying updateRelationship with temp token"
+    );
+    consoleSpy.mockRestore();
+  });
+
+  it("handles 400 error for invalid request", async () => {
+    client = createClient(mockFetch, { debug: true });
+
+    const tableId = QB_TABLE_ID_1;
+    const relationshipId = 6;
+
+    const request: UpdateRelationshipRequest = {
+      lookupFieldIds: [-1],
+    };
+
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 400,
+      json: () => Promise.resolve({ message: "Invalid field ID" }),
+    });
+
+    await expect(
+      client.updateRelationship({
+        tableId,
+        relationshipId,
+        body: request,
+      })
+    ).rejects.toThrow("API Error: Invalid field ID (Status: 400)");
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      `https://api.quickbase.com/v1/tables/${tableId}/relationship/${relationshipId}`, // Changed to singular
+      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),
+        credentials: "omit",
+      })
+    );
+  });
+});

package/tests/vitest/unit/tokenLifespan.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { createClient, mockFetch, QB_APP_ID, QB_REALM } from "@tests/setup.ts";
+import { UpdateAppRequest, UpdateApp200Response } from "@/generated/models";
+
+describe("QuickbaseClient Unit - Token Lifespan", () => {
+  let client: ReturnType<typeof createClient>;
+
+  beforeEach(() => {
+    mockFetch.mockClear();
+  });
+
+  it("reuses token within lifespan and fetches new token after expiration", async () => {
+    // Set a short lifespan of 500ms for testing
+    client = createClient(mockFetch, {
+      realm: QB_REALM,
+      useTempTokens: true,
+      tokenLifespan: 500, // 0.5 seconds
+      debug: true,
+    });
+
+    const request: UpdateAppRequest = {
+      name: "Test App",
+    };
+    const mockResponse: UpdateApp200Response = {
+      id: QB_APP_ID,
+      name: "Test App",
+      description: "",
+      created: new Date("2020-01-01T00:00:00Z"),
+      updated: new Date("2020-01-01T00:00:00Z"),
+      dateFormat: "MM-DD-YYYY",
+      timeZone: "(UTC-08:00) Pacific Time (US & Canada)",
+      hasEveryoneOnTheInternet: false,
+      ancestorId: null,
+      variables: [],
+      securityProperties: {},
+      memoryInfo: { estMemory: 0, estMemoryInclDependentApps: 0 },
+      dataClassification: "None",
+    };
+
+    // First call: Fetch a new token
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve({ temporaryAuthorization: "token1" }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve(mockResponse),
+      });
+
+    await client.updateApp({ appId: QB_APP_ID, body: request });
+    expect(mockFetch).toHaveBeenCalledTimes(2); // Token fetch + API call
+
+    // Second call within lifespan: Should reuse token1
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve(mockResponse),
+    });
+    await client.updateApp({ appId: QB_APP_ID, body: request });
+    expect(mockFetch).toHaveBeenCalledTimes(3); // Only API call, no new token fetch
+
+    // Wait for token to expire (500ms + buffer)
+    await new Promise((resolve) => setTimeout(resolve, 600));
+
+    // Third call after expiration: Should fetch a new token
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve({ temporaryAuthorization: "token2" }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve(mockResponse),
+      });
+    await client.updateApp({ appId: QB_APP_ID, body: request });
+    expect(mockFetch).toHaveBeenCalledTimes(5); // New token fetch + API call
+  });
+
+  it("uses default lifespan when not specified", async () => {
+    // No tokenLifespan provided, should use default (4:50 = 290,000ms)
+    client = createClient(mockFetch, {
+      realm: QB_REALM,
+      useTempTokens: true,
+      debug: true,
+    });
+
+    const request: UpdateAppRequest = {
+      name: "Default Lifespan Test",
+    };
+    const mockResponse: UpdateApp200Response = {
+      id: QB_APP_ID,
+      name: "Default Lifespan Test",
+      description: "",
+      created: new Date("2020-01-01T00:00:00Z"),
+      updated: new Date("2020-01-01T00:00:00Z"),
+      dateFormat: "MM-DD-YYYY",
+      timeZone: "(UTC-08:00) Pacific Time (US & Canada)",
+      hasEveryoneOnTheInternet: false,
+      ancestorId: null,
+      variables: [],
+      securityProperties: {},
+      memoryInfo: { estMemory: 0, estMemoryInclDependentApps: 0 },
+      dataClassification: "None",
+    };
+
+    // First call: Fetch a new token
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: () =>
+          Promise.resolve({ temporaryAuthorization: "default_token" }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve(mockResponse),
+      });
+
+    await client.updateApp({ appId: QB_APP_ID, body: request });
+    expect(mockFetch).toHaveBeenCalledTimes(2); // Token fetch + API call
+
+    // Second call within default lifespan (e.g., after 1 second, well below 4:50)
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve(mockResponse),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 1000)); // Wait 1 second
+    await client.updateApp({ appId: QB_APP_ID, body: request });
+    expect(mockFetch).toHaveBeenCalledTimes(3); // No new token fetch, still within 4:50
+  });
+});

package/tools/log-gen.ts

@@ -18,20 +18,20 @@ const excludeDirs: string[] = [
 // prettier-ignore
 const includeFolders: string[] = [
   // "open-api",
-  // "open-api/definitions",
-  // "open-api/paths",
 ];
 
 // prettier-ignore
 const includeRecursiveFolders: string[] = [
-  "open-api"
+  // "open-api"
   // "tests",
   // "tests/vitest/unit",
-  // "tests/vitest/qb"
+  "tests/vitest/qb"
 ];
 
 // prettier-ignore
 const includeFiles: string[] = [
+  // "tests/setup.ts",
+
   // "package.json",
   // "tsconfig.json",
   // "tsconfig.build.json",
@@ -43,7 +43,11 @@ const includeFiles: string[] = [
   // "src/tokenCache.ts",
   // "src/generated/runtime.ts",
   // "src/quickbaseClient.ts",
+  // "src/invokeMethod.ts",
   // "src/generated-unified/QuickbaseClient.ts",
+
+  // "src/RateLimitError.ts",
+  // "src/TokenBucket.ts"
 ];
 
 const projectGoals: string[] = [