quickbase-js 1.1.0-beta.6 → 1.2.0

package/README.md

@@ -1,212 +1,330 @@
 # quickbase-js
 
-# Installation
+A Typescript API client for the [Quickbase JSON RESTful API](https://developer.quickbase.com/).
+
+Support for various authentication types (`user token`, `temporary tokens`, `SSO token`), `concurrent rate limiting strategies`, `auto pagination`, `js date conversion`, `429` (rate limit) and `401` (auth) error handling retries. 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 and throttle methods are opinionated. See configuration options for details and available settings.
+
+## API Documentation
+
+<a href="https://quickbase-js.netlify.app/" target="_blank"> Documentation</a> for quickbase-js.
+
+## Installation
+
+#### Node.js install
 
 ```bash
 npm install --save quickbase-js
 ```
 
-## Example
+#### 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 Test</title>
+    <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>
-    <div>
-      <h1>Quickbase Test</h1>
-      <p id="result">Loading...</p>
-    </div>
-    <script type="module">
-      import { quickbase } from "quickbase-js";
-      // Initalize the QuickBase client
-      const qb = quickbase({
-        realm: "your-realm", // Replace with actual QuickBase realm
-        // ## ------------------------------
-        // ## Authentication Options
-        // ## ----------------------------
-        // ## OPTION 1: User Token Authentication
-        // ## - Use this if you have a QuickBase user token.
-        // ## - Works in Node.js or browsers, ideal for standalone apps or testing outside QuickBase
-        // ## - Uncomment the line below and replace with your token; comment out 'useTempTokens'
-        // userToken: "your-user-token",
-
-        // ## ----------------------------
-        // ## OPTION 2: Temporary Token Authentication
-        // ## - Use this for QuickBase code pages, leveraging the browser’s authenticated session
-        // ## - No user token needed; requires running in a QuickBase browser context
-        // ## - Uncomment the line below and comment out 'userToken' if using this option
-        // useTempTokens: true,
+    <script>
+      const realm = ""; // Replace with your realm
+      const appId = ""; // Replace with your app ID
+
+      const qb = QuickbaseJS.quickbase({
+        realm,
+        useTempTokens: true,
       });
 
-      // Fetch the app
-      qb.getApp({ appId: "your-app-id" }) // Replace with actual app ID
-        .then((app) => {
-          document.getElementById(
-            "result"
-          ).textContent = `App Name: ${app.name}`;
-        })
-        .catch((err) => {
-          console.error("Error fetching app:", err);
-          document.getElementById("result").textContent =
-            err.message || "Failed to load app";
-        });
+      qb.getApp({ appId })
+        .then((app) => console.log(app.name))
+        .catch((err) => console.log(err.message));
     </script>
   </body>
 </html>
 ```
 
-# Development workflow
-
-```bash
-npm run regenerate:all
-npm run build
-npm run test:all
-```
+## Authentication Examples
 
-## Usage
+### User Token
 
-### Node.js (ESM - Recommended)
+```javascript
+import { quickbase } from "quickbase-js"; // Adjust the import path as needed
 
-For modern Node.js applications, use ES modules:
+// QuickBase config variables
+const QB_REALM = ""; // Your QuickBase realm (e.g., 'mycompany')
+const QB_USER_TOKEN = ""; // Your QuickBase user token (e.g., 'b12345_abcde...')
+const QB_APP_ID = ""; // Your app ID (e.g., 'bxyz789')
 
-```javascript
-// ESM (Node.js) - Recommended
-import { quickbase } from "quickbase-js";
-const qb = quickbase({ realm: "example", userToken: "your-token" });
-
-// Example: Fetching an app
-const app = await qb.getApp({ appId: "your-app-id" });
-console.log(app);
-
-// Example: Creating a record with temporary token
-const qbTemp = quickbase({ realm: "example", useTempTokens: true });
-const record = await qbTemp.upsert({
-  body: {
-    to: "your-table-id",
-    data: [
-      {
-        /* record data */
-      },
-    ],
-  },
+const qb = quickbase({
+  realm: QB_REALM,
+  userToken: QB_USER_TOKEN,
 });
-console.log(record);
+
+const getAppDetails = async () => {
+  try {
+    const response = await qb.getApp({
+      appId: QB_APP_ID,
+    });
+    console.log("App Details:", response);
+  } catch (error) {
+    console.error("Error fetching app:", error.message);
+  }
+};
+
+getAppDetails();
 ```
 
+### Temporary Tokens (Code Pages)
+
 ```javascript
-// Example: TypeScript ESM (Recommended)
-import { quickbase } from "quickbase-js";
-const qbTyped: QuickbaseClient = quickbase({
-  realm: "example",
-  userToken: "your-token",
+import { quickbase } from "quickbase-js"; // Adjust the import path as needed
+
+// QuickBase config variables
+const QB_REALM = ""; // Your QuickBase realm (e.g., 'mycompany')
+const QB_APP_ID = ""; // Your app ID (e.g., 'bxyz789')
+
+const qb = quickbase({
+  realm: QB_REALM,
+  useTempTokens: true,
 });
-const typedApp = await qbTyped.getApp({ appId: "your-app-id" });
-console.log(typedApp);
+
+const getAppDetails = async () => {
+  try {
+    const response = await qb.getApp({
+      appId: QB_APP_ID,
+    });
+    console.log("App Details:", response);
+  } catch (error) {
+    console.error("Error fetching app:", error.message);
+  }
+};
+
+getAppDetails();
 ```
 
+### SSO Token
+
 ```javascript
-// Example: UMD via CDN (QuickBase Code Pages)
-// Note: This is HTML, not JavaScript, and should be used in a browser environment
+import { quickbase } from "quickbase-js"; // Adjust the import path as needed
 
-<script src="https://cdn.jsdelivr.net/npm/quickbase-js@1.1.0-beta.4/dist/umd/quickbase.umd.js"></script>
-<script>
-  const qb = new QuickbaseJS({ realm: 'example', useTempTokens: true });
-  // Example: Fetching an app
-  qb.getApp({ appId: 'your-app-id' }).then(app => console.log(app));
-</script>
+// QuickBase config variables
+const QB_REALM = ""; // Your QuickBase realm (e.g., 'mycompany')
+const QB_SAML_TOKEN = ""; // Your SAML token (e.g., 'saml_xyz789...')
+const QB_APP_ID = ""; // Your app ID (e.g., 'bxyz789')
 
+const qb = quickbase({
+  realm: QB_REALM,
+  samlToken: QB_SAML_TOKEN,
+  useSso: true,
+});
+
+const getAppDetails = async () => {
+  try {
+    const response = await qb.getApp({
+      appId: QB_APP_ID,
+    });
+    console.log("App Details:", response);
+  } catch (error) {
+    console.error("Error fetching app:", error.message);
+  }
+};
+
+getAppDetails();
 ```
 
-## In QuickBase Code Pages (Browser Environment)
+## Configuration
+
+The `quickbase` function accepts a `QuickbaseConfig` object with the following options:
+
+### User Options
 
-### useTempTokens: true:
+- **`realm`** (`string`): Your QuickBase realm (e.g., "company"). This is required and has no default value.
 
-Token Fetch: Auto-fetches temporary tokens using the provided fetchApi (or window.fetch by default) with cookies (withCredentials: true in the internal tokenClient).
+- **`userToken`** (`string`, optional): A QuickBase user token for authentication. No default is provided.
 
-Subsequent Calls (e.g., getApp): Uses the same fetchApi (or window.fetch) with the QB-TEMP-TOKEN {TOKEN} header. No additional config needed beyond realm and useTempTokens.
+- **`useTempTokens`** (`boolean`, optional): Enables temporary token authentication. Defaults to `false`.
 
-How It Works: Leverages the browser’s session cookies for the initial token fetch, then uses the token for all API calls. In a real code page, window.fetch handles both steps seamlessly.
+- **`useSso`** (`boolean`, optional): Enables SSO authentication. Defaults to `false`.
 
-Test Output: The test uses page.evaluate for token fetch and node-fetch for getApp to bypass Playwright’s browser fetch issue, but in a code page, it’s all window.fetch.
+- **`samlToken`** (`string`, optional): A SAML token for SSO authentication. No default is provided.
 
-### userToken:
+### Advanced User Options
 
-All Calls: Uses the provided fetchApi (or window.fetch by default) with the QB-USER-TOKEN {TOKEN} header. No session cookies needed (credentials: "omit").
+- **`throttle`** (`{ type?: 'flow' | 'burst-aware';` `rate?: number;` `burst?: number;` `windowSeconds?: number }`, optional): Configures concurrent rate limiting to manage API request throughput. Defaults to `{ type: 'flow', rate: 5, burst: 50 }`.
 
-How It Works: The user token authenticates directly, independent of the browser session, making it straightforward and reliable.
+  - **`type`** (`string`): Throttle strategy. _Setting type without rate or burst enables default settings for that throttle type._
 
-Test Output: Confirms this with page.evaluate sending QB-USER-TOKEN.
+    - `'flow'` (default): Uses `FlowThrottleBucket` for a QuickBase-agnostic burst-then-rate flow. Ideal for steady request pacing.
 
-## In Node.js (Non-Browser Environment)
+    - `'burst-aware'`: Uses `BurstAwareThrottleBucket` for QuickBase-specific burst throttling with a sliding window (e.g., 100 requests per 10 seconds). Ideal for when you need to use nearly all your allotted API calls immediately, for example on page load.
 
-### userToken:
+  _Set rate and burst if changing defaults._
 
-All Calls: Works with a provided fetchApi (e.g., fetchApi: node-fetch). Sets QB-USER-TOKEN {TOKEN} header.
+  - **`rate`** (`number`): Requests per second after the initial burst (for `'flow'` only). Default is `5`. Meaning 5 request tokens get created each second.
 
-How It Works: Fully functional as long as fetchApi is supplied (e.g., node-fetch), since user tokens don’t require a browser session.
+  - **`burst`** (`number`): Maximum concurrent requests:
+    - For `'flow'`: Initial concurrent burst size (default: 50), followed by `rate`/sec.
+    - For `'burst-aware'`: Concurrent burst cap per window (default: 100), waits for window reset if exceeded.
+  - **`windowSeconds`** (`number`, `'burst-aware'` only): Sliding window duration in seconds (default: 10). Caps total requests (e.g., 100 requests available every 10s).
 
-Requirement: Must provide fetchApi explicitly (no default in Node.js).
+  - **Examples**:
+    - `{ type: 'flow', rate: 5, burst: 50 }`: **~10s for 100 requests**, (50 instant, and 1 every 200ms. In other words, 50 at 10/sec).
+    - `{ type: 'burst-aware', burst: 100, windowSeconds: 10 }`: **~10s for 100 requests**, (100 instant, refreshing every 10s for next burst).
 
-### useTempTokens: true:
+- **`maxRetries`** (`number`, optional): Maximum retries for failed requests. Defaults to `3`.
 
-Behavior: Fails with a clear error unless a browser-like fetchApi is provided:
+- **`retryDelay`** (`number`, optional): Base delay (in milliseconds) between retries, increases exponentially. Defaults to `1000`.
 
-"Temporary tokens require a browser environment or a custom fetchApi with browser-like session support"
+- **`tempTokenLifespan`** (`number`, optional): Lifespan (in milliseconds) of temporary tokens in the cache. Defaults to 4 minutes 50 seconds (290000 ms).
 
-How It Works: Temp tokens need a browser session with cookies, which Node.js can’t provide natively. A custom fetchApi (e.g., via Puppeteer) could work but is impractical for typical Node.js use.
+- **`convertDates`** (`boolean`, optional): Converts ISO date strings to `Date` objects in responses. Defaults to `true`.
 
-Practicality: Effectively unusable in Node.js without external browser support, aligning with QuickBase’s temp token requirement.
+- **`autoPaginate`** (`boolean`, optional): Enables automatic pagination of multi-page API responses. Defaults to `true`.
 
-## getTempTokenDBID
+### Overrides and Development Options
 
-Temporary Token Handling with getTempTokenDBID
-The QuickBase API provides the getTempTokenDBID method to fetch temporary tokens (QB-TEMP-TOKEN) for browser-based authentication, typically using session credentials (e.g., cookies). These tokens are short-lived (~5 minutes) and intended for secure, client-side API calls. In the generated OpenAPI client, getTempTokenDBID makes a straightforward GET request to /v1/auth/temporary/{dbid} and returns { temporaryAuthorization: string }. However, this raw implementation lacks caching and doesn’t optimize repeated calls, which can lead to unnecessary API requests.
-In quickbaseClient.ts, we enhance getTempTokenDBID when useTempTokens: true is enabled, wrapping it with intelligent token management:
-Caching: We introduce a TokenCache to store temporary tokens by dbid. Before fetching a new token, the client checks the cache. If a valid token exists, it’s returned immediately, avoiding redundant API calls.
+- **`fetchApi`** (`typeof fetch`, optional): Defaults to built-in `fetch` in browsers and Node.js >= 18. In older Node.js versions, node-fetch or another compatible library via fetchApi is required.
 
-Custom Fetch Logic: Instead of relying solely on the generated method, we use a custom fetchTempToken function to fetch tokens. This ensures consistency with browser-based session authentication (credentials: "include") and allows us to cache the result.
+- **`baseUrl`** (`string`, optional): Base URL for the QuickBase API. Defaults to `"https://api.quickbase.com/v1"`.
 
-Early Returns: For getTempTokenDBID, we bypass the generated method’s execution by returning the cached or freshly fetched token directly. This prevents unnecessary calls to the underlying API when the token is already available or just retrieved.
+- **`debug`** (`boolean`, optional): Enables debug logging to the console. Defaults to `false`.
 
-Why This Matters
-Efficiency: Caching reduces API requests, crucial for performance in browser environments where temp tokens are fetched frequently but don’t change within their lifespan.
+- **`tempToken`** (`string`, optional): Overrides default tempToken behavior by providing your own token.
 
-Seamless Integration: The wrapper supports both QB-USER-TOKEN (server-side) and QB-TEMP-TOKEN (client-side) workflows, controlled by the useTempTokens config. This makes the client versatile for different use cases.
+- **`tokenCache`** (`TokenCache`, optional): Allows use of a custom token cache instance.
 
-Testability: The enhancement fixes issues in unit tests (e.g., getTempToken.test.ts) by ensuring predictable behavior—fetching once and reusing cached tokens—avoiding unexpected errors from redundant calls.
+---
 
-How It Works
-When you call client.getTempTokenDBID({ dbid: "someDbid" }) with useTempTokens: true:
-Cache Check: Looks for an existing token in tokenCache for the given dbid.
+#### Configuration Notes
 
-Fetch if Needed: If no cached token exists, fetchTempToken requests a new one from /v1/auth/temporary/{dbid} and caches it.
+- **Authentication**: Three mutually exclusive methods: `userToken`, `useTempTokens`, and `useSso` with `samlToken`. Only one may be active at a time.
+- **`tokenCache`**: Temporary tokens are cached here with their `dbid` and `tempTokenLifespan` when `useTempTokens` is enabled.
 
-Return Early: Returns { temporaryAuthorization: token } immediately, skipping the generated method’s execution.
+---
 
-For other methods (e.g., getFields), the fetched temp token is applied to the Authorization header, ensuring authenticated API calls without re-fetching.
+### Pagination Control
+
+The library supports automatic pagination for methods like `runQuery` when `autoPaginate` is enabled (default: `true`). To temporarily disable or constrain pagination for a specific operation without altering the global configuration, use the `withPaginationDisabled()` or `withPaginationLimit()` methods.
+
+#### `withPaginationDisabled(callback)`
+
+- **Description**: Executes an asynchronous callback with pagination temporarily disabled, restoring the original `autoPaginate` setting afterward. Useful for fetching only the initial page of results without modifying method signatures or global settings.
+- **Parameters**:
+  - `callback`: `() => Promise<T>` - An async function containing the API call(s) to execute without pagination.
+- **Returns**: `Promise<T>` - The result of the callback.
+- **Example**:
+
+```javascript
+import { quickbase } from "quickbase-js"; // Adjust the import path as needed
+
+const QB_REALM = ""; // Your QuickBase realm (e.g., 'mycompany')
+const QB_USER_TOKEN = ""; // Your QuickBase user token (e.g., 'b12345_abcde...')
+const QB_TABLE_ID = ""; // Your table ID (e.g., 'bxyz789')
+
+const qb = quickbase({
+  realm: QB_REALM,
+  userToken: QB_USER_TOKEN,
+  autoPaginate: true, // Pagination enabled by default
+});
+
+const runLimitedQuery = async () => {
+  try {
+    const result = await qb.withPaginationDisabled(async () => {
+      return qb.runQuery({
+        body: {
+          from: QB_TABLE_ID,
+          select: [3], // Example field ID
+          options: { top: 2 }, // Fetch only 2 records
+        },
+      });
+    });
+    console.log("Fetched records:", result.data.length); // Outputs: 2
+  } catch (error) {
+    console.error("Error running query:", error.message);
+  }
+};
+
+runLimitedQuery();
+```
+
+#### `withPaginationLimit(limit, callback)`
+
+- **Description**: Executes an asynchronous callback with pagination enabled but limited to a specified number of records, restoring the original `autoPaginate` setting afterward. Useful for fetching a precise number of records (e.g., 100) from a larger dataset, stopping pagination once the limit is reached, without modifying method signatures or global settings.
+- **Parameters**:
+  - `limit`: `number` - The maximum number of records to fetch across all pages.
+  - `callback`: `() => Promise<T>` - An async function containing the API call(s) to execute with the pagination limit.
+- **Returns**: `Promise<T>` - The result of the callback, containing up to `limit` records.
+- **Example**:
+
+```javascript
+import { quickbase } from "quickbase-js"; // Adjust the import path as needed
+
+const QB_REALM = ""; // Your QuickBase realm (e.g., 'mycompany')
+const QB_USER_TOKEN = ""; // Your QuickBase user token (e.g., 'b12345_abcde...')
+const QB_TABLE_ID = ""; // Your table ID (e.g., 'bxyz789')
+
+const qb = quickbase({
+  realm: QB_REALM,
+  userToken: QB_USER_TOKEN,
+  autoPaginate: true, // Pagination enabled by default
+});
+
+const runCappedQuery = async () => {
+  try {
+    const result = await qb.withPaginationLimit(100, async () => {
+      return qb.runQuery({
+        body: {
+          from: QB_TABLE_ID,
+          select: [3], // Example field ID
+          options: { top: 25 }, // Fetch 25 records per page
+        },
+      });
+    });
+    console.log("Fetched records:", result.data.length); // Outputs: 100
+  } catch (error) {
+    console.error("Error running query:", error.message);
+  }
+};
+
+runCappedQuery();
+```
+
+---
+
+### Development workflow
+
+```bash
+npm run gen:all
+npm run build
+npm run test:all
+```
 
-## 401 Unauthorized Error Behavior
+---
 
-The quickbase-js library manages 401 Unauthorized errors from the QuickBase API when using temporary tokens (useTempTokens: true). Normally, it keeps tokens fresh via a time-managed cache intending to never have a 401 Unauthorized error, but there is added safety measures incase a 401 happens to occur.
+### Prerequisites
 
-If a 401 happens, the library tries once more with a fresh temporary token.
+- Node.js version >= 18
+- A Quickbase account. [Free tier available](https://www.quickbase.com/builder-program).
 
-It gets the new token using fetchTempToken and retries the call.
+---
 
-If the retry fails with another 401, it stops and throws an error like API Error: Unauthorized (Status: 401).
+### Contributing
 
-Fetching a New Token:
-If fetchTempToken itself gets a 401 (e.g., no valid login session), it doesn’t retry.
+If you would like to contribute to this project, please fork the repository and submit a pull request.
 
-It throws an error right away: API Error: Unauthorized (Status: 401).
+---
 
-Why It’s Like This
-One Retry: Retries once to fix expired tokens, but stops to avoid endless tries.
+### License
 
-Fast Fail: No retry on fetchTempToken 401s means you know quickly if login is broken.
+MIT License - see LICENSE for details.
 
-No Loops: Built to never get stuck retrying forever.
+---