quickbase-js 2.3.0 → 2.4.1

package/src/index.ts

@@ -0,0 +1,259 @@
+/**
+ * QuickBase SDK v2
+ *
+ * A TypeScript/JavaScript client for the QuickBase JSON RESTful API.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from 'quickbase-js';
+ *
+ * const client = createClient({
+ *   realm: 'mycompany',
+ *   auth: {
+ *     type: 'user-token',
+ *     userToken: 'your-user-token',
+ *   },
+ * });
+ *
+ * const app = await client.getApp({ appId: 'bpqe82s1' });
+ * console.log(app.name);
+ * ```
+ */
+
+// Core exports
+export type {
+  QuickbaseConfig,
+  AuthConfig,
+  UserTokenAuthConfig,
+  TempTokenAuthConfig,
+  SsoTokenAuthConfig,
+  TicketAuthConfig, // XML-API-TICKET: Remove if XML API discontinued
+  RateLimitConfig,
+  RetryConfig,
+  RateLimitInfo,
+  PaginationMetadata,
+  PaginatedResponse,
+  FieldInfo,
+  // Schema types
+  Schema,
+  TableSchema,
+  FieldSchema,
+  ResolvedSchema,
+} from './core/index.js';
+
+// Schema utilities
+export { SchemaError } from './core/schema.js';
+
+export {
+  QuickbaseError,
+  RateLimitError,
+  AuthenticationError,
+  AuthorizationError,
+  NotFoundError,
+  ValidationError,
+  TimeoutError,
+  ServerError,
+  QuickbaseTicketError,
+  QuickbaseAppTokenError,
+  QuickbaseXmlError,
+  ReadOnlyError,
+} from './core/index.js';
+
+// Auth exports (for advanced usage)
+export type { AuthStrategy } from './auth/index.js';
+export {
+  UserTokenStrategy,
+  TempTokenStrategy,
+  SsoTokenStrategy,
+  TicketStrategy, // XML-API-TICKET: Remove if XML API discontinued
+  createAuthStrategy,
+} from './auth/index.js';
+import type { AuthStrategy } from './auth/index.js';
+
+// Client exports
+export type { RequestOptions } from './client/index.js';
+export { SlidingWindowThrottle, NoOpThrottle } from './client/index.js';
+
+// Generated types and client
+export type { QuickbaseAPI } from './generated/types.js';
+export * from './generated/types.js';
+export { createApiMethods } from './generated/client.js';
+
+// Main client factory
+import type { QuickbaseConfig, ResolvedConfig } from './core/types.js';
+import { resolveConfig } from './core/config.js';
+import { createLogger } from './core/logger.js';
+import { createAuthStrategy } from './auth/index.js';
+import { createThrottle } from './client/throttle.js';
+import { createRequestExecutor } from './client/request.js';
+import type { QuickbaseAPI } from './generated/types.js';
+import { createApiMethods } from './generated/client.js';
+
+/**
+ * QuickBase client with typed API methods
+ */
+export interface QuickbaseClient extends QuickbaseAPI {
+  /** Execute a raw request (for custom API calls) */
+  request: <T = unknown>(options: {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+    dbid?: string;
+  }) => Promise<T>;
+
+  /** Get the resolved configuration */
+  getConfig: () => ResolvedConfig;
+
+  /**
+   * Get the auth strategy for advanced usage (e.g., XML API client).
+   * XML-API: Used by createXmlClient() to access authentication.
+   */
+  getAuthStrategy: () => AuthStrategy;
+}
+
+/**
+ * Create a QuickBase client
+ *
+ * @example User token authentication
+ * ```typescript
+ * const client = createClient({
+ *   realm: 'mycompany',
+ *   auth: {
+ *     type: 'user-token',
+ *     userToken: 'your-user-token',
+ *   },
+ * });
+ * ```
+ *
+ * @example Temporary token authentication
+ * ```typescript
+ * const client = createClient({
+ *   realm: 'mycompany',
+ *   auth: {
+ *     type: 'temp-token',
+ *     userToken: 'your-user-token',
+ *     appToken: 'optional-app-token',
+ *   },
+ * });
+ * ```
+ *
+ * @example With rate limiting callback
+ * ```typescript
+ * const client = createClient({
+ *   realm: 'mycompany',
+ *   auth: { type: 'user-token', userToken: 'token' },
+ *   rateLimit: {
+ *     onRateLimit: (info) => {
+ *       console.log(`Rate limited! Retry after ${info.retryAfter}s`);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function createClient(config: QuickbaseConfig): QuickbaseClient {
+  const resolvedConfig = resolveConfig(config);
+  const logger = createLogger(resolvedConfig.debug);
+
+  const authContext = {
+    realm: resolvedConfig.realm,
+    baseUrl: resolvedConfig.baseUrl,
+    fetchApi: resolvedConfig.fetchApi,
+    logger,
+  };
+
+  const auth = createAuthStrategy(resolvedConfig.auth, authContext);
+  const throttle = createThrottle(resolvedConfig.proactiveThrottle);
+
+  const executor = createRequestExecutor({
+    config: resolvedConfig,
+    auth,
+    throttle,
+    logger,
+  });
+
+  // Create typed API methods
+  const apiMethods = createApiMethods(executor.execute, resolvedConfig.autoPaginate);
+
+  return {
+    ...apiMethods,
+    request: executor.execute,
+    getConfig: () => resolvedConfig,
+    // XML-API: Expose auth strategy for XML client
+    getAuthStrategy: () => auth,
+  };
+}
+
+// XML-API: XML API exports - remove when QuickBase discontinues XML API
+export {
+  createXmlClient,
+  XmlClient,
+  XmlError,
+  XmlErrorCode,
+  checkError,
+  isUnauthorized as isXmlUnauthorized,
+  isNotFound as isXmlNotFound,
+  isInvalidTicket as isXmlInvalidTicket,
+  isXmlWriteAction,
+} from './xml/index.js';
+export type {
+  XmlCaller,
+  XmlClientOptions,
+  XmlExecutor,
+  // Role types
+  Role,
+  RoleAccess,
+  UserRole,
+  RoleMember,
+  UserWithRoles,
+  // Group types
+  Group,
+  GroupUser,
+  GroupManager,
+  Subgroup,
+  // User types
+  UserInfo,
+  // Schema types (XML)
+  SchemaField,
+  SchemaQuery,
+  SchemaVariable,
+  SchemaChildTable,
+  SchemaOriginal,
+  SchemaTable,
+  // App discovery types
+  DatabaseInfo,
+  DBInfo,
+  // Record types (XML)
+  RecordField,
+  // Code page types
+  PageType,
+  // Webhook types
+  WebhookTrigger,
+  WebhookOptions,
+  // Result types
+  GetRoleInfoResult,
+  UserRolesResult,
+  GetUserRoleResult,
+  GetSchemaResult,
+  GrantedDBsResult,
+  FindDBByNameResult,
+  GetUsersInGroupResult,
+  CreateGroupResult,
+  GetGroupRoleResult,
+  ProvisionUserResult,
+  AddReplaceDBPageResult,
+  FieldAddChoicesResult,
+  FieldRemoveChoicesResult,
+  DoQueryCountResult,
+  GetRecordInfoResult,
+  GrantedGroupsResult,
+  GrantedDBsForGroupResult,
+  GetAppDTMInfoResult,
+  GetAncestorInfoResult,
+  ImportFromCSVResult,
+  CopyMasterDetailResult,
+  WebhookResult,
+} from './xml/index.js';
+
+// Default export
+export default createClient;

package/src/xml/codepages.ts

@@ -0,0 +1,119 @@
+/**
+ * XML API Code Pages
+ *
+ * Endpoints for managing stored code pages (HTML, XSL, etc.).
+ *
+ * XML-API: Remove this file when QuickBase discontinues the XML API.
+ * To find all XML API code, search for: XML-API
+ */
+
+import type {
+  XmlCaller,
+  PageType,
+  AddReplaceDBPageResult,
+} from './types.js';
+import { checkError } from './errors.js';
+import {
+  buildRequest,
+  escapeXml,
+  parseBaseResponse,
+  getTagContent,
+  xmlElementCDATA,
+  parseXmlNumber,
+} from './request.js';
+
+/**
+ * Get stored code page content.
+ *
+ * Returns the raw page content (HTML, XSL, etc.).
+ *
+ * @see https://help.quickbase.com/docs/api-getdbpage
+ *
+ * @param pageIdOrName - Page ID (number) or page name (string)
+ *
+ * @example
+ * ```typescript
+ * // By page ID
+ * const content = await getDBPage(caller, 'bqapp123', 3);
+ *
+ * // By page name
+ * const content = await getDBPage(caller, 'bqapp123', 'mystylesheet.xsl');
+ * ```
+ */
+export async function getDBPage(
+  caller: XmlCaller,
+  appId: string,
+  pageIdOrName: string | number
+): Promise<string> {
+  const inner = `<pageID>${escapeXml(String(pageIdOrName))}</pageID>`;
+  const body = buildRequest(inner);
+  const xml = await caller.doXml(appId, 'API_GetDBPage', body);
+
+  // Note: GetDBPage returns raw HTML, not XML
+  // Check if it's an error response
+  if (xml.includes('<errcode>') && !xml.includes('<errcode>0</errcode>')) {
+    const base = parseBaseResponse(xml);
+    checkError(base);
+  }
+
+  // If not an error, return the raw content
+  // The response is the page content itself, not wrapped in XML
+  return xml;
+}
+
+/**
+ * Create or update a code page.
+ *
+ * Page types:
+ * - 1: XSL stylesheets or HTML pages
+ * - 3: Exact Forms (Word templates)
+ *
+ * @see https://help.quickbase.com/docs/api-addreplacedbpage
+ *
+ * @param pageId - Existing page ID to replace (undefined to create new)
+ * @param pageName - Name for the page (required when creating new)
+ *
+ * @example
+ * ```typescript
+ * // Create a new page
+ * const result = await addReplaceDBPage(
+ *   caller, 'bqapp123',
+ *   'mypage.html', undefined, 1,
+ *   '<html><body>Hello World</body></html>'
+ * );
+ * console.log(`Created page ID: ${result.pageId}`);
+ *
+ * // Update existing page
+ * await addReplaceDBPage(
+ *   caller, 'bqapp123',
+ *   'mypage.html', 6, 1,
+ *   '<html><body>Updated content</body></html>'
+ * );
+ * ```
+ */
+export async function addReplaceDBPage(
+  caller: XmlCaller,
+  appId: string,
+  pageName: string,
+  pageId: number | undefined,
+  pageType: PageType,
+  pageBody: string
+): Promise<AddReplaceDBPageResult> {
+  let inner = '';
+
+  if (pageId !== undefined) {
+    inner += `<pageid>${pageId}</pageid>`;
+  }
+  inner += `<pagename>${escapeXml(pageName)}</pagename>`;
+  inner += `<pagetype>${pageType}</pagetype>`;
+  inner += xmlElementCDATA('pagebody', pageBody);
+
+  const body = buildRequest(inner);
+  const xml = await caller.doXml(appId, 'API_AddReplaceDBPage', body);
+
+  const base = parseBaseResponse(xml);
+  checkError(base);
+
+  const resultPageId = parseXmlNumber(getTagContent(xml, 'pageID'));
+  return { pageId: resultPageId };
+}

package/src/xml/dbvars.ts

@@ -0,0 +1,75 @@
+/**
+ * XML API Application Variables (DBVars)
+ *
+ * Endpoints for managing application variables.
+ *
+ * XML-API: Remove this file when QuickBase discontinues the XML API.
+ * To find all XML API code, search for: XML-API
+ */
+
+import type { XmlCaller } from './types.js';
+import { checkError } from './errors.js';
+import {
+  buildRequest,
+  escapeXml,
+  parseBaseResponse,
+  getTagContent,
+} from './request.js';
+
+/**
+ * Get an application variable value.
+ *
+ * DBVars are application-level variables that can be used in formulas
+ * and code pages.
+ *
+ * @see https://help.quickbase.com/docs/api-getdbvar
+ *
+ * @example
+ * ```typescript
+ * const value = await getDBVar(caller, 'bqapp123', 'myVariable');
+ * console.log(`Variable value: ${value}`);
+ * ```
+ */
+export async function getDBVar(
+  caller: XmlCaller,
+  appId: string,
+  varName: string
+): Promise<string> {
+  const inner = `<varname>${escapeXml(varName)}</varname>`;
+  const body = buildRequest(inner);
+  const xml = await caller.doXml(appId, 'API_GetDBVar', body);
+
+  const base = parseBaseResponse(xml);
+  checkError(base);
+
+  return getTagContent(xml, 'value');
+}
+
+/**
+ * Set an application variable value.
+ *
+ * Creates the variable if it doesn't exist, or overwrites if it does.
+ * Requires Full Administration rights on the application.
+ *
+ * @see https://help.quickbase.com/docs/api-setdbvar
+ *
+ * @example
+ * ```typescript
+ * await setDBVar(caller, 'bqapp123', 'myVariable', '42');
+ * ```
+ */
+export async function setDBVar(
+  caller: XmlCaller,
+  appId: string,
+  varName: string,
+  value: string
+): Promise<void> {
+  const inner =
+    `<varname>${escapeXml(varName)}</varname>` +
+    `<value>${escapeXml(value)}</value>`;
+  const body = buildRequest(inner);
+  const xml = await caller.doXml(appId, 'API_SetDBVar', body);
+
+  const base = parseBaseResponse(xml);
+  checkError(base);
+}

package/src/xml/errors.ts

@@ -0,0 +1,133 @@
+/**
+ * XML API Errors
+ *
+ * Error handling for the legacy QuickBase XML API.
+ *
+ * XML-API: Remove this file when QuickBase discontinues the XML API.
+ * To find all XML API code, search for: XML-API
+ */
+
+import type { BaseResponse } from './types.js';
+import { QuickbaseTicketError, QuickbaseAppTokenError, QuickbaseXmlError } from '../core/errors.js';
+
+/**
+ * Common QuickBase XML API error codes
+ */
+export const XmlErrorCode = {
+  /** No error (success) */
+  Success: 0,
+  /** Invalid input parameters */
+  InvalidInput: 2,
+  /** User is not authorized for this action */
+  Unauthorized: 3,
+  /** Authentication ticket is invalid or expired (Bad Ticket) */
+  InvalidTicket: 4,
+  /** Database/table does not exist */
+  NoSuchDatabase: 6,
+  /** SSL is required for this application/table */
+  SSLRequired: 8,
+  /** Realm IP filtering is in place */
+  UnauthorizedIP: 19,
+  /** Application token provided is invalid or not assigned */
+  InvalidAppToken: 24,
+  /** Record does not exist */
+  NoSuchRecord: 30,
+  /** Field does not exist */
+  NoSuchField: 31,
+  /** Application does not exist or was deleted */
+  NoSuchApp: 32,
+  /** User does not exist */
+  NoSuchUser: 33,
+  /** Access denied */
+  AccessDenied: 83,
+} as const;
+
+/**
+ * Error returned by the QuickBase XML API.
+ * 
+ * XML-API: This class is a legacy alias for QuickbaseXmlError.
+ */
+export class XmlError extends QuickbaseXmlError {
+  constructor(code: number, text: string, detail?: string, action?: string) {
+    super(code, text, { description: detail, action });
+    this.name = 'XmlError';
+  }
+}
+
+/**
+ * Check if the response contains an error and throw if so.
+ * Returns void if successful (errcode === 0).
+ */
+export function checkError(resp: BaseResponse): void {
+  if (resp.errcode === 0) {
+    return;
+  }
+
+  // Map to specialized error types
+  if (resp.errcode === XmlErrorCode.InvalidTicket) {
+    throw new QuickbaseTicketError(resp.errtext, resp.errcode, {
+      description: resp.errdetail,
+      action: resp.action,
+    });
+  }
+
+  if (
+    resp.errcode === XmlErrorCode.InvalidAppToken
+  ) {
+    throw new QuickbaseAppTokenError(resp.errtext, resp.errcode, {
+      description: resp.errdetail,
+      action: resp.action,
+    });
+  }
+
+  throw new XmlError(resp.errcode, resp.errtext, resp.errdetail, resp.action);
+}
+
+/**
+ * Check if the error is an authorization error (code 3 or 83)
+ */
+export function isUnauthorized(err: unknown): boolean {
+  if (err instanceof XmlError) {
+    return (
+      err.code === XmlErrorCode.Unauthorized ||
+      err.code === XmlErrorCode.AccessDenied
+    );
+  }
+  return false;
+}
+
+/**
+ * Check if the error indicates a resource was not found
+ */
+export function isNotFound(err: unknown): boolean {
+  if (err instanceof XmlError) {
+    return (
+      err.code === XmlErrorCode.NoSuchDatabase ||
+      err.code === XmlErrorCode.NoSuchApp ||
+      err.code === XmlErrorCode.NoSuchRecord ||
+      err.code === XmlErrorCode.NoSuchField ||
+      err.code === XmlErrorCode.NoSuchUser
+    );
+  }
+  return false;
+}
+
+/**
+ * Check if the error indicates an invalid or expired authentication ticket
+ */
+export function isInvalidTicket(err: unknown): boolean {
+  if (err instanceof XmlError) {
+    return err.code === XmlErrorCode.InvalidTicket;
+  }
+  return false;
+}
+
+/**
+ * Check if the error indicates invalid input parameters
+ */
+export function isInvalidInput(err: unknown): boolean {
+  if (err instanceof XmlError) {
+    return err.code === XmlErrorCode.InvalidInput;
+  }
+  return false;
+}

package/src/xml/fields.ts

@@ -0,0 +1,121 @@
+/**
+ * XML API Field Management
+ *
+ * Endpoints for managing field properties.
+ *
+ * XML-API: Remove this file when QuickBase discontinues the XML API.
+ * To find all XML API code, search for: XML-API
+ */
+
+import type {
+  XmlCaller,
+  FieldAddChoicesResult,
+  FieldRemoveChoicesResult,
+} from './types.js';
+import { checkError } from './errors.js';
+import {
+  buildRequest,
+  escapeXml,
+  parseBaseResponse,
+  getTagContent,
+  parseXmlNumber,
+} from './request.js';
+
+/**
+ * Add choices to a multiple-choice field.
+ *
+ * @see https://help.quickbase.com/docs/api-fieldaddchoices
+ *
+ * @example
+ * ```typescript
+ * const result = await fieldAddChoices(caller, 'bqtable123', 6, ['Option A', 'Option B']);
+ * console.log(`Added ${result.numAdded} choices`);
+ * ```
+ */
+export async function fieldAddChoices(
+  caller: XmlCaller,
+  tableId: string,
+  fieldId: number,
+  choices: string[]
+): Promise<FieldAddChoicesResult> {
+  if (choices.length === 0) {
+    throw new Error('choices array cannot be empty');
+  }
+  let inner = `<fid>${fieldId}</fid>`;
+  for (const choice of choices) {
+    inner += `<choice>${escapeXml(choice)}</choice>`;
+  }
+
+  const body = buildRequest(inner);
+  const xml = await caller.doXml(tableId, 'API_FieldAddChoices', body);
+
+  const base = parseBaseResponse(xml);
+  checkError(base);
+
+  return {
+    fieldId,
+    fieldName: getTagContent(xml, 'fname') || '',
+    numAdded: parseXmlNumber(getTagContent(xml, 'numadded')),
+  };
+}
+
+/**
+ * Remove choices from a multiple-choice field.
+ *
+ * @see https://help.quickbase.com/docs/api-fieldremovechoices
+ *
+ * @example
+ * ```typescript
+ * const result = await fieldRemoveChoices(caller, 'bqtable123', 6, ['Option A']);
+ * console.log(`Removed ${result.numRemoved} choices`);
+ * ```
+ */
+export async function fieldRemoveChoices(
+  caller: XmlCaller,
+  tableId: string,
+  fieldId: number,
+  choices: string[]
+): Promise<FieldRemoveChoicesResult> {
+  if (choices.length === 0) {
+    throw new Error('choices array cannot be empty');
+  }
+  let inner = `<fid>${fieldId}</fid>`;
+  for (const choice of choices) {
+    inner += `<choice>${escapeXml(choice)}</choice>`;
+  }
+
+  const body = buildRequest(inner);
+  const xml = await caller.doXml(tableId, 'API_FieldRemoveChoices', body);
+
+  const base = parseBaseResponse(xml);
+  checkError(base);
+
+  return {
+    fieldId,
+    fieldName: getTagContent(xml, 'fname') || '',
+    numRemoved: parseXmlNumber(getTagContent(xml, 'numremoved')),
+  };
+}
+
+/**
+ * Set the key field for a table.
+ *
+ * @see https://help.quickbase.com/docs/api-setkeyfield
+ *
+ * @example
+ * ```typescript
+ * await setKeyField(caller, 'bqtable123', 6);
+ * ```
+ */
+export async function setKeyField(
+  caller: XmlCaller,
+  tableId: string,
+  fieldId: number
+): Promise<void> {
+  const inner = `<fid>${fieldId}</fid>`;
+  const body = buildRequest(inner);
+  const xml = await caller.doXml(tableId, 'API_SetKeyField', body);
+
+  const base = parseBaseResponse(xml);
+  checkError(base);
+}