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

package/src/quickbaseClient.ts

@@ -1,9 +1,19 @@
 // src/quickbaseClient.ts
+
 import { QuickbaseClient as IQuickbaseClient } from "./generated-unified/QuickbaseClient";
-import { Configuration, HTTPHeaders, ResponseError } from "./generated/runtime";
+import { Configuration, HTTPHeaders } from "./generated/runtime";
 import * as apis from "./generated/apis";
 import { TokenCache } from "./tokenCache";
 import { simplifyName } from "./utils";
+import { invokeMethod, MethodInfo } from "./invokeMethod";
+import {
+  TempTokenStrategy,
+  UserTokenStrategy,
+  AuthorizationStrategy,
+  SsoTokenStrategy,
+} from "./authorizationStrategy";
+import { ThrottleBucket } from "./ThrottleBucket";
+import { RateLimiter } from "./rateLimiter";
 
 export * from "./generated/models/index";
 
@@ -14,26 +24,17 @@ export interface QuickbaseConfig {
   userToken?: string;
   tempToken?: string;
   useTempTokens?: boolean;
+  useSso?: boolean;
+  samlToken?: string;
   debug?: boolean;
   fetchApi?: typeof fetch;
-  convertDates?: boolean; // New flag to control date string conversion, defaults to true
-}
-
-export interface TempTokenParams {
-  appId?: string;
-  tableId?: string;
-  dbid?: string;
-}
-
-type ApiMethod<K extends keyof QuickbaseClient> = (
-  requestParameters: Parameters<QuickbaseClient[K]>[0],
-  initOverrides?: RequestInit
-) => Promise<ReturnType<QuickbaseClient[K]>>;
-
-interface MethodInfo<K extends keyof QuickbaseClient> {
-  api: any;
-  method: ApiMethod<K>;
-  paramMap: string[];
+  convertDates?: boolean;
+  tempTokenLifespan?: number;
+  throttle?: { rate: number; burst: number };
+  maxRetries?: number;
+  retryDelay?: number;
+  tokenCache?: TokenCache;
+  baseUrl?: string;
 }
 
 type MethodMap = {
@@ -48,18 +49,6 @@ const getParamNames = (fn: (...args: any[]) => any): string[] =>
     .map((p) => p.trim().split("=")[0]?.trim())
     .filter((p) => p && !p.match(/^\{/) && p !== "options");
 
-const extractDbid = (
-  params: Partial<TempTokenParams>,
-  errorMessage: string
-): string => {
-  const dbid = params.dbid || params.tableId || params.appId;
-  if (!dbid) {
-    throw new Error(errorMessage);
-  }
-  return dbid;
-};
-
-// Utility to convert ISO date strings to Date objects recursively, with optional conversion
 function transformDates(obj: any, convertStringsToDates: boolean = true): any {
   if (obj === null || obj === undefined) return obj;
   if (obj instanceof Date) return obj;
@@ -86,47 +75,82 @@ function transformDates(obj: any, convertStringsToDates: boolean = true): any {
   return obj;
 }
 
+function inferHttpMethod(methodSource: string, debug?: boolean): string {
+  const methodMatches = [
+    ...methodSource.matchAll(/method:\s*['"]?(\w+)['"]?/gi),
+  ];
+  const method =
+    methodMatches.length > 0
+      ? methodMatches[methodMatches.length - 1][1].toUpperCase()
+      : "GET";
+  if (debug) {
+    console.log(`[inferHttpMethod] Source:`, methodSource);
+    console.log(
+      `[inferHttpMethod] All matches:`,
+      methodMatches.map((m) => m[0])
+    );
+    console.log(`[inferHttpMethod] Extracted method:`, method);
+  }
+  return method;
+}
+
 export function quickbase(config: QuickbaseConfig): QuickbaseClient {
   const {
     realm,
     userToken,
-    tempToken: initialTempToken,
+    tempToken,
     useTempTokens,
+    useSso,
+    samlToken,
     fetchApi,
     debug,
-    convertDates = true, // Default to true for backward compatibility
+    convertDates = true,
+    tempTokenLifespan = 290000,
+    throttle = { rate: 10, burst: 10 },
+    maxRetries = 3,
+    retryDelay = 1000,
+    tokenCache: providedTokenCache,
+    baseUrl = "https://api.quickbase.com/v1",
   } = config;
-  const baseUrl = `https://api.quickbase.com/v1`;
 
-  const tokenCache = new TokenCache();
+  const tokenCache = providedTokenCache || new TokenCache(tempTokenLifespan);
+  const throttleBucket = throttle
+    ? new ThrottleBucket(throttle.rate, throttle.burst)
+    : null;
+  const rateLimiter = new RateLimiter(throttleBucket, maxRetries, retryDelay);
+
+  const defaultFetch: typeof fetch | undefined =
+    typeof globalThis.window !== "undefined"
+      ? globalThis.window.fetch.bind(globalThis.window)
+      : undefined;
+  const effectiveFetch = fetchApi || defaultFetch;
+
+  if (!effectiveFetch) {
+    throw new Error("No fetch implementation available");
+  }
+
+  const authStrategy: AuthorizationStrategy = useSso
+    ? new SsoTokenStrategy(samlToken || "", realm, effectiveFetch, debug)
+    : useTempTokens
+    ? new TempTokenStrategy(tokenCache, tempToken)
+    : new UserTokenStrategy(userToken || "");
 
   const baseHeaders: HTTPHeaders = {
     "QB-Realm-Hostname": `${realm}.quickbase.com`,
     "Content-Type": "application/json",
   };
 
-  if (initialTempToken) {
-    baseHeaders["Authorization"] = `QB-TEMP-TOKEN ${initialTempToken}`;
-  } else if (userToken && !useTempTokens) {
-    baseHeaders["Authorization"] = `QB-USER-TOKEN ${userToken}`;
-  }
-
-  const defaultFetch: typeof fetch | undefined =
-    typeof globalThis.window !== "undefined"
-      ? globalThis.window.fetch.bind(globalThis.window)
-      : undefined;
   const configuration = new Configuration({
     basePath: baseUrl,
     headers: { ...baseHeaders },
-    fetchApi: fetchApi || defaultFetch,
+    fetchApi: effectiveFetch,
     credentials: "omit",
   });
 
-  if (!configuration.fetchApi && typeof globalThis.window === "undefined") {
-    throw new Error(
-      "fetchApi must be provided in non-browser environments (e.g., Node.js)"
-    );
-  }
+  // Removed redundant check:
+  // if (!configuration.fetchApi && typeof globalThis.window === "undefined") {
+  //   throw new Error("fetchApi must be provided in non-browser environments (e.g., Node.js)");
+  // }
 
   const apiInstances = Object.fromEntries(
     Object.entries(apis)
@@ -137,8 +161,6 @@ export function quickbase(config: QuickbaseConfig): QuickbaseClient {
       ])
   );
 
-  const methodMap = buildMethodMap();
-
   function buildMethodMap(): MethodMap {
     const methodMap: Partial<MethodMap> = {};
     const isValidMethod = (name: string) =>
@@ -157,36 +179,35 @@ export function quickbase(config: QuickbaseConfig): QuickbaseClient {
           const simplifiedName = simplifyName(
             rawMethodName
           ) as keyof QuickbaseClient;
-          const method = api[rawMethodName as keyof typeof api];
+          const rawMethodKey = `${rawMethodName}Raw` as keyof typeof api;
+          const method =
+            api[rawMethodKey] || api[rawMethodName as keyof typeof api];
           const boundMethod = method.bind(api as any) as unknown;
           if (typeof boundMethod === "function" && boundMethod.length <= 2) {
+            const methodSource = method.toString();
             methodMap[simplifiedName] = {
               api,
-              method: boundMethod as ApiMethod<typeof simplifiedName>,
+              method: boundMethod as any,
               paramMap: getParamNames(method),
+              httpMethod: inferHttpMethod(methodSource, debug),
             };
           }
         });
     }
+    if (debug) {
+      console.log("[buildMethodMap] Methods:", Object.keys(methodMap));
+    }
     return methodMap as MethodMap;
   }
 
-  const fetchTempToken = async (dbid: string): Promise<string> => {
-    const effectiveFetch = fetchApi || defaultFetch;
-    if (!effectiveFetch) {
-      throw new Error(
-        "No fetch implementation available for fetching temp token"
-      );
-    }
+  const methodMap = buildMethodMap();
 
-    const response = await effectiveFetch(
-      `https://api.quickbase.com/v1/auth/temporary/${dbid}`,
-      {
-        method: "GET",
-        headers: { ...baseHeaders },
-        credentials: "include",
-      }
-    );
+  const fetchTempToken = async (dbid: string): Promise<string> => {
+    const response = await effectiveFetch(`${baseUrl}/auth/temporary/${dbid}`, {
+      method: "GET",
+      headers: { ...baseHeaders },
+      credentials: "include",
+    });
 
     if (!response.ok) {
       const errorBody: { message?: string } = await response.json();
@@ -198,204 +219,52 @@ export function quickbase(config: QuickbaseConfig): QuickbaseClient {
     }
 
     const tokenResult = await response.json();
+    console.log(`[fetchTempToken] Response:`, tokenResult);
     const token = tokenResult.temporaryAuthorization;
     if (!token) {
       throw new Error("No temporary token returned from API");
     }
-    tokenCache.set(dbid, token);
+    tokenCache.set(dbid, token, tempTokenLifespan);
     if (debug) {
       console.log(`Fetched and cached new token for dbid: ${dbid}`, token);
     }
     return token;
   };
 
-  async function invokeMethod<K extends keyof QuickbaseClient>(
-    methodName: K,
-    params: Parameters<QuickbaseClient[K]>[0] & Partial<TempTokenParams>,
-    retryCount: number = 0
-  ): Promise<ReturnType<QuickbaseClient[K]>> {
-    const methodInfo = methodMap[methodName];
-    if (!methodInfo) {
-      throw new Error(`Method ${methodName} not found`);
-    }
-
-    // Safely handle body extraction
-    const hasBody = "body" in params && params.body !== undefined;
-    const body = hasBody ? (params as any).body : undefined;
-    const restParams: any = hasBody
-      ? Object.fromEntries(
-          Object.entries(params).filter(([key]) => key !== "body")
-        )
-      : { ...params };
-
-    // Construct requestParameters with 'generated' for body
-    const requestParameters: any = {
-      ...restParams,
-      ...(body ? { generated: { ...body } } : {}),
-    };
-
-    let requestOptions: RequestInit = {
-      credentials: "omit",
-    };
-
-    const selectedToken =
-      initialTempToken || (userToken && !useTempTokens ? userToken : undefined);
-
-    if (methodName === "getTempTokenDBID" && useTempTokens) {
-      const dbid = extractDbid(params, "No dbid provided for getTempTokenDBID");
-      const cachedToken = tokenCache.get(dbid);
-      if (cachedToken) {
-        return { temporaryAuthorization: cachedToken } as ReturnType<
-          QuickbaseClient[K]
-        >;
-      }
-    }
-
-    let authorizationToken = selectedToken;
-    if (useTempTokens && !authorizationToken) {
-      const dbid = extractDbid(
-        params,
-        `No dbid found in params for ${methodName} to fetch temp token`
-      );
-      const cachedToken = tokenCache.get(dbid);
-      authorizationToken = cachedToken || (await fetchTempToken(dbid));
-      if (methodName === "getTempTokenDBID") {
-        return { temporaryAuthorization: authorizationToken } as ReturnType<
-          QuickbaseClient[K]
-        >;
-      }
-      requestOptions.headers = {
-        ...baseHeaders,
-        Authorization: `QB-TEMP-TOKEN ${authorizationToken}`,
-      };
-    } else if (authorizationToken) {
-      requestOptions.headers = {
-        ...baseHeaders,
-        Authorization: `QB-USER-TOKEN ${authorizationToken}`,
-      };
-    }
-
-    if (debug) {
-      console.log(`[${methodName}] requestParameters:`, requestParameters);
-      console.log(`[${methodName}] requestOptions:`, requestOptions);
-    }
-
-    try {
-      const response = await methodInfo.method(
-        requestParameters,
-        requestOptions
+  const proxyHandler: ProxyHandler<QuickbaseClient> = {
+    get: (_, prop: string) => {
+      console.log(
+        "[proxy] Accessing:",
+        prop,
+        "in methodMap:",
+        prop in methodMap
       );
-      if (debug) {
-        console.log(`[${methodName}] rawResponse:`, response);
-      }
-      if (response instanceof Response) {
-        const contentType = response.headers.get("Content-Type")?.toLowerCase();
-        if (debug) {
-          console.log(`[${methodName}] contentType:`, contentType);
-        }
-        if (contentType?.includes("application/octet-stream")) {
-          return (await response.arrayBuffer()) as ReturnType<
-            QuickbaseClient[K]
-          >;
-        } else if (
-          contentType?.includes("application/x-yaml") ||
-          contentType?.includes("text/yaml")
-        ) {
-          return (await response.text()) as ReturnType<QuickbaseClient[K]>;
-        } else if (contentType?.includes("application/json")) {
-          const jsonResponse = await response.json();
-          if (debug) {
-            console.log(`[${methodName}] jsonResponse:`, jsonResponse);
-          }
-          const transformedResponse = transformDates(
-            jsonResponse,
-            convertDates
-          );
-          if (debug) {
-            console.log(
-              `[${methodName}] transformedResponse:`,
-              transformedResponse
-            );
-          }
-          return transformedResponse as ReturnType<QuickbaseClient[K]>;
-        }
-        return response as ReturnType<QuickbaseClient[K]>;
-      } else {
-        if (debug) {
-          console.log(
-            `[${methodName}] non-Response return, applying transform:`,
-            response
-          );
-        }
-        const transformedResponse = transformDates(response, convertDates);
-        if (debug) {
-          console.log(
-            `[${methodName}] transformedNonResponse:`,
-            transformedResponse
-          );
-        }
-        return transformedResponse as ReturnType<QuickbaseClient[K]>;
-      }
-    } catch (error) {
-      if (
-        error instanceof ResponseError &&
-        error.response.status === 401 &&
-        retryCount < 1 &&
-        useTempTokens
-      ) {
-        if (debug) {
-          console.log(
-            `Authorization error for ${methodName}, refreshing token:`,
-            error.message
-          );
-        }
-        const dbid = extractDbid(
-          params,
-          `No dbid to refresh token after authorization error`
-        );
-        authorizationToken = await fetchTempToken(dbid);
-        requestOptions.headers = {
-          ...baseHeaders,
-          Authorization: `QB-TEMP-TOKEN ${authorizationToken}`,
-        };
-        if (debug) {
-          console.log(`Retrying ${methodName} with new token`);
-        }
-        return invokeMethod(methodName, params, retryCount + 1);
-      }
-      if (error instanceof ResponseError) {
-        let errorMessage = error.message;
-        try {
-          const errorBody: { message?: string } = await error.response.json();
-          if (debug) {
-            console.log(`Error response body for ${methodName}:`, errorBody);
-          }
-          errorMessage = errorBody.message || errorMessage;
-        } catch (e) {
-          // Silent fail on parse error
-        }
-        throw new Error(
-          `API Error: ${errorMessage} (Status: ${error.response.status})`
-        );
-      }
-      throw error;
-    }
-  }
-
-  const proxy = new Proxy<QuickbaseClient>({} as QuickbaseClient, {
-    get: (_, prop: string): ((params: any) => Promise<any>) | undefined => {
       if (prop in methodMap) {
         const methodName = prop as keyof QuickbaseClient;
         return (params: Parameters<QuickbaseClient[typeof methodName]>[0]) =>
-          invokeMethod(methodName, params);
+          invokeMethod(
+            methodName,
+            params,
+            methodMap,
+            baseHeaders,
+            authStrategy,
+            rateLimiter,
+            fetchTempToken,
+            transformDates,
+            debug,
+            convertDates
+          );
       }
+      console.log("[proxy] Method not found:", prop);
       return undefined;
     },
-  });
+  };
+
+  const proxy = new Proxy<QuickbaseClient>({} as QuickbaseClient, proxyHandler);
 
   if (debug) {
     console.log("[createClient] Config:", config);
-    console.log("[createClient] Returning:", proxy);
+    console.log("[createClient] Proxy created:", proxy);
   }
 
   return proxy;

package/src/rateLimiter.ts

@@ -0,0 +1,25 @@
+// src/rateLimiter.ts
+import { ThrottleBucket } from "./ThrottleBucket";
+import { ResponseError } from "./generated/runtime";
+
+export class RateLimiter {
+  constructor(
+    private throttleBucket: ThrottleBucket | null,
+    public maxRetries: number = 3,
+    private retryDelay: number = 1000
+  ) {}
+
+  async throttle(): Promise<void> {
+    if (this.throttleBucket) {
+      await this.throttleBucket.acquire();
+    }
+  }
+
+  async handle429(error: ResponseError, attempt: number): Promise<number> {
+    // Remove the throw here; let invokeMethod handle exhaustion
+    const retryAfter = error.response.headers.get("Retry-After");
+    return retryAfter
+      ? parseInt(retryAfter, 10) * 1000
+      : this.retryDelay * Math.pow(2, attempt - 1);
+  }
+}

package/src/tokenCache.ts

@@ -1,50 +1,34 @@
+// src/tokenCache.ts
 interface CachedToken {
   token: string;
-  expiresAt: number; // Timestamp in milliseconds
+  expiresAt: number;
 }
 
 export class TokenCache {
   private cache: Map<string, CachedToken>;
-  private readonly lifespan: number; // Token lifespan in milliseconds
+  private readonly tempTokenLifespan: number;
 
-  constructor(lifespan: number = 4 * 60 * 1000 + 50 * 1000) {
-    // Default 4:50
+  constructor(tempTokenLifespan: number = 4 * 60 * 1000 + 50 * 1000) {
     this.cache = new Map<string, CachedToken>();
-    this.lifespan = lifespan;
+    this.tempTokenLifespan = tempTokenLifespan;
   }
 
   get(dbid: string): string | undefined {
     const entry = this.cache.get(dbid);
     const now = Date.now();
-    if (entry && entry.expiresAt > now) {
-      return entry.token;
-    }
-    return undefined; // Expired or not found
+    if (entry && entry.expiresAt > now) return entry.token;
+    if (entry) this.cache.delete(dbid); // Clean up expired temp tokens
+    return undefined;
   }
 
-  // New method to get full entry
-  getEntry(dbid: string): CachedToken | undefined {
-    const entry = this.cache.get(dbid);
-    const now = Date.now();
-    if (entry && entry.expiresAt > now) {
-      return entry;
-    }
-    return undefined; // Expired or not found
-  }
-
-  set(dbid: string, token: string): void {
+  set(dbid: string, token: string, lifespan?: number): void {
     const now = Date.now();
     this.cache.set(dbid, {
       token,
-      expiresAt: now + this.lifespan,
+      expiresAt: now + (lifespan || this.tempTokenLifespan),
     });
   }
 
-  dump(): [string, CachedToken][] {
-    return Array.from(this.cache.entries());
-  }
-
-  // New method to clear the cache
   clear(): void {
     this.cache.clear();
   }

package/tests/setup.ts

@@ -38,12 +38,14 @@ export const createClient = (
     userToken,
     debug: true,
     fetchApi,
+    throttle: { rate: 10, burst: 10 }, // Throttle at 10 req/s with 10 burst capacity
     ...config, // Allow overrides if provided
   });
   console.log("[createClient] Config:", {
     realm,
     userToken,
     debug: true,
+    throttle: { rate: 10, burst: 10 },
     ...config,
   });
   console.log("[createClient] Returning:", client);

package/tests/vitest/qb/apps/getApp.test.ts

@@ -1,3 +1,4 @@
+// tests/vitest/qb/apps/getApp.test.ts
 import { test, expect } from "vitest";
 import { quickbase } from "../../../../src/quickbaseClient";
 
@@ -20,8 +21,8 @@ test(
     expect(result).toEqual({
       id: getAppId,
       name: "qb-copy",
-      created: expect.any(Date), // Matches Date object from client
-      updated: expect.any(Date), // Matches Date object from client
+      created: expect.any(Date),
+      updated: expect.any(Date),
       description: "",
       timeZone: "(UTC-08:00) Pacific Time (US & Canada)",
       dateFormat: "MM-DD-YYYY",
@@ -35,6 +36,9 @@ test(
         mustBeRealmApproved: false,
         useIPFilter: false,
       },
+      ancestorId: undefined,
+      dataClassification: undefined,
+      variables: [{ name: "TestVar", value: "TestValue" }],
     });
   }
 );

package/tests/vitest/qb/apps/getAppEvents.test.ts

@@ -0,0 +1,67 @@
+import { test, expect } from "vitest";
+import { quickbase } from "../../../../src/quickbaseClient";
+
+test(
+  "QuickbaseClient Integration - getAppEvents > fetches real app events from QuickBase",
+  { timeout: 10000 },
+  async () => {
+    const config = {
+      realm: process.env.QB_REALM || "",
+      userToken: process.env.QB_USER_TOKEN || "",
+      debug: true,
+    };
+    const client = quickbase(config);
+    const appId = "buwai2zpe"; // Same app ID as getApp test
+
+    console.log("Config used:", config);
+    const result = await client.getAppEvents({ appId });
+    console.log("Real API response:", result);
+
+    // Validate the response is an array of events
+    expect(result).toBeInstanceOf(Array);
+
+    // Check that each event has the required properties
+    result.forEach((event) => {
+      expect(event).toHaveProperty("type");
+      expect([
+        "qb-action",
+        "webhook",
+        "email-notification",
+        "subscription",
+        "reminder",
+        "automation",
+      ]).toContain(event.type);
+
+      expect(event).toHaveProperty("owner");
+      expect(event.owner).toHaveProperty("email");
+      expect(typeof event.owner.email).toBe("string");
+      expect(event.owner).toHaveProperty("id");
+      expect(typeof event.owner.id).toBe("string");
+      expect(event.owner).toHaveProperty("name");
+      expect(typeof event.owner.name).toBe("string");
+      // userName is optional, so we don't enforce it
+
+      expect(event).toHaveProperty("isActive");
+      expect(typeof event.isActive).toBe("boolean");
+
+      expect(event).toHaveProperty("tableId");
+      expect(typeof event.tableId).toBe("string");
+
+      // Name is present for all types except automation
+      if (event.type !== "automation") {
+        expect(event).toHaveProperty("name");
+        expect(typeof event.name).toBe("string");
+      } else {
+        expect(event.name).toBeUndefined();
+      }
+
+      // URL is only present for automation
+      if (event.type === "automation") {
+        expect(event).toHaveProperty("url");
+        expect(typeof event.url).toBe("string");
+      } else {
+        expect(event.url).toBeUndefined();
+      }
+    });
+  }
+);