quickbase-js 1.0.1-beta.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+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.
+
+### 1.0.1-beta.0 (2025-03-10)
+
+Testing done in a consuming library for getApp() and getFields()

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Drew Bradford
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# quickbase-js
+
+# Development workflow
+
+```bash
+npm run fix-spec
+npm run regenerate
+npm run generate-unified
+npm run build
+npm run test
+npm run test:pw:qb:all
+```
+
+## In QuickBase Code Pages (Browser Environment)
+
+### useTempTokens: true:
+
+Token Fetch: Auto-fetches temporary tokens using the provided fetchApi (or window.fetch by default) with cookies (withCredentials: true in the internal tokenClient).
+
+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.
+
+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.
+
+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.
+
+### userToken:
+
+All Calls: Uses the provided fetchApi (or window.fetch by default) with the QB-USER-TOKEN {TOKEN} header. No session cookies needed (credentials: "omit").
+
+How It Works: The user token authenticates directly, independent of the browser session, making it straightforward and reliable.
+
+Test Output: Confirms this with page.evaluate sending QB-USER-TOKEN.
+
+## In Node.js (Non-Browser Environment)
+
+### userToken:
+
+All Calls: Works with a provided fetchApi (e.g., fetchApi: node-fetch). Sets QB-USER-TOKEN {TOKEN} header.
+
+How It Works: Fully functional as long as fetchApi is supplied (e.g., node-fetch), since user tokens don’t require a browser session.
+
+Requirement: Must provide fetchApi explicitly (no default in Node.js).
+
+### useTempTokens: true:
+
+Behavior: Fails with a clear error unless a browser-like fetchApi is provided:
+
+"Temporary tokens require a browser environment or a custom fetchApi with browser-like session support"
+
+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.
+
+Practicality: Effectively unusable in Node.js without external browser support, aligning with QuickBase’s temp token requirement.
+
+## getTempTokenDBID
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+Fetch if Needed: If no cached token exists, fetchTempToken requests a new one from /v1/auth/temporary/{dbid} and caches it.
+
+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.
+
+## 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.
+
+If a 401 happens, the library tries once more with a fresh temporary token.
+
+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).
+
+Fetching a New Token:
+If fetchTempToken itself gets a 401 (e.g., no valid login session), it doesn’t retry.
+
+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.
+
+Fast Fail: No retry on fetchTempToken 401s means you know quickly if login is broken.
+
+No Loops: Built to never get stuck retrying forever.

package/build.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+const { readFile, writeFile } = require("fs/promises");
+const { execSync } = require("child_process");
+const esbuild = require("esbuild");
+const pkg = require("./package.json");
+
+async function build() {
+  try {
+    // Compile TypeScript
+    console.log("Compiling TypeScript...");
+    execSync("npx tsc -b", { stdio: "inherit" });
+
+    // Format with Prettier
+    console.log("Formatting files with Prettier...");
+    execSync("npx prettier --write src/**/*.ts dist/**/*.js", {
+      stdio: "inherit",
+    });
+
+    // Bundle for Browser
+    console.log("Bundling for Browser...");
+    await esbuild.build({
+      entryPoints: ["dist/QuickBaseClient.js"],
+      bundle: true,
+      minify: true,
+      sourcemap: true,
+      target: ["es2015"],
+      outfile: "dist/quickbase-client.browser.min.js",
+    });
+
+    // Load Sources
+    console.log("Loading Sources...");
+    const browserSource = await readFile(
+      "dist/quickbase-client.browser.min.js",
+      "utf8"
+    );
+    const cjsSource = await readFile("dist/QuickBaseClient.js", "utf8");
+    const license = await readFile("LICENSE", "utf8");
+
+    // Build Header
+    console.log("Adding Metadata...");
+    const header = [
+      "/*! ",
+      ` * ${pkg.name} v${pkg.version}`,
+      ` * ${pkg.description || "A QuickBase API Client"}`,
+      ` * License: ${pkg.license}`,
+      ` * ${license}`,
+      " */",
+    ].join("\n");
+
+    // Write Output Files
+    await Promise.all([
+      writeFile(
+        "dist/quickbase-client.browser.min.js",
+        header + "\n" + browserSource
+      ),
+      writeFile("dist/QuickBaseClient.js", header + "\n" + cjsSource),
+    ]);
+
+    console.log("Build completed successfully.");
+  } catch (error) {
+    console.error("Build failed:", error);
+    process.exit(1);
+  }
+}
+
+build();