quickbase-js 2.3.0 → 2.4.1

package/package.json

@@ -1,24 +1,25 @@
 {
   "name": "quickbase-js",
-  "version": "2.3.0",
-  "description": "TypeScript/JavaScript client for the QuickBase JSON RESTful API",
+  "version": "2.4.1",
+  "description": "TypeScript client for the QuickBase JSON and XML APIs: every endpoint, pagination, retries, code-page temp tokens",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
-  "browser": "dist/quickbase.min.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
       "types": "./dist/index.d.ts",
-      "browser": "./dist/quickbase.min.js"
-    }
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
   },
   "bin": {
     "quickbase-js": "./bin/quickbase-js.js"
   },
   "files": [
     "dist",
+    "src",
     "bin",
     "README.md",
     "LICENSE"
@@ -35,14 +36,13 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "lint": "eslint src tests",
-    "typecheck": "tsc --noEmit",
-    "spec:convert": "tsx spec/tools/cli.ts convert",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.examples.json",
+    "spec:normalize": "tsx spec/tools/cli.ts normalize",
     "spec:patch": "tsx spec/tools/cli.ts patch",
     "spec:validate": "tsx spec/tools/cli.ts validate",
-    "spec:split": "tsx spec/tools/cli.ts split",
     "spec:generate": "tsx scripts/spec/generate.ts",
-    "spec:build": "npm run spec:convert && npm run spec:patch && npm run spec:validate && npm run spec:generate",
-    "docs": "typedoc",
+    "spec:build": "npm run spec:normalize && npm run spec:patch && npm run spec:validate && npm run spec:generate",
+    "docs": "typedoc && node scripts/build-llms.js",
     "docs:watch": "typedoc --watch",
     "prepublishOnly": "npm run clean && npm run build && npm run test"
   },
@@ -58,7 +58,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/DrewBradfordXYZ/quickbase-js.git"
+    "url": "git+https://github.com/DrewBradfordXYZ/quickbase-js.git"
   },
   "bugs": {
     "url": "https://github.com/DrewBradfordXYZ/quickbase-js/issues"
@@ -76,5 +76,8 @@
     "typescript": "^5.4.0",
     "vitest": "^1.4.0",
     "yaml": "^2.4.0"
-  }
+  },
+  "unpkg": "dist/quickbase.min.js",
+  "jsdelivr": "dist/quickbase.min.js",
+  "sideEffects": false
 }

package/src/auth/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Authentication module exports
+ */
+
+export type { AuthStrategy, AuthContext, CachedToken } from './types.js';
+export { UserTokenStrategy } from './user-token.js';
+export { TempTokenStrategy } from './temp-token.js';
+export { SsoTokenStrategy } from './sso-token.js';
+export { TicketStrategy } from './ticket.js'; // XML-API-TICKET: Remove if XML API discontinued
+export { TokenCache } from './token-cache.js';
+
+import type { AuthConfig } from '../core/types.js';
+import type { AuthStrategy, AuthContext } from './types.js';
+import { UserTokenStrategy } from './user-token.js';
+import { TempTokenStrategy } from './temp-token.js';
+import { SsoTokenStrategy } from './sso-token.js';
+import { TicketStrategy } from './ticket.js'; // XML-API-TICKET: Remove if XML API discontinued
+
+/**
+ * Factory function to create the appropriate auth strategy
+ */
+export function createAuthStrategy(
+  authConfig: AuthConfig,
+  context: AuthContext
+): AuthStrategy {
+  switch (authConfig.type) {
+    case 'user-token':
+      return new UserTokenStrategy(authConfig.userToken, context);
+
+    case 'temp-token':
+      return new TempTokenStrategy(authConfig.userToken, context, {
+        appToken: authConfig.appToken,
+        tokenLifespanMs: authConfig.tokenLifespanMs,
+      });
+
+    case 'sso':
+      return new SsoTokenStrategy(authConfig.samlToken, context);
+
+    // XML-API-TICKET: Remove this case if XML API is discontinued
+    case 'ticket':
+      return new TicketStrategy(
+        authConfig.username,
+        authConfig.password,
+        {
+          hours: authConfig.hours,
+          onExpired: authConfig.onExpired,
+          persist: authConfig.persist,
+        },
+        context
+      );
+
+    default:
+      throw new Error(`Unknown auth type: ${(authConfig as { type: string }).type}`);
+  }
+}

package/src/auth/sso-token.ts

@@ -0,0 +1,143 @@
+/**
+ * SSO Token Authentication Strategy
+ *
+ * Exchanges a SAML token for a QuickBase temporary token via OAuth token exchange.
+ */
+
+import type { AuthStrategy, AuthContext } from './types.js';
+import type { Logger } from '../core/logger.js';
+import { TokenCache } from './token-cache.js';
+import { DEFAULT_CONFIG } from '../core/types.js';
+import { AuthenticationError } from '../core/errors.js';
+
+export class SsoTokenStrategy implements AuthStrategy {
+  private readonly samlToken: string;
+  private readonly realm: string;
+  private readonly baseUrl: string;
+  private readonly fetchApi: typeof fetch;
+  private readonly logger: Logger;
+  private readonly cache: TokenCache;
+
+  /**
+   * Track pending SSO token exchange to deduplicate concurrent requests
+   */
+  private pendingExchange: Promise<string> | null = null;
+
+  constructor(
+    samlToken: string,
+    context: AuthContext,
+    options?: { tokenLifespanMs?: number }
+  ) {
+    this.samlToken = samlToken;
+    this.realm = context.realm;
+    this.baseUrl = context.baseUrl;
+    this.fetchApi = context.fetchApi;
+    this.logger = context.logger;
+    // SSO tokens are global, not per-dbid, so we use a single cache key
+    this.cache = new TokenCache(
+      options?.tokenLifespanMs ?? DEFAULT_CONFIG.tempTokenLifespanMs
+    );
+  }
+
+  private get cacheKey(): string {
+    return '__sso__';
+  }
+
+  async getToken(_dbid?: string): Promise<string> {
+    // Check cache first
+    const cachedToken = this.cache.get(this.cacheKey);
+    if (cachedToken) {
+      this.logger.token('cache-hit');
+      return cachedToken;
+    }
+
+    this.logger.token('cache-miss');
+
+    // Check if there's already an exchange in progress
+    if (this.pendingExchange) {
+      this.logger.debug('Waiting for existing SSO token exchange');
+      return this.pendingExchange;
+    }
+
+    // Exchange SAML token for QuickBase token
+    const exchangePromise = this.exchangeToken();
+    this.pendingExchange = exchangePromise;
+
+    try {
+      return await exchangePromise;
+    } finally {
+      this.pendingExchange = null;
+    }
+  }
+
+  private async exchangeToken(): Promise<string> {
+    this.logger.token('fetch');
+
+    const url = `${this.baseUrl}/auth/oauth/token`;
+
+    const body = new URLSearchParams({
+      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(url, {
+      method: 'POST',
+      headers: {
+        'QB-Realm-Hostname': `${this.realm}.quickbase.com`,
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: body.toString(),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new AuthenticationError(
+        `SSO token exchange failed: ${response.status} ${errorText}`,
+        { rayId: response.headers.get('qb-api-ray') || undefined }
+      );
+    }
+
+    const data = await response.json() as {
+      access_token?: string;
+      issued_token_type?: string;
+      token_type?: string;
+    };
+
+    const token = data.access_token;
+    if (!token) {
+      throw new AuthenticationError('No access_token in SSO exchange response');
+    }
+
+    // Cache the token
+    this.cache.set(this.cacheKey, token);
+    this.logger.debug('Cached new SSO token');
+
+    return token;
+  }
+
+  getAuthorizationHeader(token: string): string {
+    return `QB-TEMP-TOKEN ${token}`;
+  }
+
+  async handleAuthError(_dbid?: string): Promise<boolean> {
+    // Invalidate the cached token
+    this.invalidate();
+
+    // Try to exchange for a new token
+    try {
+      this.logger.token('refresh');
+      await this.getToken();
+      return true;
+    } catch (error) {
+      this.logger.error('Failed to refresh SSO token', error);
+      return false;
+    }
+  }
+
+  invalidate(_dbid?: string): void {
+    this.logger.token('expire');
+    this.cache.clear();
+  }
+}

package/src/auth/temp-token.ts

@@ -0,0 +1,160 @@
+/**
+ * Temporary Token Authentication Strategy
+ *
+ * Fetches database-specific temporary tokens from the QuickBase API.
+ * Tokens are cached and automatically refreshed when expired.
+ */
+
+import type { AuthStrategy, AuthContext } from './types.js';
+import type { Logger } from '../core/logger.js';
+import { TokenCache } from './token-cache.js';
+import { DEFAULT_CONFIG } from '../core/types.js';
+import { AuthenticationError } from '../core/errors.js';
+
+export class TempTokenStrategy implements AuthStrategy {
+  private readonly userToken?: string;
+  private readonly appToken?: string;
+  private readonly realm: string;
+  private readonly baseUrl: string;
+  private readonly fetchApi: typeof fetch;
+  private readonly logger: Logger;
+  private readonly cache: TokenCache;
+
+  /**
+   * Track pending token fetches to deduplicate concurrent requests
+   * This prevents multiple simultaneous API calls for the same dbid
+   */
+  private readonly pendingFetches = new Map<string, Promise<string>>();
+
+  constructor(
+    userToken: string | undefined,
+    context: AuthContext,
+    options?: { appToken?: string; tokenLifespanMs?: number }
+  ) {
+    this.userToken = userToken;
+    this.appToken = options?.appToken;
+    this.realm = context.realm;
+    this.baseUrl = context.baseUrl;
+    this.fetchApi = context.fetchApi;
+    this.logger = context.logger;
+    this.cache = new TokenCache(
+      options?.tokenLifespanMs ?? DEFAULT_CONFIG.tempTokenLifespanMs
+    );
+  }
+
+  async getToken(dbid?: string): Promise<string> {
+    if (!dbid) {
+      throw new Error('Database ID (dbid) is required for temporary token authentication');
+    }
+
+    // Check cache first
+    const cachedToken = this.cache.get(dbid);
+    if (cachedToken) {
+      this.logger.token('cache-hit', dbid);
+      return cachedToken;
+    }
+
+    this.logger.token('cache-miss', dbid);
+
+    // Check if there's already a fetch in progress for this dbid
+    const pendingFetch = this.pendingFetches.get(dbid);
+    if (pendingFetch) {
+      this.logger.debug(`Waiting for existing token fetch for dbid: ${dbid}`);
+      return pendingFetch;
+    }
+
+    // Fetch new token
+    const fetchPromise = this.fetchToken(dbid);
+    this.pendingFetches.set(dbid, fetchPromise);
+
+    try {
+      const token = await fetchPromise;
+      return token;
+    } finally {
+      this.pendingFetches.delete(dbid);
+    }
+  }
+
+  private async fetchToken(dbid: string): Promise<string> {
+    this.logger.token('fetch', dbid);
+
+    const url = `${this.baseUrl}/auth/temporary/${dbid}`;
+    const headers: Record<string, string> = {
+      'QB-Realm-Hostname': `${this.realm}.quickbase.com`,
+      'Content-Type': 'application/json',
+    };
+
+    // Only include Authorization header if we have a userToken
+    // For Code Pages, browser session cookies handle auth instead
+    if (this.userToken) {
+      headers['Authorization'] = `QB-USER-TOKEN ${this.userToken}`;
+    }
+
+    if (this.appToken) {
+      headers['QB-App-Token'] = this.appToken;
+    }
+
+    const response = await this.fetchApi(url, {
+      method: 'GET',
+      headers,
+      credentials: 'include', // Include cookies for Code Page auth
+    } as RequestInit);
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new AuthenticationError(
+        `Failed to fetch temporary token for ${dbid}: ${response.status} ${errorText}`,
+        { rayId: response.headers.get('qb-api-ray') || undefined }
+      );
+    }
+
+    const data = await response.json() as { temporaryAuthorization?: string };
+    const token = data.temporaryAuthorization;
+
+    if (!token) {
+      throw new AuthenticationError(
+        `No temporary token in response for ${dbid}`
+      );
+    }
+
+    // Cache the token
+    this.cache.set(dbid, token);
+    this.logger.debug(`Cached new token for dbid: ${dbid}`);
+
+    return token;
+  }
+
+  getAuthorizationHeader(token: string): string {
+    return `QB-TEMP-TOKEN ${token}`;
+  }
+
+  async handleAuthError(dbid?: string): Promise<boolean> {
+    if (!dbid) {
+      this.logger.debug('Auth error without dbid - cannot refresh temp token');
+      return false;
+    }
+
+    // Invalidate the cached token
+    this.invalidate(dbid);
+
+    // Try to fetch a new token
+    try {
+      this.logger.token('refresh', dbid);
+      await this.getToken(dbid);
+      return true;
+    } catch (error) {
+      this.logger.error(`Failed to refresh temp token for ${dbid}`, error);
+      return false;
+    }
+  }
+
+  invalidate(dbid?: string): void {
+    if (dbid) {
+      this.logger.token('expire', dbid);
+      this.cache.delete(dbid);
+    } else {
+      // Invalidate all tokens
+      this.cache.clear();
+    }
+  }
+}