quickbase-js 0.1.0-beta.8 → 1.0.0

package/README.md

@@ -1,204 +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
 ```
 
-## Examples
+#### CDN install.
 
-### CDN Code Page
+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>
-    <script src="https://cdn.jsdelivr.net/npm/quickbase-js@1.1.0-beta.6/dist/umd/quickbase.umd.min.js"></script>
+    <!-- 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-js CDN Example</h1>
-      <p id="result">Loading...</p>
-    </div>
     <script>
-      var realm = "xxxxxxxxxxxxxxxxxxxx"; // replace with your realm
-      var appId = "xxxxxxxxxxxxxxxxxxxx"; // replace with your app ID
-      if (typeof QuickbaseJS === "undefined") {
-        document.getElementById("result").textContent =
-          "Error: Failed to load QuickbaseJS library.";
-      } else {
-        var qbClient = QuickbaseJS.quickbase({
-          realm,
-          useTempTokens: true,
-        });
-
-        qbClient
-          .getApp({ appId })
-          .then(function (app) {
-            document.getElementById("result").textContent =
-              "App Name: " + app.name;
-          })
-          .catch(function (err) {
-            document.getElementById("result").textContent =
-              "Error: " + (err.message || "Failed to load app");
-          });
-      }
+      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>
 ```
 
-# Development workflow
-
-```bash
-npm run gen: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:
 
-### useTempTokens: true:
+### User Options
 
-Token Fetch: Auto-fetches temporary tokens using the provided fetchApi (or window.fetch by default) with cookies (withCredentials: true in the internal tokenClient).
+- **`realm`** (`string`): Your QuickBase realm (e.g., "company"). This is required and has no default value.
 
-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.
+- **`userToken`** (`string`, optional): A QuickBase user token for authentication. No default is provided.
 
-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.
+- **`useTempTokens`** (`boolean`, optional): Enables temporary token 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.
+- **`useSso`** (`boolean`, optional): Enables SSO authentication. Defaults to `false`.
 
-### userToken:
+- **`samlToken`** (`string`, optional): A SAML token for SSO authentication. No default is provided.
 
-All Calls: Uses the provided fetchApi (or window.fetch by default) with the QB-USER-TOKEN {TOKEN} header. No session cookies needed (credentials: "omit").
+### Advanced User Options
 
-How It Works: The user token authenticates directly, independent of the browser session, making it straightforward and reliable.
+- **`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 }`.
 
-Test Output: Confirms this with page.evaluate sending QB-USER-TOKEN.
+  - **`type`** (`string`): Throttle strategy. _Setting type without rate or burst enables default settings for that throttle type._
 
-## In Node.js (Non-Browser Environment)
+    - `'flow'` (default): Uses `FlowThrottleBucket` for a QuickBase-agnostic burst-then-rate flow. Ideal for steady request pacing.
 
-### userToken:
+    - `'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.
 
-All Calls: Works with a provided fetchApi (e.g., fetchApi: node-fetch). Sets QB-USER-TOKEN {TOKEN} header.
+  _Set rate and burst if changing defaults._
 
-How It Works: Fully functional as long as fetchApi is supplied (e.g., node-fetch), since user tokens don’t require a browser session.
+  - **`rate`** (`number`): Requests per second after the initial burst (for `'flow'` only). Default is `5`. Meaning 5 request tokens get created each second.
 
-Requirement: Must provide fetchApi explicitly (no default in Node.js).
+  - **`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).
 
-### useTempTokens: true:
+  - **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).
 
-Behavior: Fails with a clear error unless a browser-like fetchApi is provided:
+- **`maxRetries`** (`number`, optional): Maximum retries for failed requests. Defaults to `3`.
 
-"Temporary tokens require a browser environment or a custom fetchApi with browser-like session support"
+- **`retryDelay`** (`number`, optional): Base delay (in milliseconds) between retries, increases exponentially. Defaults to `1000`.
 
-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.
+- **`tempTokenLifespan`** (`number`, optional): Lifespan (in milliseconds) of temporary tokens in the cache. Defaults to 4 minutes 50 seconds (290000 ms).
 
-Practicality: Effectively unusable in Node.js without external browser support, aligning with QuickBase’s temp token requirement.
+- **`convertDates`** (`boolean`, optional): Converts ISO date strings to `Date` objects in responses. Defaults to `true`.
 
-## getTempTokenDBID
+- **`autoPaginate`** (`boolean`, optional): Enables automatic pagination of multi-page API responses. Defaults to `true`.
 
-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.
+### Overrides and Development Options
 
-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.
+- **`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.
 
-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.
+- **`baseUrl`** (`string`, optional): Base URL for the QuickBase API. Defaults to `"https://api.quickbase.com/v1"`.
 
-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.
+- **`debug`** (`boolean`, optional): Enables debug logging to the console. Defaults to `false`.
 
-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.
+- **`tempToken`** (`string`, optional): Overrides default tempToken behavior by providing your own token.
 
-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.
+- **`tokenCache`** (`TokenCache`, optional): Allows use of a custom token cache instance.
 
-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.
+---
 
-Fetch if Needed: If no cached token exists, fetchTempToken requests a new one from /v1/auth/temporary/{dbid} and caches it.
+#### Configuration Notes
 
-Return Early: Returns { temporaryAuthorization: token } immediately, skipping the generated method’s execution.
+- **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.
 
-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.
+---