quickbase-js 1.0.1-beta.0 → 1.1.0-beta.0

package/src/generated-unified/QuickbaseClient.ts

@@ -1,15 +1,16 @@
-// Generated on 2025-03-10T01:23:11.216Z
-import { App, Field, GetTempTokenDBID200Response, Record, ReportRunResponse, Table, Upsert200Response, Upsert207Response } from "../generated/models";
+// Generated on 2025-03-11T02:50:18.896Z
+import { App, CreateApp200Response, CreateAppRequest, DeleteRecords200Response, DeleteRecordsRequest, DeleteTableResponse, Field, GetTempTokenDBID200Response, Record, ReportRunResponse, Table, UpdateTableRequest, Upsert200Response, Upsert207Response, UpsertRequest } from "../generated/models";
 
 export interface QuickbaseClient {
-  createApp: (params: { generated?: any }) => Promise<{ [key: string]: any }>;
+  createApp: (params: { body: CreateAppRequest }) => Promise<CreateApp200Response>;
   getApp: (params: { appId: string }) => Promise<App>;
   getAppEvents: (params: { appId: string }) => Promise<any[]>;
   copyApp: (params: { appId: string; generated?: any }) => Promise<{ [key: string]: any }>;
   getAppTables: (params: { appId: string }) => Promise<Table[]>;
-  getTable: (params: { appId: string; tableId: string }) => Promise<{ [key: string]: any }>;
-  updateTable: (params: { appId: string; tableId: string; generated?: { [key: string]: any } }) => Promise<{ [key: string]: any }>;
-  deleteTable: (params: { appId: string; tableId: string }) => Promise<{ [key: string]: any }>;
+  createTable: (params: { appId: string; body: any }) => Promise<Table>;
+  getTable: (params: { tableId: string; appId: string }) => Promise<Table>;
+  updateTable: (params: { tableId: string; appId: string; body: UpdateTableRequest }) => Promise<Table>;
+  deleteTable: (params: { tableId: string; appId: string }) => Promise<DeleteTableResponse>;
   getRelationships: (params: { skip?: number; tableId: string }) => Promise<{ [key: string]: any }>;
   createRelationship: (params: { tableId: string; generated?: any }) => Promise<{ [key: string]: any }>;
   updateRelationship: (params: { tableId: string; relationshipId: any; generated?: any }) => Promise<{ [key: string]: any }>;
@@ -23,8 +24,8 @@ export interface QuickbaseClient {
   getFieldsUsage: (params: { tableId: string; skip?: number; top?: number }) => Promise<any[]>;
   getFieldUsage: (params: { tableId: string; fieldId: number }) => Promise<any[]>;
   runFormula: (params: { generated?: any }) => Promise<{ [key: string]: any }>;
-  upsert: (params: { generated?: { [key: string]: any } }) => Promise<{ [key: string]: any }>;
-  deleteRecords: (params: { generated?: { [key: string]: any } }) => Promise<{ [key: string]: any }>;
+  upsert: (params: { body: UpsertRequest }) => Promise<Upsert200Response | Upsert207Response>;
+  deleteRecords: (params: { body: DeleteRecordsRequest }) => Promise<DeleteRecords200Response>;
   upsertRecords: (params: { generated: { [key: string]: string }[] }) => Promise<Upsert200Response[] | Upsert207Response[]>;
   getTempTokenDBID: (params: { dbid: string }) => Promise<GetTempTokenDBID200Response>;
   exchangeSsoToken: (params: { generated?: any }) => Promise<{ [key: string]: any }>;

package/src/log-gen.ts

@@ -2,47 +2,79 @@
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
-import yaml from "js-yaml"; // Requires "js-yaml": "^4.1.0" in package.json
+import yaml from "js-yaml";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 const rootDir: string = "./";
-const excludeDirs: string[] = ["node_modules", ".git"];
-
-const importantFolders: string[] = [];
-
-const importantFiles: string[] = [
-  "package.json",
-  "tsconfig.json",
-  "rollup.config.js",
-  "vitest.config.ts",
-  "generated-unified/QuickbaseClient.ts",
-  "src/quickbaseClient.ts",
-  "src/tokenCache.ts",
-  "src/code-generation/fix-spec-main.ts",
-  "src/code-generation/fix-spec-paths.ts",
-  "src/code-generation/fix-spec-definitions.ts",
-  "src/code-generation/regenerate-client.ts",
-  "src/code-generation/generate-unified-interface.ts",
+const excludeDirs: string[] = ["node_modules", ".git", "specs"];
+
+// prettier-ignore
+const includeFolders: string[] = [
+  // "src/code-generation",
+];
+
+// prettier-ignore
+const includeRecursiveFolders: string[] = [
+  "tests",
+];
+
+// prettier-ignore
+const includeFiles: string[] = [
+  // "package.json",
+  // "tsconfig.json",
+  // "rollup.config.js",
+  // "vitest.config.ts",
+  // "src/utils.ts",
+  // "src/tokenCache.ts",
+  // "src/generated-unified/QuickbaseClient.ts",
+  // "src/quickbaseClient.ts",
 ];
 
 const projectGoals: string[] = [
-  "Implement a QuickBase API client in TypeScript.",
-  "Generate client methods from the QuickBase RESTful API spec.",
-  "Provide a simple and intuitive interface for interacting with QuickBase.",
-  "Support both Node.js and browser environments.",
+  "A library for interacting with the QuickBase RESTful API.",
+  "Use OpenAPI to generate types and methods using a proxy. Validate with tests.",
+  "Provide robust and intuitive temporary token support for browser environments.",
+  "User Tokens support both Node.js and browser environments.",
   "Use case: JS frameworks like React, Vue, and Angular hosted in QuickBase code pages.",
-  "Node.js is supported using User Tokens",
-  "Use OpenAPI to generate the TypeScript types and methods.",
-  "Use the latest ES6+ features and TypeScript features.",
+  "Enable a flexible or native fetch in the browser.",
+  "Enable a flexible fetch framework in Node.js.",
   "#",
   "No manual updating methods when the QuickBase API changes.",
-  "The proxy magic dynamically maps generated methods.",
-  "No manual endpoint definitions—endpoints come from the generated apis (e.g., AppsApi.getApp).",
+  "The proxy magic dynamically maps generated methods and types.",
   "#",
-  "Per-Instance Store: tokenCache is defined per quickbaseClient call, so each instance has its own isolated TokenCache.",
-  "No Singleton: No shared state—tokens are fetched and cached within the current instance.",
+  "TokenCache is defined per quickbaseClient call, so each instance has its own isolated TokenCache.",
+  "Each quickbase client instance has an isolated and individual token cache.",
+];
+
+const pipelineOverview: string[] = [
+  "fix-spec-main.ts: Input: Reads the latest QuickBase_RESTful*.json file from the specs/ folder and applies fixes to the parameters and paths.",
+  "filters out the QB-Realm-Hostname, Authorization, and User-Agent parameters.",
+  "Converts parameter names to camelCase.",
+  "Fixes array schemas and applies custom paths.",
+  "Merges paths from fix-spec-paths.ts and definitions from fix-spec-definitions.ts.",
+  "Output: writes quickbase-fixed.json to src/code-generation/output/.",
+  "Key Behavior: The merge (spec.paths = { ...spec.paths, ...paths }) preserves all origional endpoints, only overriding those defined in fix-spec-paths.ts.",
+  "#",
+  "regenerate-client.ts: Uses quickbase-fixed.json to generate raw TypeScript-fetch files (src/generated/). including models and APIs.",
+  "#",
+  "generate-unified-interface.ts: Uses quickbase-fixed.json to generate a unified QuickbaseClient.ts interface in src/generated-unified/.",
+  "QuickbaseClient.ts includes all endpoints from src/code-generation/output/quickbase-fixed, and types from src/generated.",
+  "#",
+  "/specs/QuickBase_RESTful_API_*.json is over 46k lines of JSON, so it's not included in the snapshot, its too large to give to an AI.",
+  "which creates difficulties in understanding the structure of the API.",
+  "It makes it difficult to model the src/code-generation/fix-spec-*.ts files in the snapshot.",
+  "#",
+  "vitest unit and integration tests. Integration tests use the real QuickBase API with user token auth.",
+  "playwright is used to test the real QuickBase API in a browser enviornment with temporary token auth.",
+  "temp tokens can only be generated in a browser enviornment and can not be fetched with a user token.",
+  "#",
+  "getTempTokenDBID() method is wrapped to enhance temporary token generation reuse interacting with a token cache.",
+  "#",
+  "npm run fix-spec: Generates quickbase-fixed.json from the latest QuickBase_RESTful*.json file.",
+  "npm run regenerate: Generates raw TypeScript-fetch files in src/generated/.",
+  "npm run generate-unified: Generates a unified QuickbaseClient.ts interface in src/generated-unified/.",
 ];
 
 interface TreeNode {
@@ -77,11 +109,25 @@ function buildTree(dir: string): TreeNode {
     if (file.isDirectory()) {
       childNode.children = buildTree(filePath).children;
     } else {
-      const isInImportantFolder = importantFolders.some(
+      const isInIncludeFolder = includeFolders.some((folder) => {
+        const folderPath = folder.endsWith("/") ? folder : folder + "/";
+        return (
+          relativePath.startsWith(folderPath) &&
+          relativePath.split("/").length === folderPath.split("/").length
+        );
+      });
+
+      const isInIncludeRecursiveFolder = includeRecursiveFolders.some(
         (folder) =>
           relativePath.startsWith(folder + "/") || relativePath === folder
       );
-      if (importantFiles.includes(relativePath) || isInImportantFolder) {
+
+      const shouldInclude =
+        includeFiles.includes(relativePath) ||
+        isInIncludeFolder ||
+        isInIncludeRecursiveFolder;
+
+      if (shouldInclude) {
         try {
           childNode.contents = fs.readFileSync(filePath, "utf8");
         } catch (err: unknown) {
@@ -104,17 +150,18 @@ function generateTreeSnapshot(): string {
     date: new Date().toLocaleDateString(),
     root: path.resolve(rootDir),
     goals: projectGoals,
+    pipelineOverview: pipelineOverview,
     tree: buildTree(rootDir),
   };
 
-  return yaml.dump(snapshot, { lineWidth: -1 }); // No line wrapping for readability
+  return yaml.dump(snapshot, { lineWidth: -1 });
 }
 
 try {
   const output: string = generateTreeSnapshot();
-  fs.writeFileSync("logGen.yaml", output, "utf8");
-  const lineCount: number = output.split("\n").length - 1; // Exclude trailing newline
-  console.log("logGen.yaml");
+  fs.writeFileSync("log-gen.yaml", output, "utf8");
+  const lineCount: number = output.split("\n").length - 1;
+  console.log("log-gen.yaml");
   console.log(`Lines: ${lineCount}`);
 } catch (error: unknown) {
   console.error("Failed to generate tree snapshot:", (error as Error).message);

package/src/quickbaseClient.ts

@@ -6,13 +6,17 @@ import {
   ResponseError,
 } from "./generated/runtime.ts";
 import * as apis from "./generated/apis/index.ts";
-import { simplifyName } from "./utils.ts";
 import { TokenCache } from "./tokenCache.ts";
 
 // Re-export all model types from generated/models
 export * from "./generated/models";
 
-// Rename the interface to avoid naming conflict if needed
+const simplifyName = (name: string): string =>
+  name
+    .replace(/ById$/, "")
+    .replace(/Api$/, "")
+    .replace(/^(\w)/, (_, c) => c.toLowerCase());
+
 export interface QuickbaseClient extends IQuickbaseClient {}
 
 export interface QuickbaseConfig {
@@ -51,19 +55,18 @@ const getParamNames = (fn: (...args: any[]) => any): string[] =>
     .map((p) => p.trim().split("=")[0].trim())
     .filter((p) => p && !p.match(/^\{/) && p !== "options");
 
-// New utility function to extract dbid
 const extractDbid = (
   params: Partial<TempTokenParams>,
   errorMessage: string
 ): string => {
-  const dbid = params.appId || params.tableId || params.dbid;
+  const dbid = params.dbid || params.tableId || params.appId;
   if (!dbid) {
     throw new Error(errorMessage);
   }
   return dbid;
 };
 
-export function quickbaseClient(config: QuickbaseConfig): QuickbaseClient {
+export function quickbase(config: QuickbaseConfig): QuickbaseClient {
   const {
     realm,
     userToken,
@@ -134,15 +137,13 @@ export function quickbaseClient(config: QuickbaseConfig): QuickbaseClient {
             rawMethodName
           ) as keyof QuickbaseClient;
           const method = api[rawMethodName as keyof typeof api];
-          const boundMethod = method.bind(api) as unknown;
+          const boundMethod = method.bind(api as any) as unknown;
           if (typeof boundMethod === "function" && boundMethod.length <= 2) {
             methodMap[simplifiedName] = {
               api,
               method: boundMethod as ApiMethod<typeof simplifiedName>,
               paramMap: getParamNames(method),
             };
-            if (debug)
-              console.log(`Mapped ${rawMethodName} to ${simplifiedName}`);
           }
         });
     }
@@ -200,13 +201,17 @@ export function quickbaseClient(config: QuickbaseConfig): QuickbaseClient {
   ): Promise<ReturnType<QuickbaseClient[K]>> => {
     const methodInfo = methodMap[methodName];
     if (!methodInfo) {
-      console.error(`Method ${methodName} not found in methodMap`, methodMap);
       throw new Error(`Method ${methodName} not found`);
     }
 
+    const args: [any, RequestInit | undefined] =
+      methodInfo.paramMap.length === 1 &&
+      methodInfo.paramMap[0] === "requestParameters"
+        ? [{ requestParameters: params }, undefined]
+        : [params, undefined];
+
     let token =
       initialTempToken || (userToken && !useTempTokens ? userToken : undefined);
-    let initOverrides: RequestInit = {};
 
     if (methodName === "getTempTokenDBID" && useTempTokens) {
       const dbid = extractDbid(params, "No dbid provided for getTempTokenDBID");
@@ -223,12 +228,9 @@ export function quickbaseClient(config: QuickbaseConfig): QuickbaseClient {
         params,
         `No dbid found in params for ${methodName} to fetch temp token`
       );
-      if (debug)
-        console.log(`Cache state before fetch for ${dbid}:`, tokenCache.dump());
       const cachedToken = tokenCache.get(dbid);
       if (cachedToken) {
         token = cachedToken;
-        if (debug) console.log(`Reusing cached token for dbid: ${dbid}`, token);
       } else {
         if (typeof globalThis.window === "undefined" && !fetchApi) {
           throw new Error(
@@ -242,24 +244,16 @@ export function quickbaseClient(config: QuickbaseConfig): QuickbaseClient {
           >;
         }
       }
-      initOverrides.headers = {
-        ...headers,
-        Authorization: `QB-TEMP-TOKEN ${token}`,
+      args[1] = {
+        headers: {
+          ...headers,
+          Authorization: `QB-TEMP-TOKEN ${token}`,
+        },
       };
     }
 
-    if (debug) console.log(`Invoking ${methodName} with params:`, params);
-    if (debug)
-      console.log(`Calling method with args:`, [params, initOverrides]);
-    const args: [any, RequestInit | undefined] =
-      methodInfo.paramMap.length === 1 &&
-      methodInfo.paramMap[0] === "requestParameters"
-        ? [params, initOverrides]
-        : [params, initOverrides];
-
     try {
       const response = await methodInfo.method(...args);
-      if (debug) console.log(`Response from ${methodName}:`, response);
       return response;
     } catch (error) {
       if (
@@ -267,34 +261,38 @@ export function quickbaseClient(config: QuickbaseConfig): QuickbaseClient {
         error.response.status === 401 &&
         retryCount < 1
       ) {
-        if (debug)
+        if (debug) {
           console.log(
             `Authorization error for ${methodName}, refreshing token:`,
             error.message
           );
+        }
         const dbid = extractDbid(
           params,
           `No dbid to refresh token after authorization error`
         );
         token = await fetchTempToken(dbid);
-        initOverrides.headers = {
-          ...headers,
-          Authorization: `QB-TEMP-TOKEN ${token}`,
+        args[1] = {
+          headers: {
+            ...headers,
+            Authorization: `QB-TEMP-TOKEN ${token}`,
+          },
         };
-        if (debug) console.log(`Retrying ${methodName} with new token`);
+        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();
-          console.log(`Error response body for ${methodName}:`, errorBody);
+          if (debug) {
+            console.log(`Error response body for ${methodName}:`, errorBody);
+          }
           errorMessage = errorBody.message || errorMessage;
         } catch (e) {
-          console.log(
-            `Failed to parse error response for ${methodName}:`,
-            error.message
-          );
+          // Silent fail on parse error
         }
         throw new Error(
           `API Error: ${errorMessage} (Status: ${error.response.status})`
@@ -304,17 +302,16 @@ export function quickbaseClient(config: QuickbaseConfig): QuickbaseClient {
     }
   };
 
-  return new Proxy<QuickbaseClient>({} as QuickbaseClient, {
+  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]) => {
-          if (debug) console.log(`Proxy called ${methodName} with:`, params);
-          return invokeMethod(methodName, params);
-        };
+        return (params: Parameters<QuickbaseClient[typeof methodName]>[0]) =>
+          invokeMethod(methodName, params);
       }
-      console.warn(`Method ${prop} not found in methodMap`);
       return undefined;
     },
   });
+
+  return proxy;
 }