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

package/open-api/generate-unified-interface.ts

@@ -16,11 +16,15 @@ console.log("Path modules imported");
 import { fileURLToPath } from "url";
 console.log("URL module imported");
 
-import { OpenAPIV2 } from "openapi-types"; // Use module name, not relative path
+import { OpenAPIV2 } from "openapi-types";
 console.log("openapi-types imported");
 
-// Temporary simplifyName fallback
-const simplifyName = (str: string) => str;
+import { Project } from "ts-morph";
+console.log("ts-morph imported");
+
+import { generateJsDoc } from "./utils/generateJsDoc.js";
+
+const simplifyName = (str: string): string => str;
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 console.log("__dirname set:", __dirname);
@@ -110,7 +114,57 @@ function mapRefToType(
   return "any";
 }
 
-function generateInterface() {
+interface PropertyDetail {
+  name: string;
+  type: string;
+  required: boolean;
+  jsdoc?: string;
+}
+
+function parseInterfaceProperties(
+  modelName: string,
+  modelsDir: string
+): PropertyDetail[] {
+  const project = new Project();
+  const filePath = join(modelsDir, `${modelName}.ts`);
+  if (!existsSync(filePath)) {
+    console.warn(`Model file ${filePath} not found for ${modelName}`);
+    return [];
+  }
+
+  const sourceFile = project.addSourceFileAtPath(filePath);
+  const interfaceDec = sourceFile.getInterface(modelName);
+  if (!interfaceDec) {
+    console.warn(`Interface ${modelName} not found in ${filePath}`);
+    return [];
+  }
+
+  return interfaceDec.getProperties().map((prop) => {
+    const jsDocs = prop.getJsDocs();
+    const jsdocText =
+      jsDocs.length > 0 ? jsDocs[0].getDescription().trim() : undefined;
+    return {
+      name: prop.getName(),
+      type: prop.getType().getText(prop),
+      required: !prop.hasQuestionToken(),
+      jsdoc: jsdocText,
+    };
+  });
+}
+
+interface ParamDetail {
+  name: string;
+  type: string;
+  required: boolean;
+  properties: PropertyDetail[];
+}
+
+function generateInterface(includeResponseProperties: boolean = false): void {
+  console.log(
+    "Generating interface with includeResponseProperties:",
+    includeResponseProperties
+  );
+
   console.log("Checking spec file:", SPEC_FILE);
   if (!existsSync(SPEC_FILE)) {
     console.error(
@@ -121,7 +175,7 @@ function generateInterface() {
 
   console.log("Reading spec file...");
   const specContent = readFileSync(SPEC_FILE, "utf8");
-  const spec = JSON.parse(specContent) as OpenAPIV2.Document;
+  const spec: OpenAPIV2.Document = JSON.parse(specContent);
   console.log("Spec parsed, keys:", Object.keys(spec));
 
   const { paths } = spec;
@@ -158,7 +212,9 @@ function generateInterface() {
 
       const opId = simplifyName(op.operationId);
       const summary = op.summary || "No description.";
-      const params = (op.parameters || [])
+      const docLink = `https://developer.quickbase.com/operation/${op.operationId}`;
+
+      const paramDetails: ParamDetail[] = (op.parameters || [])
         .filter((p: OpenAPIV2.ParameterObject | OpenAPIV2.ReferenceObject) => {
           const param = p as OpenAPIV2.ParameterObject;
           return !["QB-Realm-Hostname", "Authorization", "User-Agent"].includes(
@@ -167,8 +223,9 @@ function generateInterface() {
         })
         .map((param: OpenAPIV2.ParameterObject | OpenAPIV2.ReferenceObject) => {
           const p = param as OpenAPIV2.ParameterObject;
-          if (!p.name) return "";
+          if (!p.name) return null;
           let type = "any";
+          let properties: PropertyDetail[] = [];
           if ("schema" in p && p.schema) {
             type = mapRefToType(
               p.schema,
@@ -178,13 +235,28 @@ function generateInterface() {
               availableModels,
               missingTypes
             );
+            if ("$ref" in p.schema && p.schema.$ref) {
+              const refParts = p.schema.$ref.split("/");
+              const model = refParts[refParts.length - 1];
+              const pascalModel =
+                model.charAt(0).toUpperCase() + model.slice(1);
+              properties = parseInterfaceProperties(pascalModel, MODELS_DIR);
+            }
           } else if ("type" in p && p.type) {
             type = mapOpenApiTypeToTs(p.type);
           }
           const paramName = p.in === "body" ? "body" : p.name;
-          return `${paramName}${p.required ? "" : "?"}: ${type}`;
+          return {
+            name: paramName,
+            type,
+            required: p.required || false,
+            properties,
+          };
         })
-        .filter((param) => param !== "")
+        .filter((p): p is ParamDetail => p !== null);
+
+      const params = paramDetails
+        .map((p) => `${p.name}${p.required ? "" : "?"}: ${p.type}`)
         .join("; ");
 
       const returnTypes = ["200", "207"]
@@ -207,13 +279,21 @@ function generateInterface() {
           ? returnTypes.join(" | ")
           : returnTypes[0] || "void";
 
-      const jsDoc = [
-        `  /**`,
-        `   * ${summary}`,
-        `   * @param params - Parameters for ${opId}`,
-        `   * @returns Promise resolving to ${opId} response`,
-        `   */`,
-      ].join("\n");
+      const returnTypeDetails: PropertyDetail[] =
+        includeResponseProperties &&
+        returnTypes.length === 1 &&
+        returnTypes[0] !== "void"
+          ? parseInterfaceProperties(returnTypes[0], MODELS_DIR)
+          : [];
+
+      const jsDoc = generateJsDoc({
+        summary,
+        opId,
+        paramDetails,
+        returnType,
+        returnTypeDetails,
+        docLink,
+      });
 
       methods.push(
         `${jsDoc}\n  ${opId}: (params: { ${params} }) => Promise<${returnType}>;`
@@ -247,7 +327,7 @@ function generateInterface() {
 
 console.log("Entering try block");
 try {
-  generateInterface();
+  generateInterface(true); // Toggle response properties here
 } catch (error) {
   console.error("Error in generateInterface:", error);
   process.exit(1);

package/open-api/utils/generateJsDoc.ts

@@ -0,0 +1,96 @@
+interface ParamDetail {
+  name: string;
+  type: string;
+  required: boolean;
+  properties: {
+    name: string;
+    type: string;
+    required: boolean;
+    jsdoc?: string;
+  }[];
+}
+
+interface JsDocOptions {
+  summary: string;
+  opId: string;
+  paramDetails: ParamDetail[];
+  returnType: string;
+  returnTypeDetails: {
+    name: string;
+    type: string;
+    required: boolean;
+    jsdoc?: string;
+  }[];
+  docLink: string;
+}
+
+export function generateJsDoc({
+  summary,
+  opId,
+  paramDetails,
+  returnType,
+  returnTypeDetails,
+  docLink,
+}: JsDocOptions): string {
+  const jsDocLines: string[] = [
+    `  /**`,
+    `   * ${summary}`,
+    `   *`,
+    `   * @param {Object} params _Object containing the parameters for_ ${opId}`,
+  ];
+
+  // Parameters section
+  if (paramDetails.length > 0) {
+    paramDetails.forEach((p) => {
+      jsDocLines.push(
+        `   *   @param {${p.type}} params.${p.name} _${
+          p.required ? "Required" : "Optional"
+        } parameter with properties_`
+      );
+      if (p.properties.length > 0) {
+        p.properties.forEach((prop) => {
+          const propDesc = prop.jsdoc
+            ? prop.jsdoc.replace(/@type\s*{[^}]+}\s*@memberof\s*\w+/, "").trim()
+            : `Type: ${prop.type}`;
+          jsDocLines.push(
+            `   *     - **${prop.name}** (\`${prop.type}\`${
+              prop.required ? ", required" : ", optional"
+            }) _${propDesc}_`
+          );
+        });
+      }
+    });
+  } else {
+    jsDocLines.push(`   *   No parameters`);
+  }
+
+  // Returns section
+  jsDocLines.push(`   *`);
+  if (returnTypeDetails.length > 0) {
+    jsDocLines.push(
+      `   * @returns {Promise<${returnType}>} _Promise resolving to the ${opId} response with properties_`
+    );
+    returnTypeDetails.forEach((prop) => {
+      const propDesc = prop.jsdoc
+        ? prop.jsdoc.replace(/@type\s*{[^}]+}\s*@memberof\s*\w+/, "").trim()
+        : `Type: ${prop.type}`;
+      jsDocLines.push(
+        `   *   - **${prop.name}** (\`${prop.type}\`${
+          prop.required ? ", required" : ", optional"
+        }) _${propDesc}_`
+      );
+    });
+  } else {
+    jsDocLines.push(
+      `   * @returns {Promise<${returnType}>} _Promise resolving to the ${opId} response_`
+    );
+  }
+
+  jsDocLines.push(
+    `   *`,
+    `   * @see {@link ${docLink}} Official Quickbase API documentation`
+  );
+  jsDocLines.push(`   */`);
+
+  return jsDocLines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quickbase-js",
-  "version": "0.1.0-beta.8",
+  "version": "0.1.0-beta.9",
   "description": "QuickBase JavaScript client for frameworks and vanilla JS",
   "type": "module",
   "main": "dist/esm/quickbase.js",
@@ -52,6 +52,7 @@
     "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:pw:qb:auth": "playwright test tests/playwright/qb/auth"
@@ -67,6 +68,7 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.13.10",
     "dotenv": "^16.4.7",
+    "express": "^4.21.2",
     "fast-json-patch": "^3.1.1",
     "glob": "^10.4.5",
     "js-yaml": "^4.1.0",

package/src/ThrottleBucket.ts

@@ -1,18 +1,18 @@
-// src/TokenBucket.ts
+// src/ThrottleBucket.ts
 export class ThrottleBucket {
   private tokens: number;
   private maxTokens: number;
   private refillRate: number; // Tokens per second
   private lastRefill: number;
+  private pending: Promise<void> = Promise.resolve(); // Queue for sequential execution
 
   constructor(rate: number, burst: number) {
-    this.tokens = burst; // Start with full burst capacity
+    this.tokens = burst;
     this.maxTokens = burst;
     this.refillRate = rate;
     this.lastRefill = Date.now();
   }
 
-  // Refill tokens based on elapsed time
   private refill(): void {
     const now = Date.now();
     const elapsed = (now - this.lastRefill) / 1000; // Seconds elapsed
@@ -21,16 +21,21 @@ export class ThrottleBucket {
     this.lastRefill = now;
   }
 
-  // Acquire a token, waiting if necessary
   async acquire(): Promise<void> {
-    this.refill();
-    if (this.tokens >= 1) {
+    // Chain the new acquisition onto the pending queue
+    const previous = this.pending;
+    this.pending = (async () => {
+      await previous; // Wait for prior calls to complete
+      this.refill();
+      if (this.tokens >= 1) {
+        this.tokens -= 1;
+        return;
+      }
+      const waitTime = ((1 - this.tokens) / this.refillRate) * 1000; // ms until next token
+      await new Promise((resolve) => setTimeout(resolve, waitTime));
+      this.refill();
       this.tokens -= 1;
-      return;
-    }
-    const waitTime = ((1 - this.tokens) / this.refillRate) * 1000; // ms until next token
-    await new Promise((resolve) => setTimeout(resolve, waitTime));
-    this.refill();
-    this.tokens -= 1;
+    })();
+    await this.pending;
   }
 }

package/src/authorizationStrategy.ts

@@ -0,0 +1,246 @@
+// src/authorizationStrategy.ts
+
+import { TokenCache } from "./tokenCache";
+
+export interface AuthorizationStrategy {
+  getToken(dbid: string): Promise<string | undefined>;
+  applyHeaders(headers: Record<string, string>, token: string): void;
+  handleError(
+    status: number,
+    params: any,
+    fetchTempToken: (dbid: string) => Promise<string>,
+    attempt: number,
+    maxAttempts: number,
+    debug?: boolean,
+    methodName?: string
+  ): Promise<string | null>;
+}
+
+export class TempTokenStrategy implements AuthorizationStrategy {
+  constructor(
+    private tokenCache: TokenCache,
+    private initialTempToken?: string
+  ) {}
+
+  async getToken(dbid: string): Promise<string | undefined> {
+    return this.tokenCache.get(dbid) || this.initialTempToken;
+  }
+
+  applyHeaders(headers: Record<string, string>, token: string): void {
+    headers["Authorization"] = `QB-TEMP-TOKEN ${token}`;
+  }
+
+  async handleError(
+    status: number,
+    params: any,
+    fetchTempToken: (dbid: string) => Promise<string>,
+    attempt: number,
+    maxAttempts: number,
+    debug?: boolean,
+    methodName?: string
+  ): Promise<string | null> {
+    if (status !== 401 || attempt >= maxAttempts - 1) return null;
+    if (debug)
+      console.log(
+        `Authorization error for ${
+          methodName || "method"
+        } (temp token), refreshing token:`
+      );
+    const dbid = extractDbid(params);
+    if (!dbid) {
+      if (debug)
+        console.log(
+          `No dbid available for ${
+            methodName || "method"
+          }, skipping token refresh`
+        );
+      return null;
+    }
+    if (debug) console.log(`Refreshing temp token for dbid: ${dbid}`);
+    const newToken = await fetchTempToken(dbid);
+    this.tokenCache.set(dbid, newToken);
+    return newToken;
+  }
+}
+
+export class UserTokenStrategy implements AuthorizationStrategy {
+  constructor(private userToken: string) {}
+
+  async getToken(_dbid: string): Promise<string> {
+    return this.userToken;
+  }
+
+  applyHeaders(headers: Record<string, string>, token: string): void {
+    headers["Authorization"] = `QB-USER-TOKEN ${token}`;
+  }
+
+  async handleError(
+    status: number,
+    _params: any,
+    _fetchTempToken: (dbid: string) => Promise<string>,
+    attempt: number,
+    maxAttempts: number,
+    debug?: boolean,
+    methodName?: string
+  ): Promise<string | null> {
+    if (status !== 401 || attempt >= maxAttempts - 1) return null;
+    if (debug)
+      console.log(
+        `Retrying ${
+          methodName || "method"
+        } with existing user token: ${this.userToken.substring(0, 10)}...`
+      );
+    return this.userToken;
+  }
+}
+
+export class SsoTokenStrategy implements AuthorizationStrategy {
+  private currentToken: string | undefined;
+
+  constructor(
+    private samlToken: string,
+    private realm: string,
+    private fetchApi: typeof fetch,
+    private debug: boolean = false
+  ) {}
+
+  async getToken(_dbid: string): Promise<string | undefined> {
+    if (!this.currentToken) {
+      this.currentToken = await this.fetchSsoToken({
+        grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+        requested_token_type:
+          "urn:quickbase:params:oauth:token-type:temp_token",
+        subject_token: this.samlToken,
+        subject_token_type: "urn:ietf:params:oauth:token-type:saml2",
+      });
+    }
+    return this.currentToken;
+  }
+
+  applyHeaders(headers: Record<string, string>, token: string): void {
+    headers["Authorization"] = `QB-TEMP-TOKEN ${token}`;
+  }
+
+  async handleError(
+    status: number,
+    _params: any,
+    _fetchTempToken: (dbid: string) => Promise<string>,
+    attempt: number,
+    maxAttempts: number,
+    debug?: boolean,
+    methodName?: string
+  ): Promise<string | null> {
+    if (status !== 401 || attempt >= maxAttempts - 1) return null;
+
+    if (debug || this.debug) {
+      console.log(
+        `Authorization error for ${
+          methodName || "method"
+        } (SSO), refreshing token`
+      );
+    }
+
+    const newToken = await this.refreshSsoToken(debug || this.debug);
+    if (newToken) {
+      this.currentToken = newToken;
+      return newToken;
+    }
+    return null;
+  }
+
+  private async refreshSsoToken(debug: boolean = false): Promise<string> {
+    const payload = {
+      grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+      requested_token_type: "urn:quickbase:params:oauth:token-type:temp_token",
+      subject_token: this.samlToken,
+      subject_token_type: "urn:ietf:params:oauth:token-type:saml2",
+    };
+
+    const response = await this.fetchApi(
+      `https://api.quickbase.com/v1/auth/oauth/token`,
+      {
+        method: "POST",
+        headers: {
+          "QB-Realm-Hostname": `${this.realm}.quickbase.com`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(payload),
+        credentials: "omit",
+      }
+    );
+
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({}));
+      if (debug) {
+        console.log(`[SSO Refresh] Failed: ${response.status}`, errorBody);
+      }
+      throw new Error(
+        `SSO token refresh failed: ${errorBody.message || "Unknown error"}`
+      );
+    }
+
+    const result = await response.json();
+    const newToken = result.access_token;
+    if (!newToken) {
+      throw new Error("No access token returned from SSO token exchange");
+    }
+
+    if (debug) {
+      console.log(`[SSO Refresh] New token: ${newToken.substring(0, 10)}...`);
+    }
+    return newToken;
+  }
+
+  private async fetchSsoToken(params: {
+    grant_type: string;
+    requested_token_type: string;
+    subject_token: string;
+    subject_token_type: string;
+  }): Promise<string> {
+    const response = await this.fetchApi(
+      `https://api.quickbase.com/v1/auth/oauth/token`,
+      {
+        method: "POST",
+        headers: {
+          "QB-Realm-Hostname": `${this.realm}.quickbase.com`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(params),
+        credentials: "omit",
+      }
+    );
+
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({}));
+      if (this.debug) {
+        console.log(`[fetchSsoToken] Failed: ${response.status}`, errorBody);
+      }
+      throw new Error(
+        `SSO token fetch failed: ${errorBody.message || "Unknown error"}`
+      );
+    }
+
+    const result = await response.json();
+    const newToken = result.access_token;
+    if (!newToken) {
+      throw new Error("No access token returned from SSO token exchange");
+    }
+
+    if (this.debug) {
+      console.log(
+        `[fetchSsoToken] Fetched token: ${newToken.substring(0, 10)}...`
+      );
+    }
+    return newToken;
+  }
+}
+
+export function extractDbid(params: any): string | undefined {
+  return (
+    params.dbid ||
+    params.tableId ||
+    params.appId ||
+    params.body?.from ||
+    params.body?.to
+  );
+}