quickbase-js 0.1.0-beta.11 → 0.1.0-beta.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quickbase-js",
-  "version": "0.1.0-beta.11",
+  "version": "0.1.0-beta.13",
   "description": "QuickBase JavaScript client for frameworks and vanilla JS",
   "type": "module",
   "main": "dist/esm/quickbase.js",
@@ -53,12 +53,14 @@
     "test:vitest:qb:fields": "vitest run tests/vitest/qb/fields/*.test.ts",
     "test:vitest:qb:records": "vitest run tests/vitest/qb/records/*.test.ts",
     "test:vitest:qb:tables": "vitest run tests/vitest/qb/tables/*.test.ts",
+    "test:vitest:qb:quickbase-js": "vitest run tests/vitest/qb/quickbase-js/*.test.ts",
     "test:vitest:unit:apps": "vitest run tests/vitest/unit/apps/*.test.ts",
     "test:vitest:unit:auth": "vitest run tests/vitest/unit/auth/*.test.ts",
     "test:vitest:unit:fields": "vitest run tests/vitest/unit/fields/*.test.ts",
     "test:vitest:unit:formulas": "vitest run tests/vitest/unit/formulas/*.test.ts",
     "test:vitest:unit:records": "vitest run tests/vitest/unit/records/*.test.ts",
     "test:vitest:unit:tables": "vitest run tests/vitest/unit/tables/*.test.ts",
+    "test:vitest:unit:quickbase-js": "vitest run tests/vitest/unit/quickbase-js/*.test.ts",
     "test:pw:qb:auth": "playwright test tests/playwright/qb/auth"
   },
   "devDependencies": {

package/src/BurstAwareThrottleBucket.ts

@@ -0,0 +1,57 @@
+// src/BurstAwareThrottleBucket.ts
+import { Semaphore } from "./Semaphore";
+import { RateThrottleBucket } from "./RateThrottleBucket";
+
+export class BurstAwareThrottleBucket implements RateThrottleBucket {
+  maxTokens: number;
+  windowSeconds: number;
+  requestTimestamps: number[] = [];
+  semaphore: Semaphore;
+
+  constructor(options: { maxTokens: number; windowSeconds: number }) {
+    this.maxTokens = options.maxTokens;
+    this.windowSeconds = options.windowSeconds;
+    this.semaphore = new Semaphore(this.maxTokens);
+  }
+
+  countRequestsInWindow() {
+    const now = Date.now();
+    this.requestTimestamps = this.requestTimestamps.filter(
+      (ts) => now - ts < this.windowSeconds * 1000
+    );
+    return this.requestTimestamps.length;
+  }
+
+  availableTokens() {
+    const windowCount = this.countRequestsInWindow();
+    return Math.max(
+      0,
+      Math.min(100 - windowCount, this.maxTokens - windowCount)
+    );
+  }
+
+  async acquire() {
+    while (true) {
+      const available = this.availableTokens();
+      if (available > 0 && this.semaphore.available() > 0) {
+        await this.semaphore.acquire();
+        this.requestTimestamps.push(Date.now());
+        return;
+      }
+      const now = Date.now();
+      const oldestTimestamp = this.requestTimestamps[0];
+      let waitTime = 100;
+      if (oldestTimestamp) {
+        waitTime = Math.max(
+          0,
+          this.windowSeconds * 1000 - (now - oldestTimestamp)
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, waitTime));
+    }
+  }
+
+  release() {
+    this.semaphore.release();
+  }
+}

package/src/FlowThrottleBucket.ts

@@ -0,0 +1,47 @@
+// src/FlowThrottleBucket.ts
+import { Semaphore } from "./Semaphore";
+import { RateThrottleBucket } from "./RateThrottleBucket";
+
+export class FlowThrottleBucket implements RateThrottleBucket {
+  private tokens: number;
+  private maxTokens: number;
+  private refillRate: number;
+  private lastRefill: number;
+  private semaphore: Semaphore;
+
+  constructor(rate: number, burst: number) {
+    this.tokens = burst;
+    this.maxTokens = burst;
+    this.refillRate = rate;
+    this.lastRefill = Date.now();
+    this.semaphore = new Semaphore(burst);
+  }
+
+  private refill(): void {
+    const now = Date.now();
+    const elapsed = (now - this.lastRefill) / 1000;
+    const newTokens = elapsed * this.refillRate;
+    this.tokens = Math.min(this.maxTokens, this.tokens + newTokens);
+    this.lastRefill = now;
+  }
+
+  async acquire(): Promise<void> {
+    await this.semaphore.acquire();
+    try {
+      this.refill();
+      while (this.tokens < 1) {
+        const waitTime = ((1 - this.tokens) / this.refillRate) * 1000;
+        await new Promise((resolve) => setTimeout(resolve, waitTime));
+        this.refill();
+      }
+      this.tokens -= 1;
+    } catch (error) {
+      this.semaphore.release();
+      throw error;
+    }
+  }
+
+  release(): void {
+    this.semaphore.release();
+  }
+}

package/src/RateThrottleBucket.ts

@@ -0,0 +1,5 @@
+// src/RateThrottleBucket.ts
+export interface RateThrottleBucket {
+  acquire(): Promise<void>;
+  release(): void;
+}

package/src/Semaphore.ts

@@ -0,0 +1,33 @@
+// src/Semaphore.ts
+export class Semaphore {
+  private permits: number;
+  private waiting: Array<{ resolve: () => void; reject: (err: any) => void }> =
+    [];
+
+  constructor(maxPermits: number) {
+    this.permits = maxPermits;
+  }
+
+  async acquire(): Promise<void> {
+    if (this.permits > 0) {
+      this.permits -= 1;
+      return;
+    }
+    return new Promise((resolve, reject) => {
+      this.waiting.push({ resolve, reject });
+    });
+  }
+
+  release(): void {
+    this.permits += 1;
+    if (this.waiting.length > 0 && this.permits > 0) {
+      const { resolve } = this.waiting.shift()!;
+      this.permits -= 1;
+      resolve();
+    }
+  }
+
+  available(): number {
+    return this.permits;
+  }
+}

package/src/authorizationStrategy.ts

@@ -1,4 +1,3 @@
-// src/authorizationStrategy.ts
 import { TokenCache } from "./tokenCache";
 
 export interface AuthorizationStrategy {
@@ -109,6 +108,12 @@ export class TempTokenStrategy implements AuthorizationStrategy {
       const newToken = await this.getToken(dbid);
       if (newToken) {
         this.tokenCache.set(dbid, newToken);
+        if (debug)
+          console.log(
+            `[${
+              methodName || "method"
+            }] Retrying with token: ${newToken.substring(0, 10)}...`
+          );
         return newToken;
       }
       return null;
@@ -213,6 +218,12 @@ export class SsoTokenStrategy implements AuthorizationStrategy {
     const newToken = await this.refreshSsoToken(debug || this.debug);
     if (newToken) {
       this.currentToken = newToken;
+      if (debug || this.debug)
+        console.log(
+          `[${
+            methodName || "method"
+          }] Retrying with token: ${newToken.substring(0, 10)}...`
+        );
       return newToken;
     }
     return null;

package/src/generated-unified/QuickbaseClient.ts

@@ -1,4 +1,4 @@
-// Generated on 2025-03-23T19:11:12.725Z
+// Generated on 2025-03-25T22:56:49.051Z
 import { AddManagersToGroup200Response, AddManagersToGroupRequest, AddMembersToGroup200Response, AddMembersToGroupRequest, AddSubgroupsToGroup200Response, AddSubgroupsToGroupRequest, Audit200Response, ChangesetSolution200Response, ChangesetSolutionFromRecord200Response, CloneUserToken200Response, CopyApp200Response, CopyAppRequest, CreateApp200Response, CreateAppRequest, CreateField200Response, CreateFieldRequest, CreateRelationship200Response, CreateRelationshipRequest, CreateSolution200Response, CreateSolutionFromRecord200Response, CreateTable200Response, CreateTableRequest, DeactivateUserToken200Response, DeleteApp200Response, DeleteAppRequest, DeleteFields200Response, DeleteFieldsRequest, DeleteFile200Response, DeleteRecords200Response, DeleteRecordsRequest, DeleteRelationship200Response, DeleteTable200Response, DeleteUserToken200Response, DenyUsers200Response, DenyUsersAndGroups200Response, DenyUsersAndGroupsRequest, DenyUsersRequest, DownloadFile200Response, ExchangeSsoToken200Response, ExportSolution200Response, ExportSolutionToRecord200Response, GenerateDocument200Response, GetApp200Response, GetAppEvents200Response, GetAppTables200Response, GetField200Response, GetFieldUsage200Response, GetFields200Response, GetFieldsUsage200Response, GetRelationships200Response, GetReport200Response, GetTable200Response, GetTableReports200Response, GetTempTokenDBID200Response, GetUsers200Response, GetUsersRequest, PlatformAnalyticEventSummaries200Response, PlatformAnalyticReads200Response, RemoveManagersFromGroup200Response, RemoveManagersFromGroupRequest, RemoveMembersFromGroup200Response, RemoveMembersFromGroupRequest, RemoveSubgroupsFromGroup200Response, RemoveSubgroupsFromGroupRequest, RunFormula200Response, RunQuery200Response, RunQueryRequest, RunReport200Response, TransferUserToken200Response, UndenyUsers200Response, UndenyUsersRequest, UpdateApp200Response, UpdateAppRequest, UpdateField200Response, UpdateFieldRequest, UpdateRelationship200Response, UpdateRelationshipRequest, UpdateSolution200Response, UpdateSolutionToRecord200Response, UpdateTable200Response, UpdateTableRequest, Upsert200Response, Upsert207Response, UpsertRequest } from "../generated/models";
 
 export interface QuickbaseClient {

package/src/invokeMethod.ts

@@ -1,9 +1,9 @@
-// src/invokeMethod.ts
 import { AuthorizationStrategy, extractDbid } from "./authorizationStrategy";
 import { RateLimiter } from "./rateLimiter";
 import { RateLimitError } from "./RateLimitError";
 import { ResponseError } from "./generated/runtime";
 import { QuickbaseClient } from "./quickbaseClient";
+import { paginateRecords, isPaginatable } from "./pagination";
 
 export type ApiMethod<K extends keyof QuickbaseClient> = (
   requestParameters: Parameters<QuickbaseClient[K]>[0],
@@ -17,12 +17,34 @@ export interface MethodInfo<K extends keyof QuickbaseClient> {
   httpMethod: string;
 }
 
+/**
+ * Invokes a Quick Base API method with the specified parameters, handling authentication, rate limiting, and pagination.
+ * @template K - The method name keyof QuickbaseClient.
+ * @param methodName - The API method to invoke (e.g., "runQuery", "changesetSolution").
+ * @param params - Parameters for the API method, potentially including skip, top, or a body.
+ * @param methodMap - Mapping of method names to their implementation details.
+ * @param baseHeaders - Base HTTP headers for API requests.
+ * @param authStrategy - Strategy for handling authentication tokens.
+ * @param rateLimiter - Rate limiting mechanism to respect API limits.
+ * @param transformDates - Function to transform date strings in the response.
+ * @param debug - If true, logs detailed invocation information.
+ * @param convertDates - If true, converts date strings to Date objects in the response.
+ * @param autoPaginate - If true, automatically paginates multi-page responses (default: true).
+ * @param attempt - Current retry attempt (default: 0).
+ * @param maxAttempts - Maximum number of retry attempts (default: rateLimiter.maxRetries + 1).
+ * @param isPaginating - Indicates if this call is part of an ongoing pagination (default: false).
+ * @returns A promise resolving to the API method's response.
+ * @throws {Error} If the method is not found or retries are exhausted.
+ */
 export async function invokeMethod<K extends keyof QuickbaseClient>(
   methodName: K,
   params: Parameters<QuickbaseClient[K]>[0] & {
     dbid?: string;
     tableId?: string;
     appId?: string;
+    startTime?: number;
+    skip?: number;
+    top?: number;
   },
   methodMap: { [P in keyof QuickbaseClient]: MethodInfo<P> },
   baseHeaders: Record<string, string>,
@@ -31,24 +53,46 @@ export async function invokeMethod<K extends keyof QuickbaseClient>(
   transformDates: (obj: any, convertStringsToDates: boolean) => any,
   debug: boolean | undefined,
   convertDates: boolean,
+  autoPaginate: boolean = true,
   attempt: number = 0,
-  maxAttempts: number = rateLimiter.maxRetries + 1
+  maxAttempts: number = rateLimiter.maxRetries + 1,
+  isPaginating: boolean = false
 ): Promise<ReturnType<QuickbaseClient[K]>> {
   const methodInfo = methodMap[methodName];
   if (!methodInfo) throw new Error(`Method ${methodName} not found`);
 
   const hasBody = "body" in params && params.body !== undefined;
   const body = hasBody ? params.body : undefined;
+  // Safely check for options only if body is an object
+  const options =
+    hasBody && body && typeof body === "object" && "options" in body
+      ? (body as any).options
+      : undefined;
+  const adjustedParams = {
+    ...params,
+    skip:
+      params.skip ?? (options && "skip" in options ? options.skip : undefined),
+    top: params.top ?? (options && "top" in options ? options.top : undefined),
+  };
+
   const restParams: any = hasBody
     ? Object.fromEntries(
-        Object.entries(params).filter(([key]) => key !== "body")
+        Object.entries(adjustedParams).filter(
+          ([key]) => key !== "body" && key !== "startTime"
+        )
       )
-    : { ...params };
+    : { ...adjustedParams, startTime: undefined };
   const requestParameters: any = {
     ...restParams,
     ...(hasBody ? { generated: body } : {}),
   };
 
+  if (debug)
+    console.log(
+      "[invokeMethod] Adjusted params for pagination:",
+      adjustedParams
+    );
+
   const requestOptions: RequestInit = {
     credentials: methodName === "getTempTokenDBID" ? "include" : "omit",
     method: methodInfo.httpMethod,
@@ -78,6 +122,25 @@ export async function invokeMethod<K extends keyof QuickbaseClient>(
         ?.toLowerCase();
       if (contentType?.includes("application/json")) {
         const jsonResponse = await rawResponse.json();
+        if (autoPaginate && !isPaginating && isPaginatable(jsonResponse)) {
+          if (debug)
+            console.log(
+              "[invokeMethod] Entering pagination with params:",
+              adjustedParams
+            );
+          return paginateRecords(
+            methodName,
+            adjustedParams,
+            methodMap,
+            baseHeaders,
+            authStrategy,
+            rateLimiter,
+            transformDates,
+            debug,
+            convertDates,
+            jsonResponse
+          );
+        }
         return transformDates(jsonResponse, convertDates) as ReturnType<
           QuickbaseClient[K]
         >;
@@ -86,6 +149,25 @@ export async function invokeMethod<K extends keyof QuickbaseClient>(
     }
     if (rawResponse && typeof rawResponse.value === "function") {
       const response = await rawResponse.value();
+      if (autoPaginate && !isPaginating && isPaginatable(response)) {
+        if (debug)
+          console.log(
+            "[invokeMethod] Entering pagination with params:",
+            adjustedParams
+          );
+        return paginateRecords(
+          methodName,
+          adjustedParams,
+          methodMap,
+          baseHeaders,
+          authStrategy,
+          rateLimiter,
+          transformDates,
+          debug,
+          convertDates,
+          response
+        );
+      }
       return transformDates(response, convertDates) as ReturnType<
         QuickbaseClient[K]
       >;
@@ -128,14 +210,24 @@ export async function invokeMethod<K extends keyof QuickbaseClient>(
   }
 
   while (attempt < maxAttempts) {
+    let acquired = false;
     try {
       await rateLimiter.throttle();
-      const response = await methodInfo.method(
-        requestParameters,
-        requestOptions
-      );
+      acquired = true;
+      const postThrottleTime = Date.now();
+      if (params.startTime !== undefined) params.startTime = postThrottleTime;
+      const headers = { ...baseHeaders };
+      const finalRequest = { ...requestParameters, headers };
+      if (debug) console.log("[invokeMethod] Sending request:", finalRequest);
+      const responsePromise = methodInfo.method(finalRequest, {
+        ...requestOptions,
+        headers,
+      });
+      rateLimiter.release();
+      const response = await responsePromise;
       return await processResponse(response);
     } catch (error: unknown) {
+      if (acquired) rateLimiter.release();
       let status: number;
       let message: string;
       let response: Response | undefined;
@@ -147,7 +239,7 @@ export async function invokeMethod<K extends keyof QuickbaseClient>(
         response = error;
         ({ message, status } = await parseErrorResponse(response));
       } else {
-        throw error; // Rethrow truly unexpected errors
+        throw error;
       }
 
       if (status === 429) {
@@ -169,7 +261,6 @@ export async function invokeMethod<K extends keyof QuickbaseClient>(
         continue;
       }
 
-      // Handle authentication errors
       let newToken: string | null;
       try {
         newToken = await authStrategy.handleError(
@@ -181,23 +272,17 @@ export async function invokeMethod<K extends keyof QuickbaseClient>(
           methodName
         );
       } catch (authError) {
-        throw authError; // Propagate the fetchTempToken error and exit immediately
+        throw authError;
       }
 
-      // Only proceed with retry if we have a valid new token
       if (newToken !== null) {
         token = newToken;
         authStrategy.applyHeaders(baseHeaders, token);
         requestOptions.headers = { ...baseHeaders };
-        if (debug)
-          console.log(
-            `[${methodName}] Retrying with token: ${token.substring(0, 10)}...`
-          );
         attempt++;
         continue;
       }
 
-      // If no new token was provided, throw the original error
       throw new Error(`API Error: ${message} (Status: ${status})`);
     }
   }