quickbase-js 2.1.0 → 2.2.0

package/dist/xml/request.js

@@ -0,0 +1,167 @@
+/**
+ * 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
+ */
+/**
+ * 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) {
+    return `<qdbapi>${inner}</qdbapi>`;
+}
+/**
+ * Escape special characters for safe inclusion in XML.
+ *
+ * @param str - The string to escape
+ * @returns XML-escaped string
+ */
+export function escapeXml(str) {
+    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, tag) {
+    // 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, tag) {
+    // 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, attr) {
+    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, tag) {
+    const regex = new RegExp(`<${tag}[^>]*>([\\s\\S]*?)</${tag}>`, 'g');
+    const elements = [];
+    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) {
+    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, content) {
+    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, content) {
+    // 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, attrName, attrValue, content) {
+    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) {
+    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, defaultValue = 0) {
+    const num = parseInt(value, 10);
+    return isNaN(num) ? defaultValue : num;
+}
+//# sourceMappingURL=request.js.map

package/dist/xml/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/xml/request.ts"],"names":[],"mappings":"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"}

package/dist/xml/roles.d.ts

@@ -0,0 +1,117 @@
+/**
+ * XML API Role Management
+ *
+ * Endpoints for managing roles and user role assignments.
+ *
+ * XML-API: Remove this file when QuickBase discontinues the XML API.
+ * To find all XML API code, search for: XML-API
+ */
+import type { XmlCaller, GetRoleInfoResult, UserRolesResult, GetUserRoleResult } from './types.js';
+/**
+ * Get all roles defined in an application.
+ *
+ * @see https://help.quickbase.com/docs/api-getroleinfo
+ *
+ * @example
+ * ```typescript
+ * const result = await getRoleInfo(caller, 'bqxyz123');
+ * for (const role of result.roles) {
+ *   console.log(`Role ${role.id}: ${role.name} (${role.access.description})`);
+ * }
+ * ```
+ */
+export declare function getRoleInfo(caller: XmlCaller, appId: string): Promise<GetRoleInfoResult>;
+/**
+ * Get all users in an application and their role assignments.
+ *
+ * Requires Basic Access with Sharing or Full Administration access.
+ *
+ * @see https://help.quickbase.com/docs/api-userroles
+ *
+ * @example
+ * ```typescript
+ * const result = await userRoles(caller, 'bqxyz123');
+ * for (const user of result.users) {
+ *   console.log(`${user.name}: ${user.roles.map(r => r.name).join(', ')}`);
+ * }
+ * ```
+ */
+export declare function userRoles(caller: XmlCaller, appId: string): Promise<UserRolesResult>;
+/**
+ * Get roles for a specific user.
+ *
+ * If userId is omitted, returns your own roles.
+ * Set includeGroups to true to include roles assigned via groups.
+ *
+ * @see https://help.quickbase.com/docs/api-getuserrole
+ *
+ * @example
+ * ```typescript
+ * const result = await getUserRole(caller, 'bqxyz123', '112149.bhsv', true);
+ * console.log(`User: ${result.userName}`);
+ * for (const role of result.roles) {
+ *   if (role.member) {
+ *     console.log(`  ${role.name} (via ${role.member.type}: ${role.member.name})`);
+ *   } else {
+ *     console.log(`  ${role.name}`);
+ *   }
+ * }
+ * ```
+ */
+export declare function getUserRole(caller: XmlCaller, appId: string, userId?: string, includeGroups?: boolean): Promise<GetUserRoleResult>;
+/**
+ * Assign a user to a role.
+ *
+ * You can call this multiple times to give a user multiple roles.
+ * After assigning, use sendInvitation to invite the user.
+ *
+ * Requires Basic Access with Sharing or Full Administration access.
+ * Users with Basic Access cannot add users to admin roles.
+ *
+ * @see https://help.quickbase.com/docs/api-addusertorole
+ *
+ * @example
+ * ```typescript
+ * await addUserToRole(caller, 'bqxyz123', '112149.bhsv', 10);
+ * ```
+ */
+export declare function addUserToRole(caller: XmlCaller, appId: string, userId: string, roleId: number): Promise<void>;
+/**
+ * Remove a user from a specific role.
+ *
+ * If this is the user's only role, they lose all access to the app
+ * and are removed from the app's user list.
+ *
+ * To temporarily disable access while keeping the user in the app,
+ * use changeUserRole with newRoleId=0 instead.
+ *
+ * @see https://help.quickbase.com/docs/api-removeuserfromrole
+ *
+ * @example
+ * ```typescript
+ * await removeUserFromRole(caller, 'bqxyz123', '112149.bhsv', 10);
+ * ```
+ */
+export declare function removeUserFromRole(caller: XmlCaller, appId: string, userId: string, roleId: number): Promise<void>;
+/**
+ * Change a user's role or disable their access.
+ *
+ * This is preferred over removeUserFromRole when you want to keep the
+ * user in the app's user list but change/disable their access.
+ *
+ * Pass newRoleId=0 (or omit it) to set the role to "None" (role ID 9),
+ * which disables access while keeping the user on the app's user list.
+ *
+ * @see https://help.quickbase.com/docs/api-changeuserrole
+ *
+ * @example
+ * ```typescript
+ * // Change from role 10 to role 11
+ * await changeUserRole(caller, 'bqxyz123', '112149.bhsv', 10, 11);
+ *
+ * // Disable access (set to None role)
+ * await changeUserRole(caller, 'bqxyz123', '112149.bhsv', 10, 0);
+ * ```
+ */
+export declare function changeUserRole(caller: XmlCaller, appId: string, userId: string, currentRoleId: number, newRoleId?: number): Promise<void>;
+//# sourceMappingURL=roles.d.ts.map

package/dist/xml/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../src/xml/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,SAAS,EAMT,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAwEpB;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,iBAAiB,CAAC,CAY5B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,eAAe,CAAC,CAY1B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,EACf,aAAa,CAAC,EAAE,OAAO,GACtB,OAAO,CAAC,iBAAiB,CAAC,CAiC5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAgBf"}

package/dist/xml/roles.js

@@ -0,0 +1,241 @@
+/**
+ * XML API Role Management
+ *
+ * Endpoints for managing roles and user role assignments.
+ *
+ * XML-API: Remove this file when QuickBase discontinues the XML API.
+ * To find all XML API code, search for: XML-API
+ */
+import { checkError } from './errors.js';
+import { buildRequest, escapeXml, parseBaseResponse, getTagContent, getAttribute, getAllElements, parseXmlNumber, } from './request.js';
+/**
+ * Parse a single role element from XML
+ */
+function parseRole(roleXml) {
+    const id = parseXmlNumber(getAttribute(roleXml, 'id'));
+    const name = getTagContent(roleXml, 'name');
+    // Parse access element
+    const accessMatch = roleXml.match(/<access[^>]*id="(\d+)"[^>]*>([^<]*)<\/access>/);
+    const access = {
+        id: accessMatch ? parseXmlNumber(accessMatch[1] ?? '0') : 0,
+        description: accessMatch?.[2] ?? '',
+    };
+    return { id, name, access };
+}
+/**
+ * Parse a role with member info (from GetUserRole with inclgrps)
+ */
+function parseUserRole(roleXml) {
+    const role = parseRole(roleXml);
+    // Parse member element if present
+    const memberMatch = roleXml.match(/<member[^>]*type="([^"]*)"[^>]*>([^<]*)<\/member>/);
+    const member = memberMatch && memberMatch[1] && memberMatch[2]
+        ? { type: memberMatch[1], name: memberMatch[2] }
+        : undefined;
+    return { ...role, member };
+}
+/**
+ * Parse a user with roles from UserRoles response
+ */
+function parseUserWithRoles(userXml) {
+    const id = getAttribute(userXml, 'id');
+    const type = getAttribute(userXml, 'type') || 'user';
+    const name = getTagContent(userXml, 'name');
+    const firstName = getTagContent(userXml, 'firstName') || undefined;
+    const lastName = getTagContent(userXml, 'lastName') || undefined;
+    const lastAccess = getTagContent(userXml, 'lastAccess') || undefined;
+    const lastAccessAppLocal = getTagContent(userXml, 'lastAccessAppLocal') || undefined;
+    // Parse roles
+    const roleElements = getAllElements(userXml, 'role');
+    const roles = roleElements.map(parseRole);
+    return {
+        id,
+        type,
+        name,
+        firstName,
+        lastName,
+        lastAccess,
+        lastAccessAppLocal,
+        roles,
+    };
+}
+/**
+ * Get all roles defined in an application.
+ *
+ * @see https://help.quickbase.com/docs/api-getroleinfo
+ *
+ * @example
+ * ```typescript
+ * const result = await getRoleInfo(caller, 'bqxyz123');
+ * for (const role of result.roles) {
+ *   console.log(`Role ${role.id}: ${role.name} (${role.access.description})`);
+ * }
+ * ```
+ */
+export async function getRoleInfo(caller, appId) {
+    const body = buildRequest('');
+    const xml = await caller.doXml(appId, 'API_GetRoleInfo', body);
+    const base = parseBaseResponse(xml);
+    checkError(base);
+    // Parse roles
+    const roleElements = getAllElements(xml, 'role');
+    const roles = roleElements.map(parseRole);
+    return { roles };
+}
+/**
+ * Get all users in an application and their role assignments.
+ *
+ * Requires Basic Access with Sharing or Full Administration access.
+ *
+ * @see https://help.quickbase.com/docs/api-userroles
+ *
+ * @example
+ * ```typescript
+ * const result = await userRoles(caller, 'bqxyz123');
+ * for (const user of result.users) {
+ *   console.log(`${user.name}: ${user.roles.map(r => r.name).join(', ')}`);
+ * }
+ * ```
+ */
+export async function userRoles(caller, appId) {
+    const body = buildRequest('');
+    const xml = await caller.doXml(appId, 'API_UserRoles', body);
+    const base = parseBaseResponse(xml);
+    checkError(base);
+    // Parse users
+    const userElements = getAllElements(xml, 'user');
+    const users = userElements.map(parseUserWithRoles);
+    return { users };
+}
+/**
+ * Get roles for a specific user.
+ *
+ * If userId is omitted, returns your own roles.
+ * Set includeGroups to true to include roles assigned via groups.
+ *
+ * @see https://help.quickbase.com/docs/api-getuserrole
+ *
+ * @example
+ * ```typescript
+ * const result = await getUserRole(caller, 'bqxyz123', '112149.bhsv', true);
+ * console.log(`User: ${result.userName}`);
+ * for (const role of result.roles) {
+ *   if (role.member) {
+ *     console.log(`  ${role.name} (via ${role.member.type}: ${role.member.name})`);
+ *   } else {
+ *     console.log(`  ${role.name}`);
+ *   }
+ * }
+ * ```
+ */
+export async function getUserRole(caller, appId, userId, includeGroups) {
+    let inner = '';
+    if (userId) {
+        inner += `<userid>${escapeXml(userId)}</userid>`;
+    }
+    if (includeGroups) {
+        inner += '<inclgrps>1</inclgrps>';
+    }
+    const body = buildRequest(inner);
+    const xml = await caller.doXml(appId, 'API_GetUserRole', body);
+    const base = parseBaseResponse(xml);
+    checkError(base);
+    // Parse user element
+    const userMatch = xml.match(/<user[^>]*id="([^"]*)"[^>]*>([\s\S]*?)<\/user>/);
+    if (!userMatch || !userMatch[1]) {
+        throw new Error('Invalid API_GetUserRole response: no user element');
+    }
+    const userIdResult = userMatch[1];
+    const userXml = userMatch[0];
+    const userName = getTagContent(userXml, 'name');
+    // Parse roles (with member info if inclgrps was used)
+    const roleElements = getAllElements(userXml, 'role');
+    const roles = roleElements.map(parseUserRole);
+    return {
+        userId: userIdResult,
+        userName,
+        roles,
+    };
+}
+/**
+ * Assign a user to a role.
+ *
+ * You can call this multiple times to give a user multiple roles.
+ * After assigning, use sendInvitation to invite the user.
+ *
+ * Requires Basic Access with Sharing or Full Administration access.
+ * Users with Basic Access cannot add users to admin roles.
+ *
+ * @see https://help.quickbase.com/docs/api-addusertorole
+ *
+ * @example
+ * ```typescript
+ * await addUserToRole(caller, 'bqxyz123', '112149.bhsv', 10);
+ * ```
+ */
+export async function addUserToRole(caller, appId, userId, roleId) {
+    const inner = `<userid>${escapeXml(userId)}</userid>` +
+        `<roleid>${roleId}</roleid>`;
+    const body = buildRequest(inner);
+    const xml = await caller.doXml(appId, 'API_AddUserToRole', body);
+    const base = parseBaseResponse(xml);
+    checkError(base);
+}
+/**
+ * Remove a user from a specific role.
+ *
+ * If this is the user's only role, they lose all access to the app
+ * and are removed from the app's user list.
+ *
+ * To temporarily disable access while keeping the user in the app,
+ * use changeUserRole with newRoleId=0 instead.
+ *
+ * @see https://help.quickbase.com/docs/api-removeuserfromrole
+ *
+ * @example
+ * ```typescript
+ * await removeUserFromRole(caller, 'bqxyz123', '112149.bhsv', 10);
+ * ```
+ */
+export async function removeUserFromRole(caller, appId, userId, roleId) {
+    const inner = `<userid>${escapeXml(userId)}</userid>` +
+        `<roleid>${roleId}</roleid>`;
+    const body = buildRequest(inner);
+    const xml = await caller.doXml(appId, 'API_RemoveUserFromRole', body);
+    const base = parseBaseResponse(xml);
+    checkError(base);
+}
+/**
+ * Change a user's role or disable their access.
+ *
+ * This is preferred over removeUserFromRole when you want to keep the
+ * user in the app's user list but change/disable their access.
+ *
+ * Pass newRoleId=0 (or omit it) to set the role to "None" (role ID 9),
+ * which disables access while keeping the user on the app's user list.
+ *
+ * @see https://help.quickbase.com/docs/api-changeuserrole
+ *
+ * @example
+ * ```typescript
+ * // Change from role 10 to role 11
+ * await changeUserRole(caller, 'bqxyz123', '112149.bhsv', 10, 11);
+ *
+ * // Disable access (set to None role)
+ * await changeUserRole(caller, 'bqxyz123', '112149.bhsv', 10, 0);
+ * ```
+ */
+export async function changeUserRole(caller, appId, userId, currentRoleId, newRoleId) {
+    let inner = `<userid>${escapeXml(userId)}</userid>` +
+        `<roleid>${currentRoleId}</roleid>`;
+    // If newRoleId is provided and > 0, include it
+    // If omitted or 0, QuickBase sets role to None (9)
+    if (newRoleId !== undefined && newRoleId > 0) {
+        inner += `<newRoleid>${newRoleId}</newRoleid>`;
+    }
+    const body = buildRequest(inner);
+    const xml = await caller.doXml(appId, 'API_ChangeUserRole', body);
+    const base = parseBaseResponse(xml);
+    checkError(base);
+}
+//# sourceMappingURL=roles.js.map

package/dist/xml/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../../src/xml/roles.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,cAAc,EACd,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB;;GAEG;AACH,SAAS,SAAS,CAAC,OAAe;IAChC,MAAM,EAAE,GAAG,cAAc,CAAC,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;IACvD,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAE5C,uBAAuB;IACvB,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnF,MAAM,MAAM,GAAe;QACzB,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3D,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE;KACpC,CAAC;IAEF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CAAC,OAAe;IACpC,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAEhC,kCAAkC;IAClC,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvF,MAAM,MAAM,GAA2B,WAAW,IAAI,WAAW,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC;QACpF,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE;QAChD,CAAC,CAAC,SAAS,CAAC;IAEd,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,SAAS,kBAAkB,CAAC,OAAe;IACzC,MAAM,EAAE,GAAG,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC;IACrD,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,aAAa,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,SAAS,CAAC;IACnE,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,EAAE,UAAU,CAAC,IAAI,SAAS,CAAC;IACjE,MAAM,UAAU,GAAG,aAAa,CAAC,OAAO,EAAE,YAAY,CAAC,IAAI,SAAS,CAAC;IACrE,MAAM,kBAAkB,GAAG,aAAa,CAAC,OAAO,EAAE,oBAAoB,CAAC,IAAI,SAAS,CAAC;IAErF,cAAc;IACd,MAAM,YAAY,GAAG,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAE1C,OAAO;QACL,EAAE;QACF,IAAI;QACJ,IAAI;QACJ,SAAS;QACT,QAAQ;QACR,UAAU;QACV,kBAAkB;QAClB,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAiB,EACjB,KAAa;IAEb,MAAM,IAAI,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,iBAAiB,EAAE,IAAI,CAAC,CAAC;IAE/D,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACpC,UAAU,CAAC,IAAI,CAAC,CAAC;IAEjB,cAAc;IACd,MAAM,YAAY,GAAG,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAE1C,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,MAAiB,EACjB,KAAa;IAEb,MAAM,IAAI,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;IAC9B,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,eAAe,EAAE,IAAI,CAAC,CAAC;IAE7D,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACpC,UAAU,CAAC,IAAI,CAAC,CAAC;IAEjB,cAAc;IACd,MAAM,YAAY,GAAG,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAEnD,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAiB,EACjB,KAAa,EACb,MAAe,EACf,aAAuB;IAEvB,IAAI,KAAK,GAAG,EAAE,CAAC;IACf,IAAI,MAAM,EAAE,CAAC;QACX,KAAK,IAAI,WAAW,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC;IACnD,CAAC;IACD,IAAI,aAAa,EAAE,CAAC;QAClB,KAAK,IAAI,wBAAwB,CAAC;IACpC,CAAC;IACD,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,iBAAiB,EAAE,IAAI,CAAC,CAAC;IAE/D,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACpC,UAAU,CAAC,IAAI,CAAC,CAAC;IAEjB,qBAAqB;IACrB,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,gDAAgD,CAAC,CAAC;IAC9E,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,YAAY,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAClC,MAAM,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAEhD,sDAAsD;IACtD,MAAM,YAAY,GAAG,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAE9C,OAAO;QACL,MAAM,EAAE,YAAY;QACpB,QAAQ;QACR,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAiB,EACjB,KAAa,EACb,MAAc,EACd,MAAc;IAEd,MAAM,KAAK,GACT,WAAW,SAAS,CAAC,MAAM,CAAC,WAAW;QACvC,WAAW,MAAM,WAAW,CAAC;IAC/B,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,mBAAmB,EAAE,IAAI,CAAC,CAAC;IAEjE,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACpC,UAAU,CAAC,IAAI,CAAC,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAiB,EACjB,KAAa,EACb,MAAc,EACd,MAAc;IAEd,MAAM,KAAK,GACT,WAAW,SAAS,CAAC,MAAM,CAAC,WAAW;QACvC,WAAW,MAAM,WAAW,CAAC;IAC/B,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,wBAAwB,EAAE,IAAI,CAAC,CAAC;IAEtE,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACpC,UAAU,CAAC,IAAI,CAAC,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAiB,EACjB,KAAa,EACb,MAAc,EACd,aAAqB,EACrB,SAAkB;IAElB,IAAI,KAAK,GACP,WAAW,SAAS,CAAC,MAAM,CAAC,WAAW;QACvC,WAAW,aAAa,WAAW,CAAC;IAEtC,+CAA+C;IAC/C,mDAAmD;IACnD,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QAC7C,KAAK,IAAI,cAAc,SAAS,cAAc,CAAC;IACjD,CAAC;IAED,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,oBAAoB,EAAE,IAAI,CAAC,CAAC;IAElE,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACpC,UAAU,CAAC,IAAI,CAAC,CAAC;AACnB,CAAC"}

package/dist/xml/schema.d.ts

@@ -0,0 +1,94 @@
+/**
+ * XML API Schema and App Discovery
+ *
+ * Endpoints for discovering apps/tables and getting schema 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, DBInfo, GetSchemaResult, GrantedDBsResult, FindDBByNameResult } from './types.js';
+/**
+ * List all apps/tables the user can access.
+ *
+ * Returns apps across all domains by default. Use realmAppsOnly to limit
+ * to the current realm.
+ *
+ * @see https://help.quickbase.com/docs/api-granteddbs
+ *
+ * @example
+ * ```typescript
+ * const result = await grantedDBs(caller, { parentsOnly: true });
+ * for (const db of result.databases) {
+ *   console.log(`${db.name} (${db.dbid})`);
+ * }
+ * ```
+ */
+export declare function grantedDBs(caller: XmlCaller, options?: {
+    parentsOnly?: boolean;
+    excludeParents?: boolean;
+    adminOnly?: boolean;
+    includeAncestors?: boolean;
+    withEmbeddedTables?: boolean;
+    realmAppsOnly?: boolean;
+}): Promise<GrantedDBsResult>;
+/**
+ * Find an app by name.
+ *
+ * Searches only apps you have access to. May return multiple results
+ * if multiple apps share the same name.
+ *
+ * @see https://help.quickbase.com/docs/api-finddbbyname
+ *
+ * @example
+ * ```typescript
+ * const result = await findDBByName(caller, 'My App', true);
+ * console.log(`Found app: ${result.dbid}`);
+ * ```
+ */
+export declare function findDBByName(caller: XmlCaller, name: string, parentsOnly?: boolean): Promise<FindDBByNameResult>;
+/**
+ * Get app/table metadata.
+ *
+ * Returns information like last modified time, record count, manager info.
+ *
+ * @see https://help.quickbase.com/docs/api-getdbinfo
+ *
+ * @example
+ * ```typescript
+ * const info = await getDBInfo(caller, 'bqxyz123');
+ * console.log(`${info.name}: ${info.numRecords} records`);
+ * console.log(`Manager: ${info.managerName}`);
+ * ```
+ */
+export declare function getDBInfo(caller: XmlCaller, dbid: string): Promise<DBInfo>;
+/**
+ * Get total record count for a table.
+ *
+ * @see https://help.quickbase.com/docs/api-getnumrecords
+ *
+ * @example
+ * ```typescript
+ * const count = await getNumRecords(caller, 'bqtable123');
+ * console.log(`Table has ${count} records`);
+ * ```
+ */
+export declare function getNumRecords(caller: XmlCaller, tableId: string): Promise<number>;
+/**
+ * Get comprehensive app/table schema information.
+ *
+ * When called on an app dbid: returns DBVars and child table dbids.
+ * When called on a table dbid: returns fields, queries, DBVars, and more.
+ *
+ * @see https://help.quickbase.com/docs/api-getschema
+ *
+ * @example
+ * ```typescript
+ * const schema = await getSchema(caller, 'bqtable123');
+ * console.log(`Table: ${schema.table.name}`);
+ * for (const field of schema.table.fields ?? []) {
+ *   console.log(`  Field ${field.id}: ${field.label} (${field.fieldType})`);
+ * }
+ * ```
+ */
+export declare function getSchema(caller: XmlCaller, dbid: string): Promise<GetSchemaResult>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/xml/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/xml/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,SAAS,EAET,MAAM,EACN,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAOnB,MAAM,YAAY,CAAC;AAapB;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,SAAS,EACjB,OAAO,CAAC,EAAE;IACR,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,GACA,OAAO,CAAC,gBAAgB,CAAC,CAiD3B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,OAAO,GACpB,OAAO,CAAC,kBAAkB,CAAC,CAkB7B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAQjB;AAgHD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,eAAe,CAAC,CA8F1B"}