quickbase-js 2.4.0 → 2.4.1

package/src/xml/metadata.ts

@@ -0,0 +1,111 @@
+/**
+ * XML API App Metadata
+ *
+ * Endpoints for getting app metadata and ancestry info.
+ *
+ * XML-API: Remove this file when QuickBase discontinues the XML API.
+ * To find all XML API code, search for: XML-API
+ */
+
+import type {
+  XmlCaller,
+  GetAppDTMInfoResult,
+  GetAncestorInfoResult,
+} from './types.js';
+import { checkError } from './errors.js';
+import {
+  buildRequest,
+  escapeXml,
+  parseBaseResponse,
+  getTagContent,
+  getAllElements,
+  getAttribute,
+} from './request.js';
+
+/**
+ * Get modification timestamps (fast, no auth required for some info).
+ *
+ * This is a lightweight call to check if data has changed.
+ *
+ * @see https://help.quickbase.com/docs/api-getappdtminfo
+ *
+ * @example
+ * ```typescript
+ * const info = await getAppDTMInfo(caller, 'bqapp123');
+ * console.log(`Last modified: ${info.lastModifiedTime}`);
+ * ```
+ */
+export async function getAppDTMInfo(
+  caller: XmlCaller,
+  appId: string
+): Promise<GetAppDTMInfoResult> {
+  // GetAppDTMInfo is invoked on db/main with appId in the body
+  const inner = `<dbid>${escapeXml(appId)}</dbid>`;
+  const body = buildRequest(inner);
+  const xml = await caller.doXml('main', 'API_GetAppDTMInfo', body);
+
+  const base = parseBaseResponse(xml);
+  checkError(base);
+
+  // Parse tables
+  const tableElements = getAllElements(xml, 'table');
+  const tables = tableElements.map((tableXml) => ({
+    id: getAttribute(tableXml, 'id'),
+    lastModifiedTime: getTagContent(tableXml, 'lastModifiedTime') || undefined,
+    lastRecModTime: getTagContent(tableXml, 'lastRecModTime') || undefined,
+  }));
+
+  return {
+    appId: getTagContent(xml, 'app_id') || appId,
+    lastModifiedTime: getTagContent(xml, 'lastModifiedTime') || undefined,
+    lastRecModTime: getTagContent(xml, 'lastRecModTime') || undefined,
+    tables,
+  };
+}
+
+/**
+ * Get app copy/template lineage info.
+ *
+ * @see https://help.quickbase.com/docs/api-getancestorinfo
+ *
+ * @example
+ * ```typescript
+ * const info = await getAncestorInfo(caller, 'bqapp123');
+ * if (info.ancestorAppId) {
+ *   console.log(`This app was copied from: ${info.ancestorAppId}`);
+ * }
+ * ```
+ */
+export async function getAncestorInfo(
+  caller: XmlCaller,
+  appId: string
+): Promise<GetAncestorInfoResult> {
+  const body = buildRequest('');
+  const xml = await caller.doXml(appId, 'API_GetAncestorInfo', body);
+
+  const base = parseBaseResponse(xml);
+  checkError(base);
+
+  return {
+    ancestorAppId: getTagContent(xml, 'ancestorappid') || undefined,
+    oldestAncestorAppId: getTagContent(xml, 'oldestancestorappid') || undefined,
+  };
+}
+
+/**
+ * Clear ticket cookie (browser-focused).
+ *
+ * @see https://help.quickbase.com/docs/api-signout
+ *
+ * @example
+ * ```typescript
+ * await signOut(caller);
+ * ```
+ */
+export async function signOut(caller: XmlCaller): Promise<void> {
+  const body = buildRequest('');
+  const xml = await caller.doXml('main', 'API_SignOut', body);
+
+  const base = parseBaseResponse(xml);
+  checkError(base);
+}

package/src/xml/records.ts

@@ -0,0 +1,301 @@
+/**
+ * XML API Record Information
+ *
+ * Endpoints for querying and managing record information.
+ *
+ * XML-API: Remove this file when QuickBase discontinues the XML API.
+ * To find all XML API code, search for: XML-API
+ */
+
+import type {
+  XmlCaller,
+  RecordField,
+  DoQueryCountResult,
+  GetRecordInfoResult,
+  ImportFromCSVResult,
+  CopyMasterDetailResult,
+} from './types.js';
+import { checkError } from './errors.js';
+import {
+  buildRequest,
+  escapeXml,
+  parseBaseResponse,
+  getTagContent,
+  getAttribute,
+  getAllElements,
+  parseXmlNumber,
+  xmlElementCDATA,
+} from './request.js';
+
+/**
+ * Parse a field element from GetRecordInfo response
+ */
+function parseRecordField(fieldXml: string): RecordField {
+  const field: RecordField = {
+    id: parseXmlNumber(getTagContent(fieldXml, 'fid')),
+    name: getTagContent(fieldXml, 'name'),
+    type: getTagContent(fieldXml, 'type'),
+    value: getTagContent(fieldXml, 'value'),
+  };
+
+  const printable = getTagContent(fieldXml, 'printable');
+  if (printable) field.printable = printable;
+
+  return field;
+}
+
+/**
+ * Get count of matching records without fetching data.
+ *
+ * @see https://help.quickbase.com/docs/api-doquerycount
+ *
+ * @example
+ * ```typescript
+ * const result = await doQueryCount(caller, 'bqtable123', "{'7'.XCT.'blue car'}");
+ * console.log(`Found ${result.numMatches} matching records`);
+ * ```
+ */
+export async function doQueryCount(
+  caller: XmlCaller,
+  tableId: string,
+  query?: string
+): Promise<DoQueryCountResult> {
+  let inner = '';
+  if (query) {
+    inner = `<query>${escapeXml(query)}</query>`;
+  }
+
+  const body = buildRequest(inner);
+  const xml = await caller.doXml(tableId, 'API_DoQueryCount', body);
+
+  const base = parseBaseResponse(xml);
+  checkError(base);
+
+  return {
+    numMatches: parseXmlNumber(getTagContent(xml, 'numMatches')),
+  };
+}
+
+/**
+ * Get a record with field metadata.
+ *
+ * Returns all fields for the specified record, including field names and types.
+ *
+ * @see https://help.quickbase.com/docs/api-getrecordinfo
+ *
+ * @example
+ * ```typescript
+ * const result = await getRecordInfo(caller, 'bqtable123', 42);
+ * console.log(`Record ${result.recordId} has ${result.numFields} fields`);
+ * for (const field of result.fields) {
+ *   console.log(`  ${field.name}: ${field.value}`);
+ * }
+ * ```
+ */
+export async function getRecordInfo(
+  caller: XmlCaller,
+  tableId: string,
+  recordId: number
+): Promise<GetRecordInfoResult> {
+  const inner = `<rid>${recordId}</rid>`;
+  const body = buildRequest(inner);
+  const xml = await caller.doXml(tableId, 'API_GetRecordInfo', body);
+
+  const base = parseBaseResponse(xml);
+  checkError(base);
+
+  const fieldElements = getAllElements(xml, 'field');
+  const fields = fieldElements.map(parseRecordField);
+
+  return {
+    recordId: parseXmlNumber(getTagContent(xml, 'rid')),
+    numFields: parseXmlNumber(getTagContent(xml, 'num_fields')),
+    updateId: getTagContent(xml, 'update_id') || undefined,
+    fields,
+  };
+}
+
+/**
+ * Get a record by key field value.
+ *
+ * @see https://help.quickbase.com/docs/api-getrecordinfo
+ *
+ * @example
+ * ```typescript
+ * const result = await getRecordInfoByKey(caller, 'bqtable123', 'ABC-123');
+ * ```
+ */
+export async function getRecordInfoByKey(
+  caller: XmlCaller,
+  tableId: string,
+  keyValue: string
+): Promise<GetRecordInfoResult> {
+  const inner = `<key>${escapeXml(keyValue)}</key>`;
+  const body = buildRequest(inner);
+  const xml = await caller.doXml(tableId, 'API_GetRecordInfo', body);
+
+  const base = parseBaseResponse(xml);
+  checkError(base);
+
+  const fieldElements = getAllElements(xml, 'field');
+  const fields = fieldElements.map(parseRecordField);
+
+  return {
+    recordId: parseXmlNumber(getTagContent(xml, 'rid')),
+    numFields: parseXmlNumber(getTagContent(xml, 'num_fields')),
+    updateId: getTagContent(xml, 'update_id') || undefined,
+    fields,
+  };
+}
+
+/**
+ * Bulk import/update records from CSV data.
+ *
+ * You can add and update records in the same call.
+ * Leave Record ID empty to add new records.
+ *
+ * @see https://help.quickbase.com/docs/api-importfromcsv
+ *
+ * @example
+ * ```typescript
+ * const result = await importFromCSV(caller, 'bqtable123', {
+ *   recordsCsv: 'Name,Email\nJohn,john@example.com\nJane,jane@example.com',
+ *   clist: [7, 8],
+ *   skipFirst: true,
+ * });
+ * console.log(`Added ${result.numRecsAdded}, updated ${result.numRecsUpdated}`);
+ * ```
+ */
+export async function importFromCSV(
+  caller: XmlCaller,
+  tableId: string,
+  options: {
+    recordsCsv: string;
+    clist?: number[];
+    skipFirst?: boolean;
+    mergeFieldId?: number;
+    decimalPercent?: boolean;
+  }
+): Promise<ImportFromCSVResult> {
+  let inner = xmlElementCDATA('records_csv', options.recordsCsv);
+
+  if (options.clist && options.clist.length > 0) {
+    inner += `<clist>${options.clist.join('.')}</clist>`;
+  }
+  if (options.skipFirst) {
+    inner += '<skipfirst>1</skipfirst>';
+  }
+  if (options.mergeFieldId !== undefined) {
+    inner += `<mergeFieldId>${options.mergeFieldId}</mergeFieldId>`;
+  }
+  if (options.decimalPercent) {
+    inner += '<decimalPercent>1</decimalPercent>';
+  }
+
+  const body = buildRequest(inner);
+  const xml = await caller.doXml(tableId, 'API_ImportFromCSV', body);
+
+  const base = parseBaseResponse(xml);
+  checkError(base);
+
+  // Parse record IDs
+  const ridElements = getAllElements(xml, 'rid');
+  const recordIds = ridElements.map((ridXml) => {
+    const rid = parseXmlNumber(ridXml.replace(/<rid[^>]*>/, '').replace(/<\/rid>/, ''));
+    const updateId = getAttribute(ridXml, 'update_id') || undefined;
+    return { recordId: rid, updateId };
+  });
+
+  return {
+    numRecsInput: parseXmlNumber(getTagContent(xml, 'num_recs_input')),
+    numRecsAdded: parseXmlNumber(getTagContent(xml, 'num_recs_added')),
+    numRecsUpdated: parseXmlNumber(getTagContent(xml, 'num_recs_updated')),
+    recordIds,
+  };
+}
+
+/**
+ * Execute a saved import definition.
+ *
+ * @see https://help.quickbase.com/docs/api-runimport
+ *
+ * @example
+ * ```typescript
+ * const result = await runImport(caller, 'bqtable123', 5);
+ * ```
+ */
+export async function runImport(
+  caller: XmlCaller,
+  tableId: string,
+  importId: number
+): Promise<ImportFromCSVResult> {
+  const inner = `<id>${importId}</id>`;
+  const body = buildRequest(inner);
+  const xml = await caller.doXml(tableId, 'API_RunImport', body);
+
+  const base = parseBaseResponse(xml);
+  checkError(base);
+
+  // Parse record IDs
+  const ridElements = getAllElements(xml, 'rid');
+  const recordIds = ridElements.map((ridXml) => {
+    const rid = parseXmlNumber(ridXml.replace(/<rid[^>]*>/, '').replace(/<\/rid>/, ''));
+    const updateId = getAttribute(ridXml, 'update_id') || undefined;
+    return { recordId: rid, updateId };
+  });
+
+  return {
+    numRecsInput: parseXmlNumber(getTagContent(xml, 'num_recs_input')),
+    numRecsAdded: parseXmlNumber(getTagContent(xml, 'num_recs_added')),
+    numRecsUpdated: parseXmlNumber(getTagContent(xml, 'num_recs_updated')),
+    recordIds,
+  };
+}
+
+/**
+ * Copy a master record with its detail records.
+ *
+ * @see https://help.quickbase.com/docs/api-copymasterdetail
+ *
+ * @example
+ * ```typescript
+ * const result = await copyMasterDetail(caller, 'bqtable123', {
+ *   rid: 42,
+ *   recurse: true,
+ * });
+ * console.log(`Copied to record ${result.newRid}`);
+ * ```
+ */
+export async function copyMasterDetail(
+  caller: XmlCaller,
+  tableId: string,
+  options: {
+    rid: number;
+    copyfid?: number;
+    recurse?: boolean;
+    relfids?: number[];
+  }
+): Promise<CopyMasterDetailResult> {
+  let inner = `<rid>${options.rid}</rid>`;
+
+  if (options.copyfid !== undefined) {
+    inner += `<copyfid>${options.copyfid}</copyfid>`;
+  }
+  if (options.recurse) {
+    inner += '<recurse>1</recurse>';
+  }
+  if (options.relfids && options.relfids.length > 0) {
+    inner += `<relfids>${options.relfids.join('.')}</relfids>`;
+  }
+
+  const body = buildRequest(inner);
+  const xml = await caller.doXml(tableId, 'API_CopyMasterDetail', body);
+
+  const base = parseBaseResponse(xml);
+  checkError(base);
+
+  return {
+    newRid: parseXmlNumber(getTagContent(xml, 'newrid')),
+    numCreated: parseXmlNumber(getTagContent(xml, 'num_created')),
+  };
+}

package/src/xml/request.ts

@@ -0,0 +1,238 @@
+/**
+ * XML API Request/Response Utilities
+ *
+ * Utilities for building XML requests and parsing XML responses
+ * 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';
+
+/**
+ * Build an XML API request body.
+ * Wraps the inner XML content in <qdbapi> tags.
+ *
+ * @param inner - The inner XML content (without qdbapi wrapper)
+ * @returns Complete XML request body
+ *
+ * @example
+ * buildRequest('<userid>123</userid><roleid>10</roleid>')
+ * // Returns: '<qdbapi><userid>123</userid><roleid>10</roleid></qdbapi>'
+ */
+export function buildRequest(inner: string): string {
+  return `<qdbapi>${inner}</qdbapi>`;
+}
+
+/**
+ * Inject an app token into an XML request body.
+ * The body is expected to have the format <qdbapi>...</qdbapi>.
+ * The apptoken is inserted right after the opening <qdbapi> tag.
+ *
+ * @param body - The XML request body
+ * @param appToken - The app token to inject
+ * @returns Body with apptoken element inserted
+ *
+ * @example
+ * injectAppToken('<qdbapi><query>{}</query></qdbapi>', 'abc123')
+ * // Returns: '<qdbapi><apptoken>abc123</apptoken><query>{}</query></qdbapi>'
+ */
+export function injectAppToken(body: string, appToken: string): string {
+  const openTag = '<qdbapi>';
+  const idx = body.indexOf(openTag);
+  if (idx === -1) {
+    return body; // Can't find tag, return unchanged
+  }
+  const insertPos = idx + openTag.length;
+  const appTokenElem = `<apptoken>${escapeXml(appToken)}</apptoken>`;
+  return body.slice(0, insertPos) + appTokenElem + body.slice(insertPos);
+}
+
+/**
+ * Inject a user token into an XML request body.
+ * The body is expected to have the format <qdbapi>...</qdbapi>.
+ * The usertoken is inserted right after the opening <qdbapi> tag.
+ *
+ * The XML API requires authentication tokens as body elements, not headers.
+ * See: https://help.quickbase.com/docs/api-getdbpage
+ *
+ * @param body - The XML request body
+ * @param userToken - The user token to inject
+ * @returns Body with usertoken element inserted
+ *
+ * @example
+ * injectUserToken('<qdbapi><query>{}</query></qdbapi>', 'b5d4r...')
+ * // Returns: '<qdbapi><usertoken>b5d4r...</usertoken><query>{}</query></qdbapi>'
+ */
+export function injectUserToken(body: string, userToken: string): string {
+  const openTag = '<qdbapi>';
+  const idx = body.indexOf(openTag);
+  if (idx === -1) {
+    return body; // Can't find tag, return unchanged
+  }
+  const insertPos = idx + openTag.length;
+  const userTokenElem = `<usertoken>${escapeXml(userToken)}</usertoken>`;
+  return body.slice(0, insertPos) + userTokenElem + body.slice(insertPos);
+}
+
+/**
+ * Escape special characters for safe inclusion in XML.
+ *
+ * @param str - The string to escape
+ * @returns XML-escaped string
+ */
+export function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Extract text content from a single XML tag.
+ * Uses regex for simple extraction without DOM parsing.
+ *
+ * @param xml - The XML string to search
+ * @param tag - The tag name to extract
+ * @returns The text content or empty string if not found
+ */
+export function getTagContent(xml: string, tag: string): string {
+  // Match tag with optional attributes, capture inner content
+  const match = xml.match(new RegExp(`<${tag}(?:\\s[^>]*)?>([^<]*)</${tag}>`));
+  return match?.[1] ?? '';
+}
+
+/**
+ * Extract text content with CDATA support.
+ * Some XML responses wrap content in CDATA blocks.
+ *
+ * @param xml - The XML string to search
+ * @param tag - The tag name to extract
+ * @returns The text content or empty string if not found
+ */
+export function getTagContentWithCDATA(xml: string, tag: string): string {
+  // Try CDATA first
+  const cdataMatch = xml.match(
+    new RegExp(`<${tag}>\\s*<!\\[CDATA\\[([\\s\\S]*?)\\]\\]>\\s*</${tag}>`)
+  );
+  if (cdataMatch && cdataMatch[1] !== undefined) {
+    return cdataMatch[1];
+  }
+  // Fall back to regular content
+  return getTagContent(xml, tag);
+}
+
+/**
+ * Extract an attribute value from an XML element.
+ *
+ * @param xml - The XML element string
+ * @param attr - The attribute name
+ * @returns The attribute value or empty string if not found
+ */
+export function getAttribute(xml: string, attr: string): string {
+  const match = xml.match(new RegExp(`${attr}="([^"]*)"`));
+  return match?.[1] ?? '';
+}
+
+/**
+ * Extract all occurrences of a tag as an array of strings.
+ *
+ * @param xml - The XML string to search
+ * @param tag - The tag name to extract
+ * @returns Array of XML element strings (including tags)
+ */
+export function getAllElements(xml: string, tag: string): string[] {
+  const regex = new RegExp(`<${tag}[^>]*>([\\s\\S]*?)</${tag}>`, 'g');
+  const elements: string[] = [];
+  let match;
+  while ((match = regex.exec(xml)) !== null) {
+    elements.push(match[0]);
+  }
+  return elements;
+}
+
+/**
+ * Parse the base response fields from an XML API response.
+ *
+ * @param xml - The XML response string
+ * @returns BaseResponse with action, errcode, errtext, errdetail
+ */
+export function parseBaseResponse(xml: string): BaseResponse {
+  const errdetail = getTagContent(xml, 'errdetail');
+  return {
+    action: getTagContent(xml, 'action'),
+    errcode: parseInt(getTagContent(xml, 'errcode'), 10) || 0,
+    errtext: getTagContent(xml, 'errtext'),
+    errdetail: errdetail || undefined,
+  };
+}
+
+/**
+ * Create an XML element with content.
+ * Escapes the content automatically.
+ *
+ * @param tag - The tag name
+ * @param content - The content (will be escaped)
+ * @returns XML element string
+ */
+export function xmlElement(tag: string, content: string | number): string {
+  return `<${tag}>${escapeXml(String(content))}</${tag}>`;
+}
+
+/**
+ * Create an XML element with CDATA content.
+ * Use for large text content that may contain special characters.
+ *
+ * @param tag - The tag name
+ * @param content - The content (will be wrapped in CDATA)
+ * @returns XML element string with CDATA
+ */
+export function xmlElementCDATA(tag: string, content: string): string {
+  // CDATA cannot contain the sequence ]]> - if present, split it
+  const escaped = content.replace(/\]\]>/g, ']]]]><![CDATA[>');
+  return `<${tag}><![CDATA[${escaped}]]></${tag}>`;
+}
+
+/**
+ * Create an XML element with an attribute.
+ *
+ * @param tag - The tag name
+ * @param attrName - The attribute name
+ * @param attrValue - The attribute value
+ * @param content - The content (will be escaped)
+ * @returns XML element string with attribute
+ */
+export function xmlElementWithAttr(
+  tag: string,
+  attrName: string,
+  attrValue: string | number,
+  content: string | number
+): string {
+  return `<${tag} ${attrName}="${escapeXml(String(attrValue))}">${escapeXml(String(content))}</${tag}>`;
+}
+
+/**
+ * Parse a boolean-like value from XML.
+ * QuickBase uses "1" for true, "0" or empty for false.
+ *
+ * @param value - The string value to parse
+ * @returns boolean
+ */
+export function parseXmlBool(value: string): boolean {
+  return value === '1' || value.toLowerCase() === 'true';
+}
+
+/**
+ * Parse a numeric value from XML.
+ *
+ * @param value - The string value to parse
+ * @param defaultValue - Default value if parsing fails
+ * @returns number
+ */
+export function parseXmlNumber(value: string, defaultValue = 0): number {
+  const num = parseInt(value, 10);
+  return isNaN(num) ? defaultValue : num;
+}