quickbase-js 2.3.0 → 2.4.1

package/src/client/request.ts

@@ -0,0 +1,544 @@
+/**
+ * Request execution module
+ *
+ * Handles the full request lifecycle:
+ * 1. Authentication
+ * 2. Throttling (if enabled)
+ * 3. Request execution
+ * 4. Error handling with retry
+ */
+
+import type { RequestContext, ResolvedConfig } from '../core/types.js';
+import type { AuthStrategy } from '../auth/types.js';
+import type { Logger } from '../core/logger.js';
+import type { Throttle } from './throttle.js';
+import {
+  QuickbaseError,
+  RateLimitError,
+  TimeoutError,
+  ReadOnlyError,
+  parseErrorResponse,
+  isRetryableError,
+} from '../core/errors.js';
+import { extractRateLimitInfo, sleep } from './retry.js';
+import { getRealmHostname } from '../core/config.js';
+import { transformDates } from '../core/dates.js';
+import {
+  transformRequest,
+  transformResponse,
+  extractTableIdFromRequest,
+} from '../core/transform.js';
+import { resolveTableAlias } from '../core/schema.js';
+
+// =============================================================================
+// Read-Only Mode - Defense-in-Depth
+// =============================================================================
+
+/**
+ * JSON API endpoints that modify data.
+ * Layer 1 of defense-in-depth - explicit blocklist.
+ * Uses "METHOD /path" for exact match, "METHOD /path/" for prefix match.
+ * Note: Paths do not include /v1 prefix as the SDK uses relative paths.
+ */
+const jsonWriteEndpoints: Record<string, boolean> = {
+  // Records
+  'POST /records': true, // Upsert
+  'DELETE /records': true, // DeleteRecords
+
+  // Apps
+  'POST /apps': true, // CreateApp
+  'DELETE /apps': true, // DeleteApp (prefix)
+  'POST /apps/': true, // UpdateApp, CopyApp (prefix)
+  'DELETE /apps/': true, // DeleteApp (prefix)
+
+  // Tables
+  'POST /tables': true, // CreateTable
+  'DELETE /tables': true, // DeleteTable (prefix)
+  'POST /tables/': true, // UpdateTable, relationships (prefix)
+  'DELETE /tables/': true, // DeleteRelationship (prefix)
+
+  // Fields
+  'POST /fields': true, // CreateField
+  'DELETE /fields': true, // DeleteFields
+  'POST /fields/': true, // UpdateField (prefix)
+
+  // Files
+  'DELETE /files/': true, // DeleteFile (prefix)
+
+  // User tokens
+  'POST /usertoken': true, // Clone, Transfer, Deactivate
+  'DELETE /usertoken': true, // Delete
+
+  // Users and groups
+  'PUT /users': true, // DenyUsers, UndenyUsers
+  'PUT /users/': true, // DenyUsersAndGroups (prefix)
+  'POST /groups/': true, // AddMembers, AddManagers, AddSubgroups (prefix)
+  'DELETE /groups/': true, // RemoveMembers, RemoveManagers, RemoveSubgroups (prefix)
+
+  // Solutions
+  'POST /solutions': true, // CreateSolution
+  'PUT /solutions/': true, // UpdateSolution, ChangesetSolution (prefix)
+
+  // Document generation (GET but writes)
+  'GET /docTemplates/': true, // GenerateDocument (prefix)
+
+  // Solution from record (GET but writes)
+  'GET /solutions/fromrecord': true, // CreateSolutionFromRecord
+};
+
+/**
+ * POST endpoints that are actually read-only (allowlist).
+ * These are exceptions to the "POST = write" rule.
+ * Note: Paths do not include /v1 prefix as the SDK uses relative paths.
+ */
+const jsonReadOnlyPOSTEndpoints: Record<string, boolean> = {
+  'POST /records/query': true, // RunQuery - read-only
+  'POST /reports/': true, // RunReport - read-only (prefix)
+  'POST /formula/run': true, // RunFormula - read-only
+  'POST /audit': true, // Audit logs - read-only
+  'POST /users': true, // GetUsers - read-only despite POST
+  'POST /analytics/': true, // Analytics - read-only (prefix)
+};
+
+/**
+ * Check if HTTP method is a write operation.
+ */
+function isWriteMethod(method: string): boolean {
+  const upper = method.toUpperCase();
+  return upper === 'POST' || upper === 'PUT' || upper === 'DELETE' || upper === 'PATCH';
+}
+
+/**
+ * Check if request matches a known write endpoint.
+ * Uses both exact matching and prefix matching for paths with IDs.
+ */
+function isJSONWriteEndpoint(method: string, path: string): boolean {
+  const key = `${method} ${path}`;
+
+  // Exact match
+  if (jsonWriteEndpoints[key]) {
+    return true;
+  }
+
+  // Prefix match for paths with IDs (e.g., "POST /v1/apps/" matches "POST /v1/apps/abc123")
+  for (let i = path.length - 1; i >= 0; i--) {
+    if (path[i] === '/') {
+      const prefixKey = `${method} ${path.slice(0, i + 1)}`;
+      if (jsonWriteEndpoints[prefixKey]) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if a POST request is actually read-only (allowlist).
+ */
+function isJSONReadOnlyPOSTEndpoint(path: string): boolean {
+  const key = `POST ${path}`;
+
+  // Exact match
+  if (jsonReadOnlyPOSTEndpoints[key]) {
+    return true;
+  }
+
+  // Prefix match
+  for (let i = path.length - 1; i >= 0; i--) {
+    if (path[i] === '/') {
+      const prefixKey = `POST ${path.slice(0, i + 1)}`;
+      if (jsonReadOnlyPOSTEndpoints[prefixKey]) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if request is blocked by read-only mode.
+ * Uses two layers of defense:
+ * 1. Explicit blocklist of known write endpoints
+ * 2. HTTP method check (catch-all for POST/PUT/DELETE/PATCH)
+ */
+function checkReadOnly(config: ResolvedConfig, method: string, path: string): void {
+  if (!config.readOnly) {
+    return;
+  }
+
+  // Layer 1: Explicit blocklist check (defense-in-depth)
+  if (isJSONWriteEndpoint(method, path)) {
+    // Exception: Some POST endpoints are read-only (RunQuery, RunReport, etc.)
+    if (method === 'POST' && isJSONReadOnlyPOSTEndpoint(path)) {
+      return;
+    }
+    throw new ReadOnlyError(method, path);
+  }
+
+  // Layer 2: HTTP method check (catch-all for any endpoints not in blocklist)
+  if (isWriteMethod(method)) {
+    // Exception: Some POST endpoints are read-only
+    if (method === 'POST' && isJSONReadOnlyPOSTEndpoint(path)) {
+      return;
+    }
+    throw new ReadOnlyError(method, path);
+  }
+}
+
+// =============================================================================
+// Request Types
+// =============================================================================
+
+export interface RequestOptions {
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  path: string;
+  body?: unknown;
+  /** Content type of a body that isn't JSON (QBL is application/x-yaml); the body is sent as given */
+  bodyType?: string;
+  /** 'text' returns the response body unparsed (QBL, file content) instead of parsing JSON */
+  responseType?: 'json' | 'text';
+  query?: Record<string, string | number | boolean | undefined>;
+  /** Database ID for temp token auth */
+  dbid?: string;
+  /** Custom headers */
+  headers?: Record<string, string>;
+}
+
+export interface RequestExecutorOptions {
+  config: ResolvedConfig;
+  auth: AuthStrategy;
+  throttle: Throttle;
+  logger: Logger;
+}
+
+/**
+ * Extract dbid from request options for temp-token auth.
+ * Checks multiple locations where table/app ID may appear.
+ * Resolves aliases to IDs if schema is provided.
+ */
+export function extractDbid(
+  options: RequestOptions,
+  config?: ResolvedConfig
+): string | undefined {
+  // 1. Explicit dbid takes priority
+  if (options.dbid) {
+    return config?.schema
+      ? resolveTableAlias(config.schema, options.dbid)
+      : options.dbid;
+  }
+
+  // 2. Check query params for tableId
+  if (options.query?.tableId) {
+    const tableId = String(options.query.tableId);
+    return config?.schema ? resolveTableAlias(config.schema, tableId) : tableId;
+  }
+
+  // 3. Check query params for appId (for app-level operations)
+  if (options.query?.appId) {
+    return String(options.query.appId);
+  }
+
+  // 4. Check path for tableId (e.g., /v1/tables/{tableId}/...)
+  const tableIdMatch = options.path.match(/\/tables\/([^/?]+)/);
+  if (tableIdMatch) {
+    return tableIdMatch[1];
+  }
+
+  // 5. Check path for appId (e.g., /v1/apps/{appId}/...)
+  const appIdMatch = options.path.match(/\/apps\/([^/?]+)/);
+  if (appIdMatch) {
+    return appIdMatch[1];
+  }
+
+  // 6. Check request body for 'from' or 'to' fields
+  if (options.body && typeof options.body === 'object') {
+    const tableId = extractTableIdFromRequest(
+      options.body as Record<string, unknown>,
+      config?.schema
+    );
+    if (tableId) return tableId;
+  }
+
+  return undefined;
+}
+
+/**
+ * Build URL with query parameters
+ */
+function buildUrl(
+  baseUrl: string,
+  path: string,
+  query?: Record<string, string | number | boolean | undefined>
+): string {
+  // Ensure baseUrl ends with / and path doesn't start with / to properly join them
+  // new URL('/apps/x', 'https://api.quickbase.com/v1') would give https://api.quickbase.com/apps/x (wrong)
+  // new URL('apps/x', 'https://api.quickbase.com/v1/') gives https://api.quickbase.com/v1/apps/x (correct)
+  const normalizedBase = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+  const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
+  const url = new URL(normalizedPath, normalizedBase);
+
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+
+  return url.toString();
+}
+
+/**
+ * Create request headers
+ */
+async function buildHeaders(
+  auth: AuthStrategy,
+  realmHostname: string,
+  dbid?: string,
+  customHeaders?: Record<string, string>
+): Promise<Record<string, string>> {
+  const token = await auth.getToken(dbid);
+  const authHeader = auth.getAuthorizationHeader(token);
+
+  return {
+    'Content-Type': 'application/json',
+    'QB-Realm-Hostname': realmHostname,
+    'Authorization': authHeader,
+    ...customHeaders,
+  };
+}
+
+/**
+ * Execute a single request (no retry logic)
+ */
+async function executeSingleRequest(
+  options: RequestOptions,
+  executor: RequestExecutorOptions,
+  context: RequestContext
+): Promise<Response> {
+  const { config, auth, throttle, logger } = executor;
+  const url = buildUrl(config.baseUrl, options.path, options.query);
+  const realmHostname = getRealmHostname(config.realm);
+
+  // Get auth headers (use extracted dbid from context)
+  const headers = await buildHeaders(auth, realmHostname, context.dbid, options.headers);
+
+  // Apply throttling if enabled
+  await throttle.acquire();
+
+  // Build fetch options
+  // Use credentials: 'omit' to avoid CORS issues (temp token fetch uses 'include' separately)
+  const fetchOptions: RequestInit = {
+    method: options.method,
+    headers,
+    credentials: 'omit',
+  };
+
+  if (options.body !== undefined) {
+    if (options.bodyType) {
+      headers['Content-Type'] = options.bodyType;
+      fetchOptions.body = options.body as string;
+    } else {
+      fetchOptions.body = JSON.stringify(options.body);
+    }
+  }
+
+  // Create abort controller for timeout
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), config.timeout);
+  fetchOptions.signal = controller.signal;
+
+  const startTime = Date.now();
+
+  try {
+    const response = await config.fetchApi(url, fetchOptions);
+    const duration = Date.now() - startTime;
+
+    logger.timing(options.method, options.path, duration);
+
+    return response;
+  } catch (error) {
+    if (error instanceof Error && error.name === 'AbortError') {
+      throw new TimeoutError(config.timeout);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+/**
+ * Handle response and throw appropriate errors
+ */
+async function handleResponse(
+  response: Response,
+  requestUrl: string,
+  context: RequestContext,
+  executor: RequestExecutorOptions
+): Promise<Response> {
+  const { config, logger } = executor;
+
+  if (response.ok) {
+    return response;
+  }
+
+  // Extract rate limit info for 429s
+  if (response.status === 429) {
+    const rateLimitInfo = extractRateLimitInfo(response, requestUrl, context.attempt);
+
+    logger.rateLimit({
+      url: requestUrl,
+      status: 429,
+      retryAfter: rateLimitInfo.retryAfter,
+      attempt: context.attempt,
+      rayId: rateLimitInfo.qbApiRay || rateLimitInfo.cfRay,
+    });
+
+    // Notify callback
+    if (config.onRateLimit) {
+      config.onRateLimit(rateLimitInfo);
+    }
+
+    throw new RateLimitError(rateLimitInfo);
+  }
+
+  // Parse and throw appropriate error
+  throw await parseErrorResponse(response, requestUrl);
+}
+
+/**
+ * Execute a request with full retry logic
+ */
+export async function executeRequest<T = unknown>(
+  options: RequestOptions,
+  executor: RequestExecutorOptions
+): Promise<T> {
+  const { config, auth, logger } = executor;
+  const maxAttempts = config.retry.maxAttempts;
+
+  // Check read-only mode before making any request
+  checkReadOnly(config, options.method, options.path);
+
+  // Extract dbid for temp-token auth (resolves aliases if schema provided)
+  const dbid = extractDbid(options, config);
+
+  // Transform the request body: resolve schema aliases when there is a
+  // schema, and wrap plain record values ({ '6': 'x' } -> { '6': { value: 'x' } })
+  // always. Raw (non-JSON) bodies are strings and pass through.
+  let transformedOptions = options;
+  if (options.body && typeof options.body === 'object' && !Array.isArray(options.body)) {
+    const transformedBody = transformRequest(
+      options.body as Record<string, unknown>,
+      { schema: config.schema, tableId: dbid }
+    );
+    transformedOptions = { ...options, body: transformedBody };
+  }
+
+  const context: RequestContext = {
+    methodName: `${options.method} ${options.path}`,
+    attempt: 1,
+    maxAttempts,
+    dbid,
+    startTime: Date.now(),
+  };
+
+  let lastError: Error | null = null;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    context.attempt = attempt;
+
+    try {
+      const response = await executeSingleRequest(transformedOptions, executor, context);
+      const url = buildUrl(config.baseUrl, options.path, options.query);
+
+      await handleResponse(response, url, context, executor);
+
+      // A response that isn't JSON (QBL, file content) comes back as text
+      if (options.responseType === 'text') {
+        return (await response.text()) as T;
+      }
+
+      // Parse JSON response
+      let data = await response.json();
+
+      // Transform response if schema is configured
+      if (config.schema && dbid) {
+        data = transformResponse(data, { schema: config.schema, tableId: dbid });
+      }
+
+      // Optionally transform dates
+      return transformDates(data, config.convertDates) as T;
+    } catch (error) {
+      lastError = error as Error;
+
+      // Check if error is retryable
+      if (!isRetryableError(error)) {
+        throw error;
+      }
+
+      // Don't retry if we've exhausted attempts
+      if (attempt >= maxAttempts) {
+        throw error;
+      }
+
+      // Handle auth errors specially - try to refresh token
+      if (error instanceof QuickbaseError && error.statusCode === 401) {
+        const refreshed = await auth.handleAuthError(dbid);
+        if (!refreshed) {
+          throw error;
+        }
+        logger.debug('Token refreshed, retrying request');
+        continue;
+      }
+
+      // Calculate retry delay
+      let delayMs: number;
+      let reason: string;
+
+      if (error instanceof RateLimitError) {
+        delayMs = error.retryAfter
+          ? error.retryAfter * 1000
+          : calculateBackoff(attempt, config.retry);
+        reason = 'Rate limited (429)';
+      } else if (error instanceof TimeoutError) {
+        delayMs = calculateBackoff(attempt, config.retry);
+        reason = 'Timeout';
+      } else if (error instanceof QuickbaseError && error.statusCode >= 500) {
+        delayMs = calculateBackoff(attempt, config.retry);
+        reason = `Server error (${error.statusCode})`;
+      } else {
+        delayMs = calculateBackoff(attempt, config.retry);
+        reason = 'Retryable error';
+      }
+
+      logger.retry(attempt, maxAttempts, delayMs, reason);
+      await sleep(delayMs);
+    }
+  }
+
+  throw lastError || new Error('Request failed');
+}
+
+/**
+ * Calculate exponential backoff delay with jitter
+ */
+function calculateBackoff(
+  attempt: number,
+  config: { initialDelayMs: number; maxDelayMs: number; multiplier: number }
+): number {
+  const delay = config.initialDelayMs * Math.pow(config.multiplier, attempt - 1);
+  const jitter = delay * 0.1 * (Math.random() * 2 - 1);
+  return Math.min(delay + jitter, config.maxDelayMs);
+}
+
+/**
+ * Create a request executor
+ */
+export function createRequestExecutor(options: RequestExecutorOptions) {
+  return {
+    execute: <T = unknown>(requestOptions: RequestOptions) =>
+      executeRequest<T>(requestOptions, options),
+  };
+}

package/src/client/retry.ts

@@ -0,0 +1,169 @@
+/**
+ * Retry logic with exponential backoff
+ *
+ * Handles:
+ * - HTTP 429 (Rate Limited) - uses Retry-After header
+ * - HTTP 5xx (Server Errors) - exponential backoff
+ * - Timeout errors - exponential backoff
+ */
+
+import type { RequestContext, RateLimitInfo, ResolvedConfig } from '../core/types.js';
+import type { Logger } from '../core/logger.js';
+import {
+  RateLimitError,
+  ServerError,
+  TimeoutError,
+  isRetryableError,
+} from '../core/errors.js';
+
+export interface RetryOptions {
+  maxAttempts: number;
+  initialDelayMs: number;
+  maxDelayMs: number;
+  multiplier: number;
+}
+
+/**
+ * Calculate delay for exponential backoff
+ */
+export function calculateBackoffDelay(
+  attempt: number,
+  options: RetryOptions
+): number {
+  // Exponential backoff: initialDelay * multiplier^(attempt-1)
+  const delay = options.initialDelayMs * Math.pow(options.multiplier, attempt - 1);
+
+  // Add jitter (±10%) to prevent thundering herd
+  const jitter = delay * 0.1 * (Math.random() * 2 - 1);
+
+  return Math.min(delay + jitter, options.maxDelayMs);
+}
+
+/**
+ * Get delay from Retry-After header or fall back to backoff calculation
+ */
+export function getRetryDelay(
+  response: Response | null,
+  attempt: number,
+  options: RetryOptions
+): number {
+  if (response) {
+    const retryAfter = response.headers.get('Retry-After');
+    if (retryAfter) {
+      // Retry-After can be seconds or a date string
+      const seconds = parseInt(retryAfter, 10);
+      if (!isNaN(seconds)) {
+        return seconds * 1000;
+      }
+
+      // Try parsing as a date
+      const date = Date.parse(retryAfter);
+      if (!isNaN(date)) {
+        return Math.max(0, date - Date.now());
+      }
+    }
+  }
+
+  return calculateBackoffDelay(attempt, options);
+}
+
+/**
+ * Extract rate limit info from response headers
+ */
+export function extractRateLimitInfo(
+  response: Response,
+  requestUrl: string,
+  attempt: number
+): RateLimitInfo {
+  const retryAfter = response.headers.get('Retry-After');
+
+  return {
+    timestamp: new Date(),
+    requestUrl,
+    httpStatus: response.status,
+    retryAfter: retryAfter ? parseInt(retryAfter, 10) : undefined,
+    cfRay: response.headers.get('cf-ray') || undefined,
+    tid: response.headers.get('tid') || undefined,
+    qbApiRay: response.headers.get('qb-api-ray') || undefined,
+    attempt,
+  };
+}
+
+/**
+ * Sleep for a given duration
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Determine if a response status is retryable
+ */
+export function isRetryableStatus(status: number): boolean {
+  return status === 429 || (status >= 500 && status < 600);
+}
+
+/**
+ * Execute a request with retry logic
+ */
+export async function executeWithRetry<T>(
+  fn: (context: RequestContext) => Promise<T>,
+  context: RequestContext,
+  config: ResolvedConfig,
+  logger: Logger
+): Promise<T> {
+  const options: RetryOptions = config.retry;
+  let lastError: Error | null = null;
+
+  for (let attempt = 1; attempt <= options.maxAttempts; attempt++) {
+    context.attempt = attempt;
+
+    try {
+      return await fn(context);
+    } catch (error) {
+      lastError = error as Error;
+
+      // Check if error is retryable
+      if (!isRetryableError(error)) {
+        throw error;
+      }
+
+      // Don't retry if we've exhausted attempts
+      if (attempt >= options.maxAttempts) {
+        throw error;
+      }
+
+      // Calculate retry delay
+      let delayMs: number;
+      let reason: string;
+
+      if (error instanceof RateLimitError) {
+        delayMs = error.retryAfter
+          ? error.retryAfter * 1000
+          : calculateBackoffDelay(attempt, options);
+        reason = `Rate limited (429)`;
+
+        // Notify callback
+        if (config.onRateLimit) {
+          config.onRateLimit(error.rateLimitInfo);
+        }
+      } else if (error instanceof ServerError) {
+        delayMs = calculateBackoffDelay(attempt, options);
+        reason = `Server error (${error.statusCode})`;
+      } else if (error instanceof TimeoutError) {
+        delayMs = calculateBackoffDelay(attempt, options);
+        reason = `Timeout`;
+      } else {
+        delayMs = calculateBackoffDelay(attempt, options);
+        reason = `Unknown retryable error`;
+      }
+
+      logger.retry(attempt, options.maxAttempts, delayMs, reason);
+
+      await sleep(delayMs);
+    }
+  }
+
+  // This should never be reached, but TypeScript needs it
+  throw lastError || new Error('Retry loop exited unexpectedly');
+}