quickbase-js 2.3.0 → 2.4.1

package/src/core/index.ts

@@ -0,0 +1,50 @@
+/**
+ * Core module exports
+ */
+
+export type {
+  QuickbaseConfig,
+  AuthConfig,
+  UserTokenAuthConfig,
+  TempTokenAuthConfig,
+  SsoTokenAuthConfig,
+  TicketAuthConfig, // XML-API-TICKET: Remove if XML API discontinued
+  RateLimitConfig,
+  RetryConfig,
+  RequestContext,
+  RateLimitInfo,
+  PaginationMetadata,
+  PaginatedResponse,
+  FieldInfo,
+  ResolvedConfig,
+  // Schema types
+  Schema,
+  TableSchema,
+  FieldSchema,
+  ResolvedSchema,
+} from './types.js';
+
+export { DEFAULT_CONFIG } from './types.js';
+
+export {
+  QuickbaseError,
+  RateLimitError,
+  AuthenticationError,
+  AuthorizationError,
+  NotFoundError,
+  ValidationError,
+  TimeoutError,
+  ServerError,
+  QuickbaseTicketError,
+  QuickbaseAppTokenError,
+  QuickbaseXmlError,
+  ReadOnlyError,
+  parseErrorResponse,
+  isRetryableError,
+} from './errors.js';
+
+export { Logger, createLogger } from './logger.js';
+
+export { resolveConfig, getRealmHostname } from './config.js';
+
+export { transformDates, isIsoDateString } from './dates.js';

package/src/core/logger.ts

@@ -0,0 +1,113 @@
+/**
+ * Logger utility that respects the debug configuration
+ */
+
+export class Logger {
+  private readonly enabled: boolean;
+  private readonly prefix: string;
+
+  constructor(enabled: boolean = false, prefix: string = 'quickbase-js') {
+    this.enabled = enabled;
+    this.prefix = prefix;
+  }
+
+  private formatMessage(level: string, message: string): string {
+    const timestamp = new Date().toISOString();
+    return `[${timestamp}] [${this.prefix}] [${level}] ${message}`;
+  }
+
+  debug(message: string, data?: unknown): void {
+    if (this.enabled) {
+      if (data !== undefined) {
+        console.log(this.formatMessage('DEBUG', message), data);
+      } else {
+        console.log(this.formatMessage('DEBUG', message));
+      }
+    }
+  }
+
+  info(message: string, data?: unknown): void {
+    if (this.enabled) {
+      if (data !== undefined) {
+        console.info(this.formatMessage('INFO', message), data);
+      } else {
+        console.info(this.formatMessage('INFO', message));
+      }
+    }
+  }
+
+  warn(message: string, data?: unknown): void {
+    // Warnings are always logged, regardless of debug setting
+    if (data !== undefined) {
+      console.warn(this.formatMessage('WARN', message), data);
+    } else {
+      console.warn(this.formatMessage('WARN', message));
+    }
+  }
+
+  error(message: string, error?: unknown): void {
+    // Errors are always logged, regardless of debug setting
+    if (error !== undefined) {
+      console.error(this.formatMessage('ERROR', message), error);
+    } else {
+      console.error(this.formatMessage('ERROR', message));
+    }
+  }
+
+  /**
+   * Log rate limit information
+   */
+  rateLimit(info: {
+    url: string;
+    status: number;
+    retryAfter?: number;
+    attempt: number;
+    rayId?: string;
+  }): void {
+    if (this.enabled) {
+      this.debug(
+        `Rate limited (attempt ${info.attempt}): ${info.url} - ` +
+          `Status ${info.status}, Retry-After: ${info.retryAfter ?? 'not specified'}s` +
+          (info.rayId ? `, Ray: ${info.rayId}` : '')
+      );
+    }
+  }
+
+  /**
+   * Log request timing
+   */
+  timing(method: string, url: string, durationMs: number): void {
+    if (this.enabled) {
+      this.debug(`${method} ${url} completed in ${durationMs}ms`);
+    }
+  }
+
+  /**
+   * Log retry attempt
+   */
+  retry(attempt: number, maxAttempts: number, delayMs: number, reason: string): void {
+    if (this.enabled) {
+      this.debug(
+        `Retry ${attempt}/${maxAttempts} in ${delayMs}ms: ${reason}`
+      );
+    }
+  }
+
+  /**
+   * Log token operations (without exposing the actual token)
+   */
+  token(operation: 'fetch' | 'cache-hit' | 'cache-miss' | 'refresh' | 'expire', dbid?: string): void {
+    if (this.enabled) {
+      const target = dbid ? ` for dbid: ${dbid}` : '';
+      this.debug(`Token ${operation}${target}`);
+    }
+  }
+}
+
+/**
+ * Create a no-op logger for when logging is disabled
+ * This avoids conditional checks at every log call
+ */
+export function createLogger(enabled: boolean): Logger {
+  return new Logger(enabled);
+}

package/src/core/schema.ts

@@ -0,0 +1,213 @@
+/**
+ * Schema resolution and lookup utilities
+ */
+
+import type { Schema, ResolvedSchema } from './types.js';
+
+/**
+ * Error thrown when an unknown table or field alias is used
+ */
+export class SchemaError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SchemaError';
+  }
+}
+
+/**
+ * Resolve a schema definition into lookup maps for efficient alias resolution
+ */
+export function resolveSchema(schema?: Schema): ResolvedSchema | undefined {
+  if (!schema) return undefined;
+
+  const tableAliasToId = new Map<string, string>();
+  const tableIdToAlias = new Map<string, string>();
+  const fieldAliasToId = new Map<string, Map<string, number>>();
+  const fieldIdToAlias = new Map<string, Map<number, string>>();
+
+  for (const [tableAlias, tableSchema] of Object.entries(schema.tables)) {
+    const tableId = tableSchema.id;
+
+    // Table mappings
+    tableAliasToId.set(tableAlias, tableId);
+    tableIdToAlias.set(tableId, tableAlias);
+
+    // Field mappings for this table
+    const aliasToId = new Map<string, number>();
+    const idToAlias = new Map<number, string>();
+
+    for (const [fieldAlias, fieldId] of Object.entries(tableSchema.fields)) {
+      aliasToId.set(fieldAlias, fieldId);
+      idToAlias.set(fieldId, fieldAlias);
+    }
+
+    fieldAliasToId.set(tableId, aliasToId);
+    fieldIdToAlias.set(tableId, idToAlias);
+  }
+
+  return {
+    original: schema,
+    tableAliasToId,
+    tableIdToAlias,
+    fieldAliasToId,
+    fieldIdToAlias,
+  };
+}
+
+/**
+ * Resolve a table alias to its ID.
+ * If the input is already a table ID, returns it unchanged.
+ * Throws SchemaError if alias is not found.
+ */
+export function resolveTableAlias(
+  schema: ResolvedSchema | undefined,
+  tableRef: string
+): string {
+  if (!schema) return tableRef;
+
+  // Check if it's an alias
+  const tableId = schema.tableAliasToId.get(tableRef);
+  if (tableId) return tableId;
+
+  // Check if it's already a table ID
+  if (schema.tableIdToAlias.has(tableRef)) return tableRef;
+
+  // Unknown alias - throw helpful error
+  const availableAliases = Array.from(schema.tableAliasToId.keys());
+  const suggestion = findSimilar(tableRef, availableAliases);
+  const suggestionText = suggestion ? ` Did you mean '${suggestion}'?` : '';
+  const availableText =
+    availableAliases.length > 0
+      ? ` Available: ${availableAliases.join(', ')}`
+      : '';
+
+  throw new SchemaError(
+    `Unknown table alias '${tableRef}'.${suggestionText}${availableText}`
+  );
+}
+
+/**
+ * Resolve a field alias to its ID for a given table.
+ * If the input is already a field ID (number), returns it unchanged.
+ * Throws SchemaError if alias is not found.
+ */
+export function resolveFieldAlias(
+  schema: ResolvedSchema | undefined,
+  tableId: string,
+  fieldRef: string | number
+): number {
+  // If it's already a number, return as-is
+  if (typeof fieldRef === 'number') return fieldRef;
+
+  // If no schema, try to parse as number or return as-is
+  if (!schema) {
+    const num = parseInt(fieldRef, 10);
+    if (!isNaN(num)) return num;
+    // Can't resolve without schema - pass through and let API handle it
+    return fieldRef as unknown as number;
+  }
+
+  // Look up the alias
+  const fieldMap = schema.fieldAliasToId.get(tableId);
+  if (fieldMap) {
+    const fieldId = fieldMap.get(fieldRef);
+    if (fieldId !== undefined) return fieldId;
+  }
+
+  // Check if it's a numeric string (raw field ID)
+  const num = parseInt(fieldRef, 10);
+  if (!isNaN(num)) return num;
+
+  // Unknown alias - throw helpful error
+  const availableAliases = fieldMap ? Array.from(fieldMap.keys()) : [];
+  const suggestion = findSimilar(fieldRef, availableAliases);
+  const suggestionText = suggestion ? ` Did you mean '${suggestion}'?` : '';
+
+  // Get table alias for better error message
+  const tableAlias = schema.tableIdToAlias.get(tableId) || tableId;
+
+  throw new SchemaError(
+    `Unknown field alias '${fieldRef}' in table '${tableAlias}'.${suggestionText}`
+  );
+}
+
+/**
+ * Get the alias for a field ID, if defined in schema.
+ * Returns undefined if no alias is defined.
+ */
+export function getFieldAlias(
+  schema: ResolvedSchema | undefined,
+  tableId: string,
+  fieldId: number
+): string | undefined {
+  if (!schema) return undefined;
+
+  const fieldMap = schema.fieldIdToAlias.get(tableId);
+  return fieldMap?.get(fieldId);
+}
+
+/**
+ * Get the alias for a table ID, if defined in schema.
+ * Returns undefined if no alias is defined.
+ */
+export function getTableAlias(
+  schema: ResolvedSchema | undefined,
+  tableId: string
+): string | undefined {
+  if (!schema) return undefined;
+  return schema.tableIdToAlias.get(tableId);
+}
+
+/**
+ * Find a similar string from a list (for "did you mean" suggestions)
+ * Uses simple Levenshtein distance
+ */
+function findSimilar(
+  input: string,
+  candidates: string[],
+  maxDistance = 3
+): string | undefined {
+  const inputLower = input.toLowerCase();
+  let bestMatch: string | undefined;
+  let bestDistance = maxDistance + 1;
+
+  for (const candidate of candidates) {
+    const distance = levenshteinDistance(inputLower, candidate.toLowerCase());
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      bestMatch = candidate;
+    }
+  }
+
+  return bestDistance <= maxDistance ? bestMatch : undefined;
+}
+
+/**
+ * Calculate Levenshtein distance between two strings
+ */
+function levenshteinDistance(a: string, b: string): number {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  // Create matrix with proper initialization
+  const matrix: number[][] = Array.from({ length: b.length + 1 }, (_, i) =>
+    Array.from({ length: a.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0))
+  );
+
+  // Fill in the rest
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      if (b.charAt(i - 1) === a.charAt(j - 1)) {
+        matrix[i]![j] = matrix[i - 1]![j - 1]!;
+      } else {
+        matrix[i]![j] = Math.min(
+          matrix[i - 1]![j - 1]! + 1, // substitution
+          matrix[i]![j - 1]! + 1, // insertion
+          matrix[i - 1]![j]! + 1 // deletion
+        );
+      }
+    }
+  }
+
+  return matrix[b.length]![a.length]!;
+}

package/src/core/transform.ts

@@ -0,0 +1,295 @@
+/**
+ * Request and response transformation utilities for schema aliases
+ */
+
+import type { ResolvedSchema } from './types.js';
+import {
+  resolveTableAlias,
+  resolveFieldAlias,
+  getFieldAlias,
+} from './schema.js';
+
+// =============================================================================
+// Request Transformation
+// =============================================================================
+
+/**
+ * Context for request transformation
+ */
+export interface RequestTransformContext {
+  schema?: ResolvedSchema;
+  /** The resolved table ID (after alias resolution) */
+  tableId?: string;
+}
+
+/**
+ * Transform a request body, resolving table and field aliases to IDs.
+ * Handles: from, to, select, sortBy, groupBy, where, data
+ */
+export function transformRequest<T extends Record<string, unknown>>(
+  body: T,
+  ctx: RequestTransformContext
+): T {
+  // Work with a plain object to avoid TypeScript index signature issues
+  const result: Record<string, unknown> = { ...body };
+  let tableId = ctx.tableId;
+
+  // Schema-dependent transforms (alias resolution)
+  if (ctx.schema) {
+    // Resolve table references (from, to)
+    if ('from' in result && typeof result.from === 'string') {
+      tableId = resolveTableAlias(ctx.schema, result.from);
+      result.from = tableId;
+    }
+    if ('to' in result && typeof result.to === 'string') {
+      tableId = resolveTableAlias(ctx.schema, result.to);
+      result.to = tableId;
+    }
+
+    // Resolve field aliases (requires tableId)
+    if (tableId) {
+      // Resolve select array
+      if ('select' in result && Array.isArray(result.select)) {
+        result.select = (result.select as (string | number)[]).map((field) =>
+          resolveFieldAlias(ctx.schema!, tableId!, field)
+        );
+      }
+
+      // Resolve sortBy array
+      if ('sortBy' in result && Array.isArray(result.sortBy)) {
+        result.sortBy = (result.sortBy as Record<string, unknown>[]).map((sort) => ({
+          ...sort,
+          fieldId: resolveFieldAlias(ctx.schema!, tableId!, sort.fieldId as string | number),
+        }));
+      }
+
+      // Resolve groupBy array
+      if ('groupBy' in result && Array.isArray(result.groupBy)) {
+        result.groupBy = (result.groupBy as Record<string, unknown>[]).map((group) => ({
+          ...group,
+          fieldId: resolveFieldAlias(ctx.schema!, tableId!, group.fieldId as string | number),
+        }));
+      }
+
+      // Resolve where clause (string replacement)
+      if ('where' in result && typeof result.where === 'string') {
+        result.where = transformWhereClause(result.where, ctx.schema, tableId);
+      }
+    }
+  }
+
+  // Auto-wrap data values (always runs, no schema required)
+  if ('data' in result && Array.isArray(result.data)) {
+    result.data = (result.data as Record<string, unknown>[]).map((record) =>
+      wrapRecordValues(record, ctx.schema, tableId)
+    );
+  }
+
+  return result as T;
+}
+
+/**
+ * Wrap record values and optionally resolve field aliases.
+ * Always wraps plain values in { value: X } format.
+ * Resolves field aliases to IDs if schema is provided.
+ */
+function wrapRecordValues(
+  record: Record<string, unknown>,
+  schema: ResolvedSchema | undefined,
+  tableId: string | undefined
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(record)) {
+    // Resolve field alias if schema is available
+    let outputKey = key;
+    if (schema && tableId) {
+      try {
+        const fieldId = resolveFieldAlias(schema, tableId, key);
+        outputKey = String(fieldId);
+      } catch {
+        // Not an alias, keep original key
+      }
+    }
+
+    // Always auto-wrap values
+    result[outputKey] = wrapFieldValue(value);
+  }
+
+  return result;
+}
+
+/**
+ * Transform a where clause, replacing field aliases with IDs.
+ * QuickBase where syntax: {fieldId.operator.value}
+ * Example: {'status'.EX.'Active'} -> {7.EX.'Active'}
+ */
+function transformWhereClause(
+  where: string,
+  schema: ResolvedSchema,
+  tableId: string
+): string {
+  // Match patterns like {'fieldAlias' or {fieldAlias. at the start of conditions
+  // The pattern captures the field reference between { and .
+  return where.replace(/\{['"]?([^.'"\}]+)['"]?\./g, (match, fieldRef: string) => {
+    try {
+      const fieldId = resolveFieldAlias(schema, tableId, fieldRef);
+      return `{${fieldId}.`;
+    } catch {
+      // If alias not found, keep original (might be a raw ID)
+      return match;
+    }
+  });
+}
+
+/**
+ * Wrap a value in QuickBase's { value: X } format if not already wrapped.
+ * Handles plain values, arrays, and already-wrapped values.
+ */
+function wrapFieldValue(value: unknown): { value: unknown } {
+  // Already wrapped - return as-is
+  if (isWrappedValue(value)) {
+    return value as { value: unknown };
+  }
+
+  // Wrap plain value
+  return { value };
+}
+
+/**
+ * Check if a value is already wrapped in { value: X } format.
+ */
+function isWrappedValue(value: unknown): boolean {
+  if (value === null || value === undefined) return false;
+  if (typeof value !== 'object' || Array.isArray(value)) return false;
+
+  const obj = value as Record<string, unknown>;
+  return 'value' in obj;
+}
+
+// =============================================================================
+// Response Transformation
+// =============================================================================
+
+/**
+ * Context for response transformation
+ */
+export interface ResponseTransformContext {
+  schema?: ResolvedSchema;
+  /** The table ID for field alias lookups */
+  tableId?: string;
+}
+
+/**
+ * Transform a response, converting field IDs to aliases and unwrapping values.
+ * Handles nested data arrays (for runQuery, upsert responses).
+ */
+export function transformResponse<T>(
+  response: T,
+  ctx: ResponseTransformContext
+): T {
+  if (!response || typeof response !== 'object') return response;
+
+  const result = { ...response } as Record<string, unknown>;
+
+  // Handle data array (runQuery, upsert responses)
+  if ('data' in result && Array.isArray(result.data) && ctx.tableId) {
+    result.data = result.data.map((record) =>
+      transformRecordForResponse(
+        record as Record<string, unknown>,
+        ctx.schema,
+        ctx.tableId!
+      )
+    );
+  }
+
+  return result as T;
+}
+
+/**
+ * Transform a single record from the response.
+ * - Converts field ID keys to aliases (if schema defined)
+ * - Unwraps { value: X } to just X
+ * - Unknown fields keep their numeric key but still get unwrapped
+ */
+function transformRecordForResponse(
+  record: Record<string, unknown>,
+  schema: ResolvedSchema | undefined,
+  tableId: string
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(record)) {
+    // Determine the output key (alias or original)
+    let outputKey = key;
+    const fieldId = parseInt(key, 10);
+
+    if (!isNaN(fieldId) && schema) {
+      const alias = getFieldAlias(schema, tableId, fieldId);
+      if (alias) {
+        outputKey = alias;
+      }
+    }
+
+    // Unwrap { value: X } -> X
+    const unwrappedValue = unwrapFieldValue(value);
+    result[outputKey] = unwrappedValue;
+  }
+
+  return result;
+}
+
+/**
+ * Unwrap a field value from QuickBase's { value: X } format.
+ * Also handles arrays of values.
+ */
+function unwrapFieldValue(value: unknown): unknown {
+  if (value === null || value === undefined) return value;
+
+  if (typeof value === 'object' && !Array.isArray(value)) {
+    const obj = value as Record<string, unknown>;
+    // Check if it's a { value: X } wrapper
+    if ('value' in obj && Object.keys(obj).length === 1) {
+      // Recursively unwrap in case value is an array of wrapped values
+      return unwrapFieldValue(obj.value);
+    }
+    // Check if it's a { value: X, ...metadata } wrapper (preserve just value)
+    if ('value' in obj) {
+      return unwrapFieldValue(obj.value);
+    }
+  }
+
+  // Handle array of { value: X } objects
+  if (Array.isArray(value)) {
+    return value.map(unwrapFieldValue);
+  }
+
+  return value;
+}
+
+// =============================================================================
+// Table ID Extraction
+// =============================================================================
+
+/**
+ * Extract the table ID from a request body.
+ * Looks for 'from' or 'to' fields and resolves any aliases.
+ */
+export function extractTableIdFromRequest(
+  body: Record<string, unknown> | undefined,
+  schema?: ResolvedSchema
+): string | undefined {
+  if (!body) return undefined;
+
+  // Check 'from' (runQuery, deleteRecords)
+  if ('from' in body && typeof body.from === 'string') {
+    return schema ? resolveTableAlias(schema, body.from) : body.from;
+  }
+
+  // Check 'to' (upsert)
+  if ('to' in body && typeof body.to === 'string') {
+    return schema ? resolveTableAlias(schema, body.to) : body.to;
+  }
+
+  return undefined;
+}