quickbase-js 2.3.0 → 2.4.1

package/src/client/throttle.ts

@@ -0,0 +1,105 @@
+/**
+ * Client-side throttling (optional)
+ *
+ * Implements a sliding window rate limiter that matches QuickBase's
+ * "100 requests per 10 seconds per user token" limit.
+ *
+ * This is OPTIONAL - QuickBase handles rate limiting server-side.
+ * Enable this if you want to avoid hitting 429s proactively.
+ */
+
+export class SlidingWindowThrottle {
+  private readonly requestsPer10Seconds: number;
+  private readonly timestamps: number[] = [];
+
+  constructor(requestsPer10Seconds: number = 100) {
+    this.requestsPer10Seconds = requestsPer10Seconds;
+  }
+
+  /**
+   * Wait until a request slot is available
+   */
+  async acquire(): Promise<void> {
+    const now = Date.now();
+    const windowStart = now - 10000; // 10 second window
+
+    // Remove timestamps outside the window
+    while (this.timestamps.length > 0 && this.timestamps[0]! < windowStart) {
+      this.timestamps.shift();
+    }
+
+    // If we're at the limit, wait until the oldest request exits the window
+    if (this.timestamps.length >= this.requestsPer10Seconds) {
+      const oldestTimestamp = this.timestamps[0]!;
+      const waitTime = oldestTimestamp + 10000 - now;
+
+      if (waitTime > 0) {
+        await this.sleep(waitTime);
+        // Recurse to recheck after waiting
+        return this.acquire();
+      }
+    }
+
+    // Record this request
+    this.timestamps.push(Date.now());
+  }
+
+  /**
+   * Get the number of requests made in the current window
+   */
+  getWindowCount(): number {
+    const windowStart = Date.now() - 10000;
+    return this.timestamps.filter((t) => t >= windowStart).length;
+  }
+
+  /**
+   * Get remaining requests available in the current window
+   */
+  getRemaining(): number {
+    return Math.max(0, this.requestsPer10Seconds - this.getWindowCount());
+  }
+
+  /**
+   * Reset the throttle state
+   */
+  reset(): void {
+    this.timestamps.length = 0;
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+/**
+ * No-op throttle for when proactive throttling is disabled
+ */
+export class NoOpThrottle {
+  async acquire(): Promise<void> {
+    // No-op
+  }
+
+  getWindowCount(): number {
+    return 0;
+  }
+
+  getRemaining(): number {
+    return Infinity;
+  }
+
+  reset(): void {
+    // No-op
+  }
+}
+
+export type Throttle = SlidingWindowThrottle | NoOpThrottle;
+
+export function createThrottle(config: {
+  enabled: boolean;
+  requestsPer10Seconds: number;
+}): Throttle {
+  if (config.enabled) {
+    return new SlidingWindowThrottle(config.requestsPer10Seconds);
+  }
+  return new NoOpThrottle();
+}

package/src/core/config.ts

@@ -0,0 +1,160 @@
+/**
+ * Configuration resolution and validation
+ */
+
+import type { QuickbaseConfig, ResolvedConfig, RetryConfig } from './types.js';
+import { DEFAULT_CONFIG } from './types.js';
+import { resolveSchema } from './schema.js';
+
+/**
+ * Resolve user configuration with defaults
+ */
+export function resolveConfig(config: QuickbaseConfig): ResolvedConfig {
+  validateConfig(config);
+
+  const retry: Required<RetryConfig> = {
+    maxAttempts: config.rateLimit?.retry?.maxAttempts ?? DEFAULT_CONFIG.retry.maxAttempts,
+    initialDelayMs: config.rateLimit?.retry?.initialDelayMs ?? DEFAULT_CONFIG.retry.initialDelayMs,
+    maxDelayMs: config.rateLimit?.retry?.maxDelayMs ?? DEFAULT_CONFIG.retry.maxDelayMs,
+    multiplier: config.rateLimit?.retry?.multiplier ?? DEFAULT_CONFIG.retry.multiplier,
+  };
+
+  const proactiveThrottle = {
+    enabled: config.rateLimit?.proactiveThrottle?.enabled ?? DEFAULT_CONFIG.proactiveThrottle.enabled,
+    requestsPer10Seconds:
+      config.rateLimit?.proactiveThrottle?.requestsPer10Seconds ??
+      DEFAULT_CONFIG.proactiveThrottle.requestsPer10Seconds,
+  };
+
+  return {
+    realm: config.realm,
+    baseUrl: config.baseUrl ?? DEFAULT_CONFIG.baseUrl,
+    timeout: config.timeout ?? DEFAULT_CONFIG.timeout,
+    debug: config.debug ?? DEFAULT_CONFIG.debug,
+    fetchApi: config.fetchApi ?? globalThis.fetch.bind(globalThis),
+    auth: config.auth,
+    retry,
+    proactiveThrottle,
+    onRateLimit: config.rateLimit?.onRateLimit,
+    autoPaginate: config.autoPaginate ?? DEFAULT_CONFIG.autoPaginate,
+    convertDates: config.convertDates ?? DEFAULT_CONFIG.convertDates,
+    schema: resolveSchema(config.schema),
+    readOnly: config.readOnly ?? false,
+    appToken: config.appToken,
+  };
+}
+
+/**
+ * Validate configuration and throw if invalid
+ */
+function validateConfig(config: QuickbaseConfig): void {
+  if (!config.realm) {
+    throw new Error('QuickBase realm is required');
+  }
+
+  if (typeof config.realm !== 'string') {
+    throw new Error('QuickBase realm must be a string');
+  }
+
+  // Remove .quickbase.com suffix if provided
+  if (config.realm.includes('.')) {
+    throw new Error(
+      'Realm should be just the subdomain (e.g., "mycompany" not "mycompany.quickbase.com")'
+    );
+  }
+
+  if (!config.auth) {
+    throw new Error('Authentication configuration is required');
+  }
+
+  validateAuthConfig(config.auth);
+
+  if (config.timeout !== undefined) {
+    if (typeof config.timeout !== 'number' || config.timeout <= 0) {
+      throw new Error('Timeout must be a positive number');
+    }
+  }
+
+  if (config.rateLimit?.retry) {
+    validateRetryConfig(config.rateLimit.retry);
+  }
+
+  if (config.rateLimit?.proactiveThrottle) {
+    validateThrottleConfig(config.rateLimit.proactiveThrottle);
+  }
+}
+
+function validateAuthConfig(auth: QuickbaseConfig['auth']): void {
+  switch (auth.type) {
+    case 'user-token':
+      if (!auth.userToken) {
+        throw new Error('User token is required for user-token auth');
+      }
+      break;
+
+    case 'temp-token':
+      // userToken is optional for temp-token auth
+      // When running in Code Pages, the browser session is used
+      break;
+
+    case 'sso':
+      if (!auth.samlToken) {
+        throw new Error('SAML token is required for SSO auth');
+      }
+      break;
+
+    // XML-API-TICKET: Remove this case if XML API is discontinued
+    case 'ticket':
+      if (!auth.username) {
+        throw new Error('Username is required for ticket auth');
+      }
+      if (!auth.password) {
+        throw new Error('Password is required for ticket auth');
+      }
+      break;
+
+    default:
+      throw new Error(`Unknown auth type: ${(auth as { type: string }).type}`);
+  }
+}
+
+function validateRetryConfig(retry: RetryConfig): void {
+  if (retry.maxAttempts !== undefined) {
+    if (typeof retry.maxAttempts !== 'number' || retry.maxAttempts < 0) {
+      throw new Error('maxAttempts must be a non-negative number');
+    }
+  }
+
+  if (retry.initialDelayMs !== undefined) {
+    if (typeof retry.initialDelayMs !== 'number' || retry.initialDelayMs < 0) {
+      throw new Error('initialDelayMs must be a non-negative number');
+    }
+  }
+
+  if (retry.maxDelayMs !== undefined) {
+    if (typeof retry.maxDelayMs !== 'number' || retry.maxDelayMs < 0) {
+      throw new Error('maxDelayMs must be a non-negative number');
+    }
+  }
+
+  if (retry.multiplier !== undefined) {
+    if (typeof retry.multiplier !== 'number' || retry.multiplier < 1) {
+      throw new Error('multiplier must be a number >= 1');
+    }
+  }
+}
+
+function validateThrottleConfig(throttle: { enabled?: boolean; requestsPer10Seconds?: number }): void {
+  if (throttle.requestsPer10Seconds !== undefined) {
+    if (typeof throttle.requestsPer10Seconds !== 'number' || throttle.requestsPer10Seconds <= 0) {
+      throw new Error('requestsPer10Seconds must be a positive number');
+    }
+  }
+}
+
+/**
+ * Build the realm hostname from the realm name
+ */
+export function getRealmHostname(realm: string): string {
+  return `${realm}.quickbase.com`;
+}

package/src/core/dates.ts

@@ -0,0 +1,63 @@
+/**
+ * Date transformation utilities
+ *
+ * Converts ISO 8601 date strings in API responses to JavaScript Date objects.
+ */
+
+/**
+ * ISO 8601 date pattern
+ * Matches: 2024-01-15, 2024-01-15T10:30:00, 2024-01-15T10:30:00.000Z, etc.
+ */
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{1,3})?(Z|[+-]\d{2}:?\d{2})?)?$/;
+
+/**
+ * Check if a string looks like an ISO 8601 date
+ */
+export function isIsoDateString(value: string): boolean {
+  return ISO_DATE_PATTERN.test(value);
+}
+
+/**
+ * Recursively transform ISO date strings to Date objects in an object
+ *
+ * @param obj - The object to transform
+ * @param enabled - Whether to perform conversion (pass false to skip)
+ * @returns A new object with date strings converted to Date objects
+ */
+export function transformDates<T>(obj: T, enabled: boolean): T {
+  if (!enabled || obj === null || obj === undefined) {
+    return obj;
+  }
+
+  if (typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => transformDates(item, enabled)) as T;
+  }
+
+  if (obj instanceof Date) {
+    return obj;
+  }
+
+  const result: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (typeof value === 'string' && isIsoDateString(value)) {
+      // Convert ISO date string to Date object
+      result[key] = new Date(value);
+    } else if (value instanceof Date) {
+      // Keep existing Date objects as-is
+      result[key] = value;
+    } else if (typeof value === 'object' && value !== null) {
+      // Recursively transform nested objects
+      result[key] = transformDates(value, enabled);
+    } else {
+      // Keep other values as-is
+      result[key] = value;
+    }
+  }
+
+  return result as T;
+}

package/src/core/errors.ts

@@ -0,0 +1,349 @@
+/**
+ * Custom error types for the QuickBase SDK
+ */
+
+import type { RateLimitInfo } from './types.js';
+
+/**
+ * Base error class for all QuickBase SDK errors
+ */
+export class QuickbaseError extends Error {
+  readonly statusCode: number;
+  readonly description?: string;
+  readonly rayId?: string;
+
+  constructor(
+    message: string,
+    statusCode: number,
+    options?: {
+      description?: string;
+      rayId?: string;
+      cause?: Error;
+    }
+  ) {
+    super(message, { cause: options?.cause });
+    this.name = 'QuickbaseError';
+    this.statusCode = statusCode;
+    this.description = options?.description;
+    this.rayId = options?.rayId;
+
+    // Maintains proper stack trace in V8 environments
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, QuickbaseError);
+    }
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      statusCode: this.statusCode,
+      description: this.description,
+      rayId: this.rayId,
+    };
+  }
+}
+
+/**
+ * Error thrown when rate limited (HTTP 429)
+ */
+export class RateLimitError extends QuickbaseError {
+  readonly retryAfter?: number;
+  readonly rateLimitInfo: RateLimitInfo;
+
+  constructor(rateLimitInfo: RateLimitInfo, message?: string) {
+    super(
+      message || `Rate limited. Retry after ${rateLimitInfo.retryAfter ?? 'unknown'} seconds`,
+      429,
+      { rayId: rateLimitInfo.qbApiRay || rateLimitInfo.cfRay }
+    );
+    this.name = 'RateLimitError';
+    this.retryAfter = rateLimitInfo.retryAfter;
+    this.rateLimitInfo = rateLimitInfo;
+  }
+
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      retryAfter: this.retryAfter,
+      rateLimitInfo: this.rateLimitInfo,
+    };
+  }
+}
+
+/**
+ * Error thrown when authentication fails (HTTP 401)
+ */
+export class AuthenticationError extends QuickbaseError {
+  constructor(message: string, options?: { rayId?: string; cause?: Error }) {
+    super(message, 401, options);
+    this.name = 'AuthenticationError';
+  }
+}
+
+/**
+ * Error thrown when authorization fails (HTTP 403)
+ */
+export class AuthorizationError extends QuickbaseError {
+  constructor(message: string, options?: { rayId?: string; cause?: Error }) {
+    super(message, 403, options);
+    this.name = 'AuthorizationError';
+  }
+}
+
+/**
+ * Error thrown when a resource is not found (HTTP 404)
+ */
+export class NotFoundError extends QuickbaseError {
+  constructor(message: string, options?: { rayId?: string; cause?: Error }) {
+    super(message, 404, options);
+    this.name = 'NotFoundError';
+  }
+}
+
+/**
+ * Error thrown for bad requests (HTTP 400)
+ */
+export class ValidationError extends QuickbaseError {
+  readonly errors?: Array<{ field?: string; message: string }>;
+
+  constructor(
+    message: string,
+    options?: {
+      description?: string;
+      rayId?: string;
+      errors?: Array<{ field?: string; message: string }>;
+      cause?: Error;
+    }
+  ) {
+    super(message, 400, options);
+    this.name = 'ValidationError';
+    this.errors = options?.errors;
+  }
+
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      errors: this.errors,
+    };
+  }
+}
+
+/**
+ * Error thrown when request times out
+ */
+export class TimeoutError extends QuickbaseError {
+  readonly timeoutMs: number;
+
+  constructor(timeoutMs: number, options?: { rayId?: string; cause?: Error }) {
+    super(`Request timed out after ${timeoutMs}ms`, 0, options);
+    this.name = 'TimeoutError';
+    this.timeoutMs = timeoutMs;
+  }
+
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      timeoutMs: this.timeoutMs,
+    };
+  }
+}
+
+/**
+ * Error thrown for server errors (HTTP 5xx)
+ */
+export class ServerError extends QuickbaseError {
+  constructor(
+    statusCode: number,
+    message: string,
+    options?: { description?: string; rayId?: string; cause?: Error }
+  ) {
+    super(message, statusCode, options);
+    this.name = 'ServerError';
+  }
+}
+
+/**
+ * Error thrown when an authentication ticket is invalid or expired.
+ * Specifically for ticket-based authentication (XML API).
+ */
+export class QuickbaseTicketError extends QuickbaseError {
+  readonly code: number;
+
+  constructor(message: string, code: number, options?: { description?: string; action?: string; cause?: Error }) {
+    super(message, 401, options);
+    this.name = 'QuickbaseTicketError';
+    this.code = code;
+  }
+
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      code: this.code,
+    };
+  }
+}
+
+/**
+ * Error thrown when an application token is missing or invalid.
+ * Specifically for apps that require app tokens (XML API).
+ */
+export class QuickbaseAppTokenError extends QuickbaseError {
+  readonly code: number;
+
+  constructor(message: string, code: number, options?: { description?: string; action?: string; cause?: Error }) {
+    super(message, 403, options);
+    this.name = 'QuickbaseAppTokenError';
+    this.code = code;
+  }
+
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      code: this.code,
+    };
+  }
+}
+
+/**
+ * Error thrown by the legacy QuickBase XML API.
+ * Wraps XML-specific error codes and messages.
+ */
+export class QuickbaseXmlError extends QuickbaseError {
+  readonly code: number;
+  readonly text: string;
+  readonly action?: string;
+
+  constructor(code: number, text: string, options?: { description?: string; action?: string; cause?: Error }) {
+    const message = options?.description
+      ? `XML API error ${code}: ${text} (${options.description})`
+      : `XML API error ${code}: ${text}`;
+    
+    // Most XML errors return HTTP 200, so we use 0 or a mapped status if known
+    super(message, 0, { rayId: undefined, description: options?.description, cause: options?.cause });
+    this.name = 'QuickbaseXmlError';
+    this.code = code;
+    this.text = text;
+    this.action = options?.action;
+  }
+
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      code: this.code,
+      text: this.text,
+      action: this.action,
+    };
+  }
+}
+
+/**
+ * Parse an error response from the QuickBase API
+ */
+export async function parseErrorResponse(
+  response: Response,
+  requestUrl: string
+): Promise<QuickbaseError> {
+  const rayId = response.headers.get('qb-api-ray') || response.headers.get('cf-ray') || undefined;
+
+  let body: { message?: string; description?: string; errors?: unknown[] } | null = null;
+  try {
+    body = await response.json() as { message?: string; description?: string; errors?: unknown[] };
+  } catch {
+    // Response body is not JSON
+  }
+
+  const message = body?.message || response.statusText || 'Unknown error';
+  const description = body?.description;
+
+  switch (response.status) {
+    case 400:
+      return new ValidationError(message, {
+        description,
+        rayId,
+        errors: body?.errors as Array<{ field?: string; message: string }>,
+      });
+
+    case 401:
+      return new AuthenticationError(message, { rayId });
+
+    case 403:
+      return new AuthorizationError(message, { rayId });
+
+    case 404:
+      return new NotFoundError(message, { rayId });
+
+    case 429: {
+      const retryAfter = response.headers.get('Retry-After');
+      const rateLimitInfo: RateLimitInfo = {
+        timestamp: new Date(),
+        requestUrl,
+        httpStatus: 429,
+        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: 1, // Will be updated by caller
+      };
+      return new RateLimitError(rateLimitInfo, message);
+    }
+
+    default:
+      if (response.status >= 500) {
+        return new ServerError(response.status, message, { description, rayId });
+      }
+      return new QuickbaseError(message, response.status, { description, rayId });
+  }
+}
+
+/**
+ * Check if an error is retryable
+ */
+export function isRetryableError(error: unknown): boolean {
+  if (error instanceof RateLimitError) {
+    return true;
+  }
+  if (error instanceof ServerError) {
+    return true;
+  }
+  if (error instanceof TimeoutError) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Error thrown when a write operation is attempted in read-only mode.
+ * Provides defense-in-depth for both JSON API and XML API requests.
+ */
+export class ReadOnlyError extends Error {
+  readonly method: string;
+  readonly path: string;
+  readonly action?: string; // For XML API actions
+
+  constructor(method: string, path: string, action?: string) {
+    const msg = action
+      ? `Read-only mode: write operation blocked (XML action: ${action})`
+      : `Read-only mode: write operation blocked (${method} ${path})`;
+    super(msg);
+    this.name = 'ReadOnlyError';
+    this.method = method;
+    this.path = path;
+    this.action = action;
+
+    // Maintains proper stack trace in V8 environments
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ReadOnlyError);
+    }
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      method: this.method,
+      path: this.path,
+      action: this.action,
+    };
+  }
+}