quickbase-js 2.1.0 → 2.2.0

package/README.md

@@ -5,12 +5,15 @@ A TypeScript/JavaScript client for the QuickBase JSON RESTful API.
 ## Features
 
 - **Typed API Methods** - Full TypeScript support with auto-generated types from OpenAPI spec
-- **Multiple Auth Methods** - User token, temporary token, and SSO authentication
+- **Multiple Auth Methods** - User token, temporary token, SSO, and ticket authentication
+- **Schema Aliases** - Use readable names for tables and fields instead of IDs
 - **Fluent Pagination** - Chain `.all()`, `.paginate()`, or `.noPaginate()` on paginated endpoints
 - **Date Conversion** - Automatic conversion of ISO date strings to JavaScript Date objects
 - **Rate Limit Handling** - Automatic retry with exponential backoff on 429 errors
 - **Proactive Throttling** - Optional client-side request throttling
 - **Tree-Shakeable** - Static method generation for optimal bundle size
+- **XML API Support** - Access legacy XML-only endpoints (roles, groups, DBVars, code pages, etc.)
+- **Read-Only Mode** - Defense-in-depth protection against accidental writes
 
 ## API Reference
 
@@ -36,12 +39,12 @@ For QuickBase Code Pages, use temp-token authentication which automatically leve
   // Realm can be auto-detected from the current URL
   const realm = window.location.hostname.split('.')[0];
 
-  const client = QuickBase.createClient({
+  const qb = QuickBase.createClient({
     realm: realm,
     auth: { type: 'temp-token' },
   });
 
-  client.getApp({ appId: 'bpqe82s1' }).then(app => {
+  qb.getApp({ appId: 'bpqe82s1' }).then(app => {
     console.log(app.name);
   });
 </script>
@@ -53,12 +56,12 @@ Or with ES modules:
 <script type="module">
   import { createClient } from 'https://cdn.jsdelivr.net/npm/quickbase-js@2/dist/quickbase.esm.js';
 
-  const client = createClient({
+  const qb = createClient({
     realm: 'mycompany',
     auth: { type: 'temp-token' },
   });
 
-  const app = await client.getApp({ appId: 'bpqe82s1' });
+  const app = await qb.getApp({ appId: 'bpqe82s1' });
   console.log(app.name);
 </script>
 ```
@@ -68,7 +71,7 @@ Or with ES modules:
 ```typescript
 import { createClient } from 'quickbase-js';
 
-const client = createClient({
+const qb = createClient({
   realm: 'mycompany',
   auth: {
     type: 'user-token',
@@ -77,11 +80,11 @@ const client = createClient({
 });
 
 // Use typed API methods
-const app = await client.getApp({ appId: 'bpqe82s1' });
+const app = await qb.getApp({ appId: 'bpqe82s1' });
 console.log(app.name);
 
 // Query records
-const records = await client.runQuery({
+const records = await qb.runQuery({
   from: 'bpqe82s1',
   select: [3, 6, 7],
   where: "{6.EX.'Active'}",
@@ -94,7 +97,7 @@ console.log(records.data);
 ### User Token (Recommended for Server-Side)
 
 ```typescript
-const client = createClient({
+const qb = createClient({
   realm: 'mycompany',
   auth: {
     type: 'user-token',
@@ -105,26 +108,16 @@ const client = createClient({
 
 ### Temporary Token (Recommended for Browser/Code Pages)
 
-Temporary tokens are automatically fetched and cached per database. They refresh on 401 errors.
+Temporary tokens are automatically fetched and cached per database. Tokens are refreshed proactively before expiration (default: 4m 50s TTL for 5-minute tokens). The SDK also handles unexpected 401 errors as a fallback.
 
 ```typescript
-// In QuickBase Code Pages - no user token needed (uses browser session)
-const client = createClient({
+// In QuickBase Code Pages - uses browser session for authentication
+const qb = createClient({
   realm: 'mycompany',
   auth: {
     type: 'temp-token',
   },
 });
-
-// Outside Code Pages - user token required to fetch temp tokens
-const client = createClient({
-  realm: 'mycompany',
-  auth: {
-    type: 'temp-token',
-    userToken: 'your-user-token',      // Required outside Code Pages
-    appToken: 'optional-app-token',    // If app requires it
-  },
-});
 ```
 
 **Auto dbid extraction:** The SDK automatically extracts the database ID for temp token authentication from your request parameters:
@@ -140,7 +133,7 @@ This means you don't need to manually specify the dbid - just make API calls and
 ### SSO Token
 
 ```typescript
-const client = createClient({
+const qb = createClient({
   realm: 'mycompany',
   auth: {
     type: 'sso',
@@ -151,43 +144,33 @@ const client = createClient({
 
 ### Ticket Auth (Username/Password)
 
-Ticket authentication lets users log in with their QuickBase email and password. Unlike user tokens, tickets properly attribute record changes (`createdBy`/`modifiedBy`) to the authenticated user.
+Ticket authentication lets users log in with their QuickBase email and password. Unlike user tokens, tickets properly attribute record changes (`createdBy`/`modifiedBy`) to the authenticated user. Credentials should come from user input (e.g., a login form), not hardcoded.
 
 ```typescript
-const client = createClient({
-  realm: 'mycompany',
-  auth: {
-    type: 'ticket',
-    username: 'user@example.com',
-    password: 'password',
-  },
-});
+// Create client after user submits login form
+function handleLogin(formData: { username: string; password: string }) {
+  const qb = createClient({
+    realm: 'mycompany',
+    auth: {
+      type: 'ticket',
+      username: formData.username,
+      password: formData.password,
+      hours: 24,                      // Optional: validity (default: 12h, max: ~6 months)
+      persist: 'sessionStorage',      // Optional: survive page refresh
+      onExpired: () => {              // Optional: called when ticket expires
+        window.location.href = '/login';
+      },
+    },
+  });
+  return qb;
+}
 ```
 
 **Key behaviors:**
 - Authentication happens lazily on the first API call
-- Password is discarded from memory after authentication
-- Tickets are valid for 12 hours by default (configurable up to ~6 months)
-- When the ticket expires, an error is thrown — create a new client with fresh credentials
-
-**With custom ticket validity:**
-
-```typescript
-const client = createClient({
-  realm: 'mycompany',
-  auth: {
-    type: 'ticket',
-    username: 'user@example.com',
-    password: 'password',
-    hours: 24 * 7, // 1 week
-  },
-});
-```
-
-**When to use ticket auth:**
-- Third-party services where users shouldn't share user tokens
-- Proper audit trails with correct `createdBy`/`modifiedBy` attribution
-- Session-based authentication flows
+- Password is discarded from memory immediately after authentication
+- Use `persist` to survive page refreshes (`'sessionStorage'` or `'localStorage'`)
+- Use `onExpired` to handle session expiration (e.g., redirect to login)
 
 ## Pagination
 
@@ -197,7 +180,7 @@ Paginated endpoints (`runQuery`, `runReport`, `getUsers`, etc.) return a `Pagina
 
 ```typescript
 // Returns first page only
-const page = await client.runQuery({ from: 'tableId' });
+const page = await qb.runQuery({ from: 'tableId' });
 console.log(page.data.length); // e.g., 100 records
 console.log(page.metadata.totalRecords); // e.g., 5000 total
 ```
@@ -206,7 +189,7 @@ console.log(page.metadata.totalRecords); // e.g., 5000 total
 
 ```typescript
 // Automatically fetches all pages and combines results
-const all = await client.runQuery({ from: 'tableId' }).all();
+const all = await qb.runQuery({ from: 'tableId' }).all();
 console.log(all.data.length); // 5000 records
 ```
 
@@ -214,7 +197,7 @@ console.log(all.data.length); // 5000 records
 
 ```typescript
 // Fetch up to 500 records (may span multiple pages)
-const limited = await client.runQuery({ from: 'tableId' }).paginate({ limit: 500 });
+const limited = await qb.runQuery({ from: 'tableId' }).paginate({ limit: 500 });
 console.log(limited.data.length); // 500 records
 ```
 
@@ -222,23 +205,23 @@ console.log(limited.data.length); // 500 records
 
 ```typescript
 // Explicitly fetch single page (useful when autoPaginate is enabled globally)
-const single = await client.runQuery({ from: 'tableId' }).noPaginate();
+const single = await qb.runQuery({ from: 'tableId' }).noPaginate();
 ```
 
 ### Global Auto-Pagination
 
 ```typescript
-const client = createClient({
+const qb = createClient({
   realm: 'mycompany',
   auth: { type: 'user-token', userToken: 'token' },
   autoPaginate: true, // Default await now fetches all pages
 });
 
 // Now direct await fetches all pages
-const all = await client.runQuery({ from: 'tableId' });
+const all = await qb.runQuery({ from: 'tableId' });
 
 // Use .noPaginate() to get single page
-const page = await client.runQuery({ from: 'tableId' }).noPaginate();
+const page = await qb.runQuery({ from: 'tableId' }).noPaginate();
 ```
 
 ## Date Conversion
@@ -246,14 +229,14 @@ const page = await client.runQuery({ from: 'tableId' }).noPaginate();
 By default, ISO 8601 date strings in API responses are automatically converted to JavaScript `Date` objects:
 
 ```typescript
-const app = await client.getApp({ appId: 'bpqe82s1' });
+const app = await qb.getApp({ appId: 'bpqe82s1' });
 
 // Date fields are now Date objects
 console.log(app.created instanceof Date); // true
 console.log(app.created.toISOString());   // "2024-01-15T10:30:00.000Z"
 
 // Works with nested objects and arrays
-const records = await client.runQuery({ from: 'tableId' });
+const records = await qb.runQuery({ from: 'tableId' });
 records.data.forEach(record => {
   // Date field values are converted
   console.log(record['7'].value instanceof Date); // true for date/timestamp fields
@@ -263,17 +246,221 @@ records.data.forEach(record => {
 To disable date conversion and keep dates as strings:
 
 ```typescript
-const client = createClient({
+const qb = createClient({
   realm: 'mycompany',
   auth: { type: 'user-token', userToken: 'token' },
   convertDates: false, // Keep dates as ISO strings
 });
 ```
 
+## Schema Aliases
+
+Use readable names for tables and fields instead of cryptic IDs. The SDK transforms aliases to IDs in requests and IDs back to aliases in responses.
+
+### Defining a Schema
+
+```typescript
+const qb = createClient({
+  realm: 'mycompany',
+  auth: { type: 'user-token', userToken: 'token' },
+  schema: {
+    tables: {
+      projects: {
+        id: 'bqw3ryzab',
+        fields: {
+          id: 3,
+          name: 6,
+          status: 7,
+          dueDate: 12,
+          assignee: 15,
+        },
+      },
+      tasks: {
+        id: 'bqw4xyzcd',
+        fields: {
+          id: 3,
+          title: 6,
+          projectId: 8,
+          completed: 10,
+        },
+      },
+    },
+  },
+});
+```
+
+### Using Aliases in Queries
+
+```typescript
+// Use table and field aliases instead of IDs
+const result = await qb.runQuery({
+  from: 'projects',                          // Instead of 'bqw3ryzab'
+  select: ['name', 'status', 'dueDate'],     // Instead of [6, 7, 12]
+  where: "{'status'.EX.'Active'}",           // Field aliases in where clauses
+  sortBy: [{ fieldId: 'dueDate', order: 'ASC' }],
+});
+
+// Response uses aliases and values are automatically unwrapped
+console.log(result.data[0].name);     // "Project Alpha" (not { value: "Project Alpha" })
+console.log(result.data[0].status);   // "Active"
+console.log(result.data[0].dueDate);  // Date object (if convertDates is enabled)
+```
+
+### Upserting with Aliases
+
+With schema, use field aliases as keys:
+
+```typescript
+await qb.upsert({
+  to: 'projects',
+  data: [
+    { name: 'New Project', status: 'Planning' },
+  ],
+});
+```
+
+## Auto-Wrapping
+
+Values are automatically wrapped in `{ value: X }` format for upserts. This works with or without a schema:
+
+```typescript
+// Clean syntax - values are auto-wrapped
+{ '6': 'New Record', '7': 42 }
+
+// Explicit wrapping also works (backwards compatible)
+{ '6': { value: 'New Record' }, '7': { value: 42 } }
+```
+
+### Response Transformation
+
+Responses are automatically transformed:
+- Field ID keys (`'6'`) become aliases (`name`)
+- Values are unwrapped from `{ value: X }` to just `X`
+- Unknown fields (not in schema) keep their numeric key but are still unwrapped
+
+```typescript
+// Raw API response:
+{ data: [{ '6': { value: 'Alpha' }, '99': { value: 'Custom' } }] }
+
+// Transformed response (with schema):
+{ data: [{ name: 'Alpha', '99': 'Custom' }] }
+```
+
+### Helpful Error Messages
+
+Typos in aliases throw errors with suggestions:
+
+```typescript
+// Throws: Unknown field alias 'stauts' in table 'projects'. Did you mean 'status'?
+await qb.runQuery({
+  from: 'projects',
+  select: ['stauts'],  // Typo!
+});
+```
+
+### Generating Schema from QuickBase
+
+Use the CLI to generate a schema from an existing app:
+
+```bash
+# Generate TypeScript schema file
+npx quickbase-js schema -r "$QB_REALM" -a "$QB_APP_ID" -t "$QB_USER_TOKEN" -o schema.ts
+
+# Generate JSON format
+npx quickbase-js schema -r "$QB_REALM" -a "$QB_APP_ID" -t "$QB_USER_TOKEN" -f json -o schema.json
+
+# Output to stdout
+npx quickbase-js schema -r "$QB_REALM" -a "$QB_APP_ID" -t "$QB_USER_TOKEN"
+```
+
+The generator creates aliases from field labels using camelCase (e.g., "Due Date" → `dueDate`).
+
+### Updating Schema with --merge
+
+When your QuickBase app changes (new tables, new fields), use `--merge` to update your schema while preserving any custom aliases you've set:
+
+```bash
+# Update schema, preserving custom aliases
+npx quickbase-js schema -r "$QB_REALM" -a "$QB_APP_ID" -t "$QB_USER_TOKEN" -o schema.ts --merge
+```
+
+**What merge does:**
+- Preserves your custom table and field aliases (matched by ID, not name)
+- Adds new tables and fields with auto-generated aliases
+- Reports what changed:
+
+```
+Merge complete:
+  Tables: 2 preserved, 1 added, 0 removed
+  Fields: 15 preserved, 3 added, 0 removed
+```
+
+This lets you rename auto-generated aliases like `dateCreated` to `created` and keep them through updates.
+
+### Using a Separate Schema File
+
+You can define your schema in a separate file and import it:
+
+**schema.ts**
+```typescript
+import type { Schema } from 'quickbase-js';
+
+export const schema: Schema = {
+  tables: {
+    projects: {
+      id: 'bqw3ryzab',
+      fields: {
+        id: 3,
+        name: 6,
+        status: 7,
+        dueDate: 12,
+      },
+    },
+  },
+};
+```
+
+**client.ts**
+```typescript
+import { createClient } from 'quickbase-js';
+import { schema } from './schema.js';
+
+const qb = createClient({
+  realm: 'mycompany',
+  auth: { type: 'user-token', userToken: 'token' },
+  schema,
+});
+```
+
+Or use a JSON file:
+
+**schema.json**
+```json
+{
+  "tables": {
+    "projects": {
+      "id": "bqw3ryzab",
+      "fields": { "id": 3, "name": 6, "status": 7 }
+    }
+  }
+}
+```
+
+```typescript
+import { createClient } from 'quickbase-js';
+import schema from './schema.json' assert { type: 'json' };
+
+const qb = createClient({
+  realm: 'mycompany',
+  auth: { type: 'user-token', userToken: 'token' },
+  schema,
+});
+```
+
 ## Configuration Options
 
 ```typescript
-const client = createClient({
+const qb = createClient({
   // Required
   realm: 'mycompany',
   auth: { /* see authentication section */ },
@@ -284,6 +471,8 @@ const client = createClient({
   baseUrl: 'https://api.quickbase.com/v1',   // API base URL
   autoPaginate: false,                       // Auto-paginate on direct await
   convertDates: true,                        // Convert ISO date strings to Date objects
+  readOnly: false,                           // Block all write operations
+  schema: { /* see schema aliases section */ }, // Table and field aliases
 
   // Rate limiting
   rateLimit: {
@@ -312,26 +501,327 @@ const client = createClient({
 });
 ```
 
+## XML API (Legacy Endpoints)
+
+The XML API provides access to endpoints not available in the JSON API, including role management, group management, app variables, code pages, and more.
+
+> **Note:** The XML API is a legacy API that may be discontinued by QuickBase in the future. Use the JSON API when possible.
+
+### Quick Start
+
+```typescript
+import { createClient, createXmlClient } from 'quickbase-js';
+
+// Create main client
+const qb = createClient({
+  realm: 'mycompany',
+  auth: { type: 'user-token', userToken: 'your-token' },
+});
+
+// Create XML client from main client
+const xml = createXmlClient(qb);
+
+// Get all roles in an app
+const roles = await xml.getRoleInfo(appId);
+for (const role of roles.roles) {
+  console.log(`${role.name}: ${role.access.description}`);
+}
+
+// Get all users and their role assignments
+const users = await xml.userRoles(appId);
+for (const user of users.users) {
+  console.log(`${user.name}: ${user.roles.map(r => r.name).join(', ')}`);
+}
+
+// Get comprehensive schema (fields, reports, variables)
+const schema = await xml.getSchema(tableId);
+for (const field of schema.table.fields ?? []) {
+  console.log(`Field ${field.id}: ${field.label} (${field.fieldType})`);
+}
+```
+
+### Available Methods
+
+**App Discovery:**
+
+| Method | XML Action | Description |
+|--------|------------|-------------|
+| `grantedDBs(opts?)` | API_GrantedDBs | List all apps/tables user can access |
+| `findDBByName(name, parentsOnly?)` | API_FindDBByName | Find an app by name |
+| `getDBInfo(dbid)` | API_GetDBInfo | Get app/table metadata (record count, manager, timestamps) |
+| `getNumRecords(tableId)` | API_GetNumRecords | Get total record count for a table |
+
+**Role Management:**
+
+| Method | XML Action | Description |
+|--------|------------|-------------|
+| `getRoleInfo(appId)` | API_GetRoleInfo | Get all roles defined in an application |
+| `userRoles(appId)` | API_UserRoles | Get all users and their role assignments |
+| `getUserRole(appId, userId, includeGroups?)` | API_GetUserRole | Get roles for a specific user |
+| `addUserToRole(appId, userId, roleId)` | API_AddUserToRole | Assign a user to a role |
+| `removeUserFromRole(appId, userId, roleId)` | API_RemoveUserFromRole | Remove a user from a role |
+| `changeUserRole(appId, userId, currentRole, newRole)` | API_ChangeUserRole | Change a user's role |
+
+**User Management:**
+
+| Method | XML Action | Description |
+|--------|------------|-------------|
+| `getUserInfo(email)` | API_GetUserInfo | Get user info by email address |
+| `provisionUser(appId, email, opts?)` | API_ProvisionUser | Create a new unregistered user |
+| `sendInvitation(appId, userId, userText?)` | API_SendInvitation | Send invitation email to a user |
+| `changeManager(appId, newManagerEmail)` | API_ChangeManager | Change the app manager |
+| `changeRecordOwner(tableId, recordId, newOwner)` | API_ChangeRecordOwner | Change record owner |
+
+**Group Management:**
+
+| Method | XML Action | Description |
+|--------|------------|-------------|
+| `createGroup(name, opts?)` | API_CreateGroup | Create a new group |
+| `deleteGroup(groupId)` | API_DeleteGroup | Delete a group |
+| `copyGroup(groupId, name, opts?)` | API_CopyGroup | Copy a group |
+| `changeGroupInfo(groupId, opts)` | API_ChangeGroupInfo | Update group name/description |
+| `getUsersInGroup(groupId, includeManagers?)` | API_GetUsersInGroup | Get users and managers in a group |
+| `addUserToGroup(groupId, userId, allowAdmin?)` | API_AddUserToGroup | Add a user to a group |
+| `removeUserFromGroup(groupId, userId)` | API_RemoveUserFromGroup | Remove a user from a group |
+| `getGroupRole(appId, groupId)` | API_GetGroupRole | Get roles assigned to a group |
+| `addGroupToRole(appId, groupId, roleId)` | API_AddGroupToRole | Assign a group to a role |
+| `removeGroupFromRole(appId, groupId, roleId, allRoles?)` | API_RemoveGroupFromRole | Remove a group from a role |
+| `grantedGroups(userId?, adminOnly?)` | API_GrantedGroups | Get groups a user belongs to |
+| `grantedDBsForGroup(groupId)` | API_GrantedDBsForGroup | Get apps a group can access |
+
+**App Metadata:**
+
+| Method | XML Action | Description |
+|--------|------------|-------------|
+| `getAppDTMInfo(appId)` | API_GetAppDTMInfo | Get modification timestamps |
+| `getAncestorInfo(appId)` | API_GetAncestorInfo | Get app copy/template lineage info |
+
+**Application Variables:**
+
+| Method | XML Action | Description |
+|--------|------------|-------------|
+| `getDBVar(appId, varName)` | API_GetDBVar | Get an application variable value |
+| `setDBVar(appId, varName, value)` | API_SetDBVar | Set an application variable value |
+
+**Code Pages:**
+
+| Method | XML Action | Description |
+|--------|------------|-------------|
+| `getDBPage(appId, pageIdOrName)` | API_GetDBPage | Get stored code page content |
+| `addReplaceDBPage(appId, opts)` | API_AddReplaceDBPage | Create or update a code page |
+
+**Field Management:**
+
+| Method | XML Action | Description |
+|--------|------------|-------------|
+| `fieldAddChoices(tableId, fieldId, choices)` | API_FieldAddChoices | Add choices to a multiple-choice field |
+| `fieldRemoveChoices(tableId, fieldId, choices)` | API_FieldRemoveChoices | Remove choices from a field |
+| `setKeyField(tableId, fieldId)` | API_SetKeyField | Set the key field for a table |
+
+**Schema Information:**
+
+| Method | XML Action | Description |
+|--------|------------|-------------|
+| `getSchema(dbid)` | API_GetSchema | Get comprehensive app/table metadata |
+
+**Record Information:**
+
+| Method | XML Action | Description |
+|--------|------------|-------------|
+| `doQueryCount(tableId, query?)` | API_DoQueryCount | Get count of matching records (no data fetch) |
+| `getRecordInfo(tableId, recordId)` | API_GetRecordInfo | Get record with field metadata |
+| `getRecordInfoByKey(tableId, keyValue)` | API_GetRecordInfo | Get record by key field value |
+
+**Record Operations:**
+
+| Method | XML Action | Description |
+|--------|------------|-------------|
+| `copyMasterDetail(tableId, opts)` | API_CopyMasterDetail | Copy a master record with its detail records |
+| `importFromCSV(tableId, opts)` | API_ImportFromCSV | Bulk import/update records from CSV data |
+| `runImport(tableId, importId)` | API_RunImport | Execute a saved import definition |
+
+**Webhooks:**
+
+| Method | XML Action | Description |
+|--------|------------|-------------|
+| `webhooksCreate(tableId, opts)` | API_Webhooks_Create | Create a webhook |
+| `webhooksEdit(tableId, webhookId, opts)` | API_Webhooks_Edit | Edit a webhook |
+| `webhooksDelete(tableId, webhookId)` | API_Webhooks_Delete | Delete a webhook |
+| `webhooksActivate(tableId, webhookId)` | API_Webhooks_Activate | Activate a webhook |
+| `webhooksDeactivate(tableId, webhookId)` | API_Webhooks_Deactivate | Deactivate a webhook |
+| `webhooksCopy(tableId, webhookId, name?)` | API_Webhooks_Copy | Copy a webhook |
+
+**HTML Generation:**
+
+| Method | XML Action | Description |
+|--------|------------|-------------|
+| `genAddRecordForm(tableId, fields?)` | API_GenAddRecordForm | Generate HTML form for adding a record |
+| `genResultsTable(tableId, opts?)` | API_GenResultsTable | Generate HTML/JS/CSV table of query results |
+| `getRecordAsHTML(tableId, opts)` | API_GetRecordAsHTML | Get a record rendered as HTML |
+
+**Authentication:**
+
+| Method | XML Action | Description |
+|--------|------------|-------------|
+| `signOut()` | API_SignOut | Clear ticket cookie (browser-focused) |
+
+### Error Handling
+
+XML API errors are returned as `XmlError`:
+
+```typescript
+import { XmlError, isUnauthorized, isNotFound, isInvalidTicket } from 'quickbase-js';
+
+try {
+  const roles = await xml.getRoleInfo(appId);
+} catch (error) {
+  if (error instanceof XmlError) {
+    console.log(`XML API error ${error.code}: ${error.text}`);
+
+    // Use helper functions for common error types
+    if (isUnauthorized(error)) {
+      console.log('Not authorized');
+    } else if (isNotFound(error)) {
+      console.log('Resource not found');
+    } else if (isInvalidTicket(error)) {
+      console.log('Invalid or expired ticket');
+    }
+  }
+}
+```
+
+### Read-Only Mode
+
+The XML client inherits read-only mode from the main client (see [Read-Only Mode](#read-only-mode-1)):
+
+```typescript
+const qb = createClient({
+  realm: 'mycompany',
+  auth: { type: 'user-token', userToken: 'token' },
+  readOnly: true,
+});
+
+const xml = createXmlClient(qb); // Inherits readOnly: true
+
+// Read operations work
+const roles = await xml.getRoleInfo(appId);
+
+// Write operations throw ReadOnlyError
+await xml.addUserToRole(appId, userId, roleId); // Throws!
+```
+
+You can also override read-only mode for just the XML client:
+
+```typescript
+const xml = createXmlClient(qb, { readOnly: true });
+```
+
+### Schema Aliases
+
+The XML client inherits the schema from the main client and supports table and field aliases:
+
+```typescript
+const qb = createClient({
+  realm: 'mycompany',
+  auth: { type: 'user-token', userToken: 'token' },
+  schema: {
+    tables: {
+      projects: {
+        id: 'bqprojects123',
+        fields: {
+          id: 3,
+          name: 6,
+          status: 7,
+        },
+      },
+    },
+  },
+});
+
+const xml = createXmlClient(qb);
+
+// Use table aliases
+const count = await xml.getNumRecords('projects');  // Resolves to 'bqprojects123'
+const roles = await xml.getRoleInfo('projects');
+
+// Use field aliases
+await xml.fieldAddChoices('projects', 'status', ['Active', 'Inactive']);
+await xml.setKeyField('projects', 'name');
+
+// Field aliases in importFromCSV
+await xml.importFromCSV('projects', {
+  recordsCsv: 'Project A,Active',
+  clist: ['name', 'status'],
+  mergeFieldId: 'id',
+});
+```
+
+**Response Transformation:**
+
+The XML client transforms responses to use field and table aliases as keys when a schema is configured, similar to the JSON API:
+
+```typescript
+// getRecordInfo - access fields by alias
+const record = await xml.getRecordInfo('projects', 123);
+console.log(record.fields.name.value);    // "Project Alpha"
+console.log(record.fields.status.value);  // "Active"
+
+// Without schema, fields are keyed by ID
+const record2 = await xmlNoSchema.getRecordInfo('bqprojects123', 123);
+console.log(record2.fields['6'].value);   // "Project Alpha"
+
+// getSchema - access fields by alias
+const schema = await xml.getSchema('projects');
+console.log(schema.table.fields?.name.label);    // "Project Name"
+console.log(schema.table.fields?.status.label);  // "Status"
+console.log(schema.table.childTables?.tasks.dbid);  // "bqtasks123"
+
+// grantedDBs - access databases by alias
+const dbs = await xml.grantedDBs();
+console.log(dbs.databases.projects.dbname);  // "My Projects App"
+console.log(dbs.databases.tasks.dbname);     // "Tasks Table"
+
+// Unknown tables/fields are keyed by their ID
+console.log(dbs.databases['bqunknown123'].dbname);  // "Unknown Table"
+
+// getAppDTMInfo - access tables by alias
+const dtm = await xml.getAppDTMInfo('projects');
+console.log(dtm.appAlias);                           // "projects"
+console.log(dtm.tables.projects.lastModifiedTime);   // "1234567890"
+console.log(dtm.tables.tasks.lastModifiedTime);      // "1234567891"
+```
+
+**Responses transformed to keyed objects:**
+
+| Method | Keyed Properties |
+|--------|-----------------|
+| `getRecordInfo` / `getRecordInfoByKey` | `fields.{alias}` |
+| `getSchema` | `table.fields.{alias}`, `table.childTables.{alias}` |
+| `grantedDBs` / `grantedDBsForGroup` | `databases.{alias}` |
+| `getAppDTMInfo` | `tables.{alias}` |
+| `fieldAddChoices` / `fieldRemoveChoices` | `fieldAlias` property |
+| `findDBByName` | `alias` property |
+
 ## API Methods
 
 All QuickBase API endpoints are available as typed methods:
 
 ```typescript
 // Apps
-const app = await client.getApp({ appId: 'bpqe82s1' });
-const newApp = await client.createApp({ name: 'My App', description: 'Test' });
-await client.updateApp({ appId: 'bpqe82s1' }, { name: 'Updated Name' });
-await client.deleteApp({ appId: 'bpqe82s1' }, { name: 'My App' });
+const app = await qb.getApp({ appId: 'bpqe82s1' });
+const newApp = await qb.createApp({ name: 'My App', description: 'Test' });
+await qb.updateApp({ appId: 'bpqe82s1' }, { name: 'Updated Name' });
+await qb.deleteApp({ appId: 'bpqe82s1' }, { name: 'My App' });
 
 // Tables
-const tables = await client.getAppTables({ appId: 'bpqe82s1' });
-const table = await client.getTable({ appId: 'bpqe82s1', tableId: 'byyy82s1' });
+const tables = await qb.getAppTables({ appId: 'bpqe82s1' });
+const table = await qb.getTable({ appId: 'bpqe82s1', tableId: 'byyy82s1' });
 
 // Fields
-const fields = await client.getFields({ tableId: 'byyy82s1' });
+const fields = await qb.getFields({ tableId: 'byyy82s1' });
 
 // Records
-const records = await client.runQuery({
+const records = await qb.runQuery({
   from: 'byyy82s1',
   select: [3, 6, 7],
   where: "{6.GT.100}",
@@ -339,28 +829,28 @@ const records = await client.runQuery({
   options: { top: 100, skip: 0 },
 });
 
-// Insert/Update records
-const result = await client.upsert({
+// Insert/Update records (values are auto-wrapped)
+const result = await qb.upsert({
   to: 'byyy82s1',
   data: [
-    { '6': { value: 'New Record' }, '7': { value: 42 } },
+    { '6': 'New Record', '7': 42 },
   ],
 });
 
 // Delete records
-await client.deleteRecords({
+await qb.deleteRecords({
   from: 'byyy82s1',
   where: "{3.EX.123}",
 });
 
 // Reports
-const report = await client.runReport(
+const report = await qb.runReport(
   { reportId: 'abc123', tableId: 'byyy82s1' },
   { skip: 0, top: 100 }
 );
 
 // Users
-const users = await client.getUsers(
+const users = await qb.getUsers(
   { accountId: '123456' },
   { appIds: ['bpqe82s1'] }
 );
@@ -371,7 +861,7 @@ const users = await client.getUsers(
 For endpoints not covered by typed methods, use the generic `request` method:
 
 ```typescript
-const result = await client.request<MyResponseType>({
+const result = await qb.request<MyResponseType>({
   method: 'POST',
   path: '/some/endpoint',
   body: { key: 'value' },
@@ -379,6 +869,99 @@ const result = await client.request<MyResponseType>({
 });
 ```
 
+## Read-Only Mode
+
+Enable read-only mode to prevent accidental writes during development, testing, or when building read-only dashboards. This feature uses defense-in-depth with two layers of protection.
+
+```typescript
+import { createClient, createXmlClient, ReadOnlyError } from 'quickbase-js';
+
+const qb = createClient({
+  realm: 'mycompany',
+  auth: { type: 'user-token', userToken: 'token' },
+  readOnly: true,
+});
+
+// Read operations work normally
+const app = await qb.getApp({ appId: 'bpqe82s1' });
+const records = await qb.runQuery({ from: 'byyy82s1' });
+
+// Write operations throw ReadOnlyError
+try {
+  await qb.upsert({ to: 'byyy82s1', data: [{ '6': 'test' }] });
+} catch (error) {
+  if (error instanceof ReadOnlyError) {
+    console.log(`Blocked: ${error.method} ${error.path}`);
+    // "Blocked: POST /records"
+  }
+}
+```
+
+### What Gets Blocked
+
+| Operation Type | Examples | Blocked? |
+|----------------|----------|----------|
+| **GET requests** | getApp, getFields, getTables | ✅ Allowed |
+| **Query POSTs** | runQuery, runReport, getUsers | ✅ Allowed |
+| **Create/Update** | upsert, createApp, createTable | ❌ Blocked |
+| **Delete** | deleteRecords, deleteApp | ❌ Blocked |
+| **XML writes** | addUserToRole, setDBVar | ❌ Blocked |
+
+### Defense-in-Depth
+
+The read-only check uses two layers:
+
+1. **Explicit blocklist** - Known write endpoints are blocked by path matching
+2. **HTTP method check** - Any POST/PUT/DELETE/PATCH not in the allowlist is blocked
+
+This ensures new API endpoints are blocked by default until explicitly allowlisted.
+
+### XML API
+
+The XML client automatically inherits read-only mode from the main client:
+
+```typescript
+const qb = createClient({
+  realm: 'mycompany',
+  auth: { type: 'user-token', userToken: 'token' },
+  readOnly: true,
+});
+
+const xml = createXmlClient(qb); // Inherits readOnly: true
+
+// Read operations work
+const roles = await xml.getRoleInfo(appId);
+
+// Write operations throw ReadOnlyError with action info
+try {
+  await xml.setDBVar(appId, 'myVar', 'value');
+} catch (error) {
+  if (error instanceof ReadOnlyError) {
+    console.log(`Blocked XML action: ${error.action}`);
+    // "Blocked XML action: API_SetDBVar"
+  }
+}
+```
+
+### ReadOnlyError
+
+The `ReadOnlyError` class provides details about the blocked operation:
+
+```typescript
+import { ReadOnlyError } from 'quickbase-js';
+
+try {
+  await qb.deleteRecords({ from: 'byyy82s1', where: '{3.GT.0}' });
+} catch (error) {
+  if (error instanceof ReadOnlyError) {
+    error.method;  // "DELETE"
+    error.path;    // "/records"
+    error.action;  // undefined (only set for XML API)
+    error.message; // "Read-only mode: write operation blocked (DELETE /records)"
+  }
+}
+```
+
 ## Error Handling
 
 ```typescript
@@ -390,10 +973,11 @@ import {
   NotFoundError,
   ValidationError,
   ServerError,
+  ReadOnlyError,
 } from 'quickbase-js';
 
 try {
-  await client.getApp({ appId: 'invalid' });
+  await qb.getApp({ appId: 'invalid' });
 } catch (error) {
   if (error instanceof RateLimitError) {
     console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
@@ -445,7 +1029,7 @@ Throw RateLimitError if exhausted
 ### Retry Configuration
 
 ```typescript
-const client = createClient({
+const qb = createClient({
   realm: 'mycompany',
   auth: { type: 'user-token', userToken: 'token' },
   rateLimit: {
@@ -466,7 +1050,7 @@ The backoff formula with jitter: `delay = initialDelayMs * (multiplier ^ attempt
 Prevent 429 errors entirely by throttling requests client-side using a sliding window algorithm:
 
 ```typescript
-const client = createClient({
+const qb = createClient({
   realm: 'mycompany',
   auth: { type: 'user-token', userToken: 'token' },
   rateLimit: {
@@ -485,7 +1069,7 @@ This tracks request timestamps and blocks new requests when the limit would be e
 Get notified when rate limited (called before retry):
 
 ```typescript
-const client = createClient({
+const qb = createClient({
   realm: 'mycompany',
   auth: { type: 'user-token', userToken: 'token' },
   rateLimit: {
@@ -507,7 +1091,7 @@ If retries are exhausted, a `RateLimitError` is thrown:
 import { RateLimitError } from 'quickbase-js';
 
 try {
-  await client.getApp({ appId: 'bpqe82s1' });
+  await qb.getApp({ appId: 'bpqe82s1' });
 } catch (error) {
   if (error instanceof RateLimitError) {
     console.log(`Rate limited after ${error.rateLimitInfo.attempt} attempts`);
@@ -525,7 +1109,7 @@ try {
 const qb = quickbase({ realm: 'company', userToken: 'token' });
 
 // v2 - user token (explicit type)
-const client = createClient({
+const qb = createClient({
   realm: 'company',
   auth: { type: 'user-token', userToken: 'token' },
 });
@@ -534,7 +1118,7 @@ const client = createClient({
 const qb = quickbase({ realm: 'company', useTempTokens: true });
 
 // v2 - temp tokens in Code Pages
-const client = createClient({
+const qb = createClient({
   realm: 'company',
   auth: { type: 'temp-token' },
 });
@@ -548,8 +1132,8 @@ await qb.withPaginationDisabled(async () => qb.runQuery({ body: { from: tableId
 await qb.withPaginationLimit(100, async () => qb.runQuery({ body: { from: tableId } }));
 
 // v2 - fluent API
-await client.runQuery({ from: tableId }).noPaginate();
-await client.runQuery({ from: tableId }).paginate({ limit: 100 });
+await qb.runQuery({ from: tableId }).noPaginate();
+await qb.runQuery({ from: tableId }).paginate({ limit: 100 });
 ```
 
 ### Request Body
@@ -559,7 +1143,7 @@ await client.runQuery({ from: tableId }).paginate({ limit: 100 });
 await qb.runQuery({ body: { from: tableId, select: [3, 6] } });
 
 // v2 - direct parameters
-await client.runQuery({ from: tableId, select: [3, 6] });
+await qb.runQuery({ from: tableId, select: [3, 6] });
 ```
 
 ## Development