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

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [0.1.0-beta.11](https://github.com/DrewBradfordXYZ/quickbase-js/compare/v0.1.0-beta.10...v0.1.0-beta.11) (2025-03-23)
+
+
+### Features
+
+* only fetch auth dbid once for concurrent requests. temp tokens and SSO ([12f7f31](https://github.com/DrewBradfordXYZ/quickbase-js/commit/12f7f3117b2fd6e5db35d73e945dff0a79ef0481))
+* SSO concurrency tests passes ([caf5fca](https://github.com/DrewBradfordXYZ/quickbase-js/commit/caf5fca4e86b0dda4a75c2856f9324634369f15a))
+* temp token concurrency prevents redundant token fetches. getAppConcurrency.test.ts unit test passes ([2913e7b](https://github.com/DrewBradfordXYZ/quickbase-js/commit/2913e7b38d38ca0ceaa0af21b2e872f7bafb9d99))
+
 ## [0.1.0-beta.10](https://github.com/DrewBradfordXYZ/quickbase-js/compare/v0.1.0-beta.9...v0.1.0-beta.10) (2025-03-22)
 
 

package/README.md

@@ -1,22 +1,60 @@
 # quickbase-js
 
-A Typescript library using the QuickBase OpenAPI spec and the typescipt-fetch generator. This library is designed for both browser and Node.js environments. Code pages have first class support.
+A Typescript API client for the [Quickbase JSON RESTful API](https://developer.quickbase.com/).
 
-Authentication methods: `Temporary Tokens`, `User Tokens`, `SSO`.
+Support for various authentication strategies (`user token`, `temporary tokens`, `SSO token`), `rate limiting`, `429` and `401` error handling retries and automatic `date` conversion. It uses a Proxy to dynamically invoke API methods derived from the OpenAPI specification.
+
+Browser and Node.js support. ESM and UMD builds are available.
+
+Authentication methods are handled in an opinionated manner. See configuration options for details and available settings.
 
 ## API Documentation
 
-https://quickbase-js.netlify.app/
+<a href="https://quickbase-js.netlify.app/" target="_blank"> Documentation</a> for quickbase-js.
 
 ## Installation
 
+#### Node.js install
+
 ```bash
 npm install --save quickbase-js
 ```
 
-## Examples
+#### CDN install.
+
+Find and select the latest version. UMD is recommended for code pages.
+
+<a href="https://www.jsdelivr.com/package/npm/quickbase-js?tab=files" target="_blank">CDN Files</a> for quickbase-js
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Quickbase</title>
+    <!-- Replace xx.xx.xx with the latest version from CDN Files-->
+    <script src="https://cdn.jsdelivr.net/npm/quickbase-js@xx.xx.xx/dist/umd/quickbase.umd.min.js"></script>
+  </head>
+  <body>
+    <script>
+      const realm = ""; // Replace with your realm
+      const appId = ""; // Replace with your app ID
+
+      const qb = QuickbaseJS.quickbase({
+        realm,
+        useTempTokens: true,
+      });
+
+      qb.getApp({ appId })
+        .then((app) => console.log(app.name))
+        .catch((err) => console.log(err.message));
+    </script>
+  </body>
+</html>
+```
+
+## Authentication Examples
 
-### Auth: User Token
+### User Token
 
 ```javascript
 import { quickbase } from "quickbase-js"; // Adjust the import path as needed
@@ -45,7 +83,7 @@ const getAppDetails = async () => {
 getAppDetails();
 ```
 
-### Auth: Temporary Tokens (Code Pages)
+### Temporary Tokens (Code Pages)
 
 ```javascript
 import { quickbase } from "quickbase-js"; // Adjust the import path as needed
@@ -73,7 +111,7 @@ const getAppDetails = async () => {
 getAppDetails();
 ```
 
-### Auth: SSO
+### SSO Token
 
 ```javascript
 import { quickbase } from "quickbase-js"; // Adjust the import path as needed
@@ -117,14 +155,14 @@ _User options:_
 
 _Advanced user options:_
 
-- **`tempTokenLifespan`** (`number`, optional): The lifespan (in milliseconds) of temporary tokens in the cache. Defaults to 4 minutes 50 seconds (290000 ms).
-
 - **`throttle`** (`{ rate: number; burst: number }`, optional): Configures rate limiting, where `rate` is requests per second and `burst` is the maximum burst of requests. Defaults to `{ rate: 10, burst: 10 }`.
 
 - **`maxRetries`** (`number`, optional): The maximum number of retries for failed requests. Defaults to `3`.
 
 - **`retryDelay`** (`number`, optional): The base delay (in milliseconds) between retries, which increases exponentially. Defaults to `1000`.
 
+- **`tempTokenLifespan`** (`number`, optional): The lifespan (in milliseconds) of temporary tokens in the cache. Defaults to 4 minutes 50 seconds (290000 ms).
+
 - **`convertDates`** (`boolean`, optional): Converts ISO date strings to `Date` objects in responses. Defaults to `true`.
 
 _Overrides and development options:_
@@ -149,6 +187,8 @@ _Overrides and development options:_
 
 - **`tokenCache`**: Temporary tokens are cached with their dbid with a `tempTokenLifespan`. This is automatically setup for you when `useTempTokens` is enabled.
 
+---
+
 ### Development workflow
 
 ```bash

package/dist/esm/quickbase.d.ts

@@ -8051,6 +8051,7 @@ declare class TokenCache {
     constructor(tempTokenLifespan?: number);
     get(dbid: string): string | undefined;
     set(dbid: string, token: string, lifespan?: number): void;
+    delete(dbid: string): void;
     clear(): void;
 }
 

package/dist/esm/quickbase.js

@@ -7348,6 +7348,9 @@ class TokenCache {
             expiresAt: now + (lifespan || this.tempTokenLifespan),
         });
     }
+    delete(dbid) {
+        this.cache.delete(dbid);
+    }
     clear() {
         this.cache.clear();
     }
@@ -7402,14 +7405,13 @@ function extractHttpMethod(method) {
     return match ? match[1].toUpperCase() : "GET"; // Fallback to GET if no match
 }
 
-// src/authorizationStrategy.ts
-// src/authorizationStrategy.ts (partial update)
 class TempTokenStrategy {
     tokenCache;
     initialTempToken;
     fetchApi;
     realm;
     baseUrl;
+    pendingFetches = new Map();
     constructor(tokenCache, initialTempToken, fetchApi, realm, baseUrl = "https://api.quickbase.com/v1") {
         this.tokenCache = tokenCache;
         this.initialTempToken = initialTempToken;
@@ -7444,7 +7446,13 @@ class TempTokenStrategy {
     async getToken(dbid) {
         let token = this.tokenCache.get(dbid) || this.initialTempToken;
         if (!token && dbid) {
-            token = await this.fetchTempToken(dbid);
+            if (this.pendingFetches.has(dbid)) {
+                console.log(`[getToken] Waiting for existing fetch for dbid: ${dbid}`);
+                return this.pendingFetches.get(dbid);
+            }
+            const fetchPromise = this.fetchTempToken(dbid).finally(() => this.pendingFetches.delete(dbid));
+            this.pendingFetches.set(dbid, fetchPromise);
+            token = await fetchPromise;
         }
         return token;
     }
@@ -7464,15 +7472,29 @@ class TempTokenStrategy {
         }
         if (debug)
             console.log(`Refreshing temp token for dbid: ${dbid}`);
-        const newToken = await this.fetchTempToken(dbid);
-        this.tokenCache.set(dbid, newToken);
-        return newToken;
+        // Invalidate the cache for this dbid to force a fresh fetch
+        this.tokenCache.delete(dbid);
+        try {
+            const newToken = await this.getToken(dbid);
+            if (newToken) {
+                this.tokenCache.set(dbid, newToken);
+                return newToken;
+            }
+            return null;
+        }
+        catch (error) {
+            if (debug)
+                console.log(`[${methodName || "method"}] Failed to refresh token:`, error);
+            throw error;
+        }
     }
 }
 class UserTokenStrategy {
     userToken;
-    constructor(userToken) {
+    baseUrl;
+    constructor(userToken, baseUrl = "https://api.quickbase.com/v1") {
         this.userToken = userToken;
+        this.baseUrl = baseUrl;
     }
     async getToken(_dbid) {
         return this.userToken;
@@ -7493,21 +7515,31 @@ class SsoTokenStrategy {
     realm;
     fetchApi;
     debug;
+    baseUrl;
     currentToken;
-    constructor(samlToken, realm, fetchApi, debug = false) {
+    pendingFetches = new Map();
+    constructor(samlToken, realm, fetchApi, debug = false, baseUrl = "https://api.quickbase.com/v1") {
         this.samlToken = samlToken;
         this.realm = realm;
         this.fetchApi = fetchApi;
         this.debug = debug;
+        this.baseUrl = baseUrl;
     }
     async getToken(_dbid) {
         if (!this.currentToken) {
-            this.currentToken = await this.fetchSsoToken({
+            if (this.pendingFetches.has("sso")) {
+                if (this.debug)
+                    console.log("[getToken] Waiting for existing SSO fetch");
+                return this.pendingFetches.get("sso");
+            }
+            const fetchPromise = 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",
-            });
+            }).finally(() => this.pendingFetches.delete("sso"));
+            this.pendingFetches.set("sso", fetchPromise);
+            this.currentToken = await fetchPromise;
         }
         return this.currentToken;
     }
@@ -7534,7 +7566,7 @@ class SsoTokenStrategy {
             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`, {
+        const response = await this.fetchApi(`${this.baseUrl}/auth/oauth/token`, {
             method: "POST",
             headers: {
                 "QB-Realm-Hostname": `${this.realm}.quickbase.com`,
@@ -7561,7 +7593,7 @@ class SsoTokenStrategy {
         return newToken;
     }
     async fetchSsoToken(params) {
-        const response = await this.fetchApi(`https://api.quickbase.com/v1/auth/oauth/token`, {
+        const response = await this.fetchApi(`${this.baseUrl}/auth/oauth/token`, {
             method: "POST",
             headers: {
                 "QB-Realm-Hostname": `${this.realm}.quickbase.com`,
@@ -7609,8 +7641,7 @@ class RateLimitError extends Error {
 }
 
 // src/invokeMethod.ts
-async function invokeMethod(methodName, params, methodMap, baseHeaders, authStrategy, rateLimiter, transformDates, debug, convertDates) {
-    console.log("[invokeMethod] Starting for method:", methodName);
+async function invokeMethod(methodName, params, methodMap, baseHeaders, authStrategy, rateLimiter, transformDates, debug, convertDates, attempt = 0, maxAttempts = rateLimiter.maxRetries + 1) {
     const methodInfo = methodMap[methodName];
     if (!methodInfo)
         throw new Error(`Method ${methodName} not found`);
@@ -7628,33 +7659,21 @@ async function invokeMethod(methodName, params, methodMap, baseHeaders, authStra
         method: methodInfo.httpMethod,
     };
     let dbid = extractDbid(params);
-    console.log("[invokeMethod] Extracted dbid:", dbid);
     let token = dbid
         ? await authStrategy.getToken(dbid)
         : await authStrategy.getToken("");
-    console.log("[invokeMethod] Initial token:", token);
     if (token) {
         authStrategy.applyHeaders(baseHeaders, token);
         requestOptions.headers = { ...baseHeaders };
-        console.log("[invokeMethod] Token found, headers set:", requestOptions.headers);
         if (methodName === "getTempTokenDBID") {
-            console.log("[invokeMethod] Using cached token:", token);
             return { temporaryAuthorization: token };
         }
     }
-    if (debug) {
-        console.log(`[${methodName}] requestParameters:`, requestParameters);
-        console.log(`[${methodName}] requestOptions:`, requestOptions);
-    }
     async function processResponse(rawResponse) {
-        if (debug)
-            console.log(`[${methodName}] rawResponse:`, rawResponse);
         if (rawResponse instanceof Response) {
             const contentType = rawResponse.headers
                 .get("Content-Type")
                 ?.toLowerCase();
-            if (debug)
-                console.log(`[${methodName}] contentType:`, contentType);
             if (contentType?.includes("application/json")) {
                 const jsonResponse = await rawResponse.json();
                 return transformDates(jsonResponse, convertDates);
@@ -7663,8 +7682,6 @@ async function invokeMethod(methodName, params, methodMap, baseHeaders, authStra
         }
         if (rawResponse && typeof rawResponse.value === "function") {
             const response = await rawResponse.value();
-            if (debug)
-                console.log(`[${methodName}] Resolved JSONApiResponse:`, response);
             return transformDates(response, convertDates);
         }
         return transformDates(rawResponse, convertDates);
@@ -7692,28 +7709,17 @@ async function invokeMethod(methodName, params, methodMap, baseHeaders, authStra
             }
         }
         catch (e) {
-            if (debug)
-                console.log(`[${methodName}] Error parsing response body:`, e);
             message = "Failed to parse error response";
         }
-        if (debug)
-            console.log("[invokeMethod] Parsed error - status:", status, "message:", message);
         return { message, status };
     }
-    let attempt = 0;
-    const maxAttempts = rateLimiter.maxRetries + 1;
     while (attempt < maxAttempts) {
-        console.log("[invokeMethod] Attempt:", attempt + 1, "of", maxAttempts);
         try {
             await rateLimiter.throttle();
-            console.log("[invokeMethod] About to call API for method:", methodName);
             const response = await methodInfo.method(requestParameters, requestOptions);
-            console.log("[invokeMethod] API call completed for method:", methodName);
             return await processResponse(response);
         }
         catch (error) {
-            if (debug)
-                console.log("[invokeMethod] Caught error:", error);
             let status;
             let message;
             let response;
@@ -7726,31 +7732,13 @@ async function invokeMethod(methodName, params, methodMap, baseHeaders, authStra
                 ({ message, status } = await parseErrorResponse(response));
             }
             else {
-                if (debug)
-                    console.log(`[${methodName}] Unexpected error:`, error);
-                // Attempt to handle as a fetch error with a response
-                if (error instanceof Error && "response" in error) {
-                    response = error.response;
-                    if (response instanceof Response) {
-                        ({ message, status } = await parseErrorResponse(response));
-                    }
-                    else {
-                        throw error; // Rethrow if no response
-                    }
-                }
-                else {
-                    throw error; // Rethrow truly unexpected errors
-                }
+                throw error; // Rethrow truly unexpected errors
             }
-            if (debug)
-                console.log("[invokeMethod] Handling error with status:", status);
             if (status === 429) {
                 if (!(error instanceof ResponseError)) {
                     throw new Error("Expected ResponseError for 429 handling");
                 }
                 const delay = await rateLimiter.handle429(error, attempt + 1);
-                if (debug)
-                    console.log(`[${methodName}] 429 delay: ${delay}ms`);
                 if (attempt + 1 === maxAttempts) {
                     throw new RateLimitError(`API Error: ${message} (Status: ${status})`, status, response?.headers.get("Retry-After")
                         ? parseInt(response.headers.get("Retry-After"), 10)
@@ -7760,16 +7748,25 @@ async function invokeMethod(methodName, params, methodMap, baseHeaders, authStra
                 attempt++;
                 continue;
             }
-            const newToken = await authStrategy.handleError(status, params, attempt, maxAttempts, debug, methodName);
-            if (newToken) {
+            // Handle authentication errors
+            let newToken;
+            try {
+                newToken = await authStrategy.handleError(status, params, attempt, maxAttempts, debug, methodName);
+            }
+            catch (authError) {
+                throw authError; // Propagate the fetchTempToken error and exit immediately
+            }
+            // Only proceed with retry if we have a valid new token
+            if (newToken !== null) {
                 token = newToken;
                 authStrategy.applyHeaders(baseHeaders, token);
                 requestOptions.headers = { ...baseHeaders };
-                attempt++;
                 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})`);
         }
     }
@@ -7838,7 +7835,6 @@ class RateLimiter {
     }
 }
 
-// src/quickbaseClient.ts
 function quickbase(config) {
     const { realm, userToken, tempToken, useTempTokens, useSso, samlToken, fetchApi, debug, convertDates = true, tempTokenLifespan = 290000, throttle = { rate: 10, burst: 10 }, maxRetries = 3, retryDelay = 1000, tokenCache: providedTokenCache, baseUrl = "https://api.quickbase.com/v1", } = config;
     const tokenCache = providedTokenCache || new TokenCache(tempTokenLifespan);
@@ -7854,10 +7850,10 @@ function quickbase(config) {
         throw new Error("No fetch implementation available");
     }
     const authStrategy = useSso
-        ? new SsoTokenStrategy(samlToken || "", realm, effectiveFetch, debug)
+        ? new SsoTokenStrategy(samlToken || "", realm, effectiveFetch, debug, baseUrl)
         : useTempTokens
             ? new TempTokenStrategy(tokenCache, tempToken, effectiveFetch, realm, baseUrl)
-            : new UserTokenStrategy(userToken || "");
+            : new UserTokenStrategy(userToken || "", baseUrl);
     const baseHeaders = {
         "QB-Realm-Hostname": `${realm}.quickbase.com`,
         "Content-Type": "application/json",