quickbase-js 2.3.0 → 2.4.1

package/README.md

@@ -1,1253 +1,291 @@
-# QuickBase JS SDK v2
+# quickbase-js
 
-A TypeScript/JavaScript client for the QuickBase JSON RESTful API.
+[![npm](https://img.shields.io/npm/v/quickbase-js)](https://www.npmjs.com/package/quickbase-js)
+[![CI](https://github.com/DrewBradfordXYZ/quickbase-js/actions/workflows/ci.yml/badge.svg)](https://github.com/DrewBradfordXYZ/quickbase-js/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/quickbase-js)](LICENSE)
 
-## Features
+The QuickBase API for TypeScript and JavaScript, in Node.js, the browser and QuickBase code pages.
 
-- **Typed API Methods** - Full TypeScript support with auto-generated types from OpenAPI spec
-- **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
-
-**[View Full API Documentation →](https://drewbradfordxyz.github.io/quickbase-js/)**
-
-The SDK provides typed methods for all 59 QuickBase API endpoints including Apps, Tables, Fields, Records, Reports, Users, and more. Each method includes JSDoc documentation with links to the official QuickBase API docs.
-
-## Installation
+```typescript
+const projects = await qb.runQuery({ from: 'bqtable1', where: "{7.EX.'Active'}" }).all();
+```
 
-### npm / Node.js
+- **Every endpoint** in QuickBase's API as a typed method, generated from QuickBase's published spec and checked against live responses.
+- **Every page of results** with `.all()`, so you never write a `skip` loop.
+- **Field names instead of IDs**: `select: ['name', 'status']`, with a generator that writes the names from your app.
+- **No token in code pages**: the client signs in with the user's QuickBase session and renews its tokens.
+- **Rate limits handled**: 429s and server errors are retried with backoff, and the client can pace itself to stay under the limit.
+- **The XML API too**, for roles, groups, code pages, app variables and CSV imports.
+- **No dependencies**, a read-only mode for tools that must never write, and typed errors.
 
 ```bash
 npm install quickbase-js
 ```
 
-### Browser / CDN (QuickBase Code Pages)
-
-For QuickBase Code Pages, use temp-token authentication which automatically leverages the user's browser session:
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/quickbase-js@2/dist/quickbase.min.js"></script>
-<script>
-  // Realm can be auto-detected from the current URL
-  const realm = window.location.hostname.split('.')[0];
-
-  const qb = QuickBase.createClient({
-    realm: realm,
-    auth: { type: 'temp-token' },
-  });
-
-  qb.getApp({ appId: 'bpqe82s1' }).then(app => {
-    console.log(app.name);
-  });
-</script>
-```
-
-Or with ES modules:
-
-```html
-<script type="module">
-  import { createClient } from 'https://cdn.jsdelivr.net/npm/quickbase-js@2/dist/quickbase.esm.js';
-
-  const qb = createClient({
-    realm: 'mycompany',
-    auth: { type: 'temp-token' },
-  });
-
-  const app = await qb.getApp({ appId: 'bpqe82s1' });
-  console.log(app.name);
-</script>
-```
+## Quick start
 
-## Quick Start
+Create a [user token](https://help.quickbase.com/docs/user-tokens) in QuickBase, then:
 
 ```typescript
 import { createClient } from 'quickbase-js';
 
 const qb = createClient({
-  realm: 'mycompany',
-  auth: {
-    type: 'user-token',
-    userToken: 'your-user-token',
-  },
+  realm: 'mycompany', // mycompany.quickbase.com
+  auth: { type: 'user-token', userToken: process.env.QB_USER_TOKEN! },
 });
 
-// Use typed API methods
 const app = await qb.getApp({ appId: 'bpqe82s1' });
 console.log(app.name);
 
-// Query records
-const records = await qb.runQuery({
-  from: 'bpqe82s1',
+const result = await qb.runQuery({
+  from: 'bqtable1',
   select: [3, 6, 7],
-  where: "{6.EX.'Active'}",
-});
-console.log(records.data);
-```
-
-## Authentication
-
-### User Token (Recommended for Server-Side)
-
-```typescript
-const qb = createClient({
-  realm: 'mycompany',
-  auth: {
-    type: 'user-token',
-    userToken: 'your-user-token',
-  },
-});
-```
-
-### Temporary Token (Recommended for Browser/Code Pages)
-
-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 - uses browser session for authentication
-const qb = createClient({
-  realm: 'mycompany',
-  auth: {
-    type: 'temp-token',
-  },
-});
-```
-
-**Auto dbid extraction:** The SDK automatically extracts the database ID for temp token authentication from your request parameters:
-
-- `body.from` (runQuery, deleteRecords)
-- `body.to` (upsert)
-- `query.tableId` (getFields, etc.)
-- `query.appId` (getAppTables, etc.)
-- Path segments `/tables/{tableId}` and `/apps/{appId}`
-
-This means you don't need to manually specify the dbid - just make API calls and the SDK handles token management automatically.
-
-### SSO Token
+  where: "{7.EX.'Active'}",
+}).all(); // every page
+for (const record of result.data ?? []) {
+  console.log(record['6']?.value);
+}
 
-```typescript
-const qb = createClient({
-  realm: 'mycompany',
-  auth: {
-    type: 'sso',
-    samlToken: 'your-saml-token',
-  },
+await qb.upsert({
+  to: 'bqtable1',
+  data: [{ '6': 'New project', '7': 'Active' }], // plain values are wrapped for you
 });
 ```
 
-### Ticket Auth (Username/Password)
+## In a code page
 
-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.
+Load the browser bundle and use temporary-token auth. Calls run as the signed-in user, with that user's permissions, and there is no token in your page.
 
-```typescript
-// 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';
-      },
-    },
+```html
+<script src="https://cdn.jsdelivr.net/npm/quickbase-js@2/dist/quickbase.min.js"></script>
+<script>
+  const qb = QuickBase.createClient({
+    realm: window.location.hostname.split('.')[0],
+    auth: { type: 'temp-token' },
   });
-  return qb;
-}
+  qb.getApp({ appId: 'bpqe82s1' }).then((app) => console.log(app.name));
+</script>
 ```
 
-**Key behaviors:**
-- Authentication happens lazily on the first API call
-- 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)
+As a module: `import { createClient } from 'https://cdn.jsdelivr.net/npm/quickbase-js@2/dist/quickbase.esm.js'`.
 
-## Pagination
+[`examples/codepages`](examples/codepages) has a complete code page for each of vanilla web components, Alpine, Lit, Preact, Solid, React and Vue. Paste one into a new code page and it explores the app it's in.
 
-Paginated endpoints (`runQuery`, `runReport`, `getUsers`, etc.) return a `PaginatedRequest` that supports fluent pagination methods.
+## Common tasks
 
-### Default Behavior (Single Page)
+### Get every record from a table
 
 ```typescript
-// Returns first page only
-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
+const all = await qb.runQuery({ from: 'bqtable1' }).all();
+const first500 = await qb.runQuery({ from: 'bqtable1' }).paginate({ limit: 500 });
+const page = await qb.runQuery({ from: 'bqtable1' }); // one page
 ```
 
-### Fetch All Pages
+QuickBase returns a page at a time. `runQuery`, `runReport`, `getUsers` and the other paginated methods return one page when awaited, and follow the pages with `.all()` or `.paginate()`. Set `autoPaginate: true` on the client to make a plain `await` fetch them all.
 
-```typescript
-// Automatically fetches all pages and combines results
-const all = await qb.runQuery({ from: 'tableId' }).all();
-console.log(all.data.length); // 5000 records
-```
-
-### Fetch with Record Limit
+### Filter and sort
 
 ```typescript
-// Fetch up to 500 records (may span multiple pages)
-const limited = await qb.runQuery({ from: 'tableId' }).paginate({ limit: 500 });
-console.log(limited.data.length); // 500 records
+await qb.runQuery({
+  from: 'bqtable1',
+  select: [3, 6, 7],
+  where: '{6.GT.100}',
+  sortBy: [{ fieldId: 3, order: 'ASC' }],
+  options: { top: 100, skip: 0 },
+});
 ```
 
-### Explicit Single Page
+`where` uses QuickBase's [query syntax](https://help.quickbase.com/docs/components-of-a-query): `{field.OPERATOR.'value'}`, joined with `AND` and `OR`.
 
-```typescript
-// Explicitly fetch single page (useful when autoPaginate is enabled globally)
-const single = await qb.runQuery({ from: 'tableId' }).noPaginate();
-```
-
-### Global Auto-Pagination
+### Run a report
 
 ```typescript
-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 qb.runQuery({ from: 'tableId' });
-
-// Use .noPaginate() to get single page
-const page = await qb.runQuery({ from: 'tableId' }).noPaginate();
+const reportRows = await qb.runReport({ reportId: '7', tableId: 'bqtable1' }).all();
 ```
 
-## Date Conversion
+### Add or update records
 
-By default, ISO 8601 date strings in API responses are automatically converted to JavaScript `Date` objects:
+`upsert` adds records, or updates the one whose merge field matches (the key field, usually Record ID#, when you don't name one):
 
 ```typescript
-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 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
+const result = await qb.upsert({
+  to: 'bqtable1',
+  mergeFieldId: 9,
+  data: [{ '9': { value: 'EXT-001' }, '6': { value: 'Alpha' } }],
+  fieldsToReturn: [6],
 });
+console.log(result.metadata?.createdRecordIds, result.metadata?.updatedRecordIds);
 ```
 
-To disable date conversion and keep dates as strings:
+### Delete records
 
 ```typescript
-const qb = createClient({
-  realm: 'mycompany',
-  auth: { type: 'user-token', userToken: 'token' },
-  convertDates: false, // Keep dates as ISO strings
-});
+await qb.deleteRecords({ from: 'bqtable1', where: '{3.EX.123}' });
 ```
 
-## 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.
+### Use field names instead of IDs
 
-### Defining a Schema
+Give the client a schema and use your names anywhere an ID goes. Records come back keyed by name, with plain values:
 
 ```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,
-        },
-      },
-    },
-  },
+  schema: { tables: { projects: { id: 'bqw3ryzab', fields: { id: 3, name: 6, status: 7 } } } },
 });
-```
-
-### 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!
+  select: ['name', 'status'],
+  where: "{'status'.EX.'Active'}",
 });
-```
-
-### Generating Schema from QuickBase
+const first = result.data?.[0] as Record<string, unknown> | undefined; // TypeScript: keyed by name
+console.log(first?.name, first?.status);
 
-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"
+await qb.upsert({ to: 'projects', data: [{ name: 'Alpha', status: 'Active' }] });
 ```
 
-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:
+Generate the schema from your app instead of writing it, and regenerate with `--merge` when the app changes (your renamed aliases are kept):
 
 ```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
+npx quickbase-js schema -r mycompany -a bpqe82s1 -t "$QB_USER_TOKEN" -o schema.ts
 ```
 
-**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:
+A misspelled name throws with a suggestion (`Did you mean 'status'?`). Results are typed by field ID, which is why TypeScript needs the cast; the [schema guide](guides/schema-aliases.md) has the details.
 
-```
-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,
-      },
-    },
-  },
-};
-```
+### Read an app's tables and fields
 
-**client.ts**
 ```typescript
-import { createClient } from 'quickbase-js';
-import { schema } from './schema.js';
+const tables = await qb.getAppTables({ appId: 'bpqe82s1' });
+console.log(tables.map((t) => `${t.id} ${t.name}`));
 
-const qb = createClient({
-  realm: 'mycompany',
-  auth: { type: 'user-token', userToken: 'token' },
-  schema,
-});
+const fields = await qb.getFields({ tableId: 'bqtable1' });
+console.log(fields.map((f) => `${f.id} ${f.label} (${f.fieldType})`));
 ```
 
-Or use a JSON file:
+### Export and update a solution, download a file
 
-**schema.json**
-```json
-{
-  "tables": {
-    "projects": {
-      "id": "bqw3ryzab",
-      "fields": { "id": 3, "name": 6, "status": 7 }
-    }
-  }
-}
-```
+Solutions are QBL (YAML) and files are raw content, so these take and return text:
 
 ```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 qb = createClient({
-  // Required
-  realm: 'mycompany',
-  auth: { /* see authentication section */ },
-
-  // Optional
-  debug: false,                              // Enable debug logging
-  timeout: 30000,                            // Request timeout in ms
-  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: {
-    // Optional client-side throttling
-    // QuickBase allows 100 requests per 10 seconds per user token
-    proactiveThrottle: {
-      enabled: false,
-      requestsPer10Seconds: 100,
-    },
-
-    // Retry configuration for 429 and 5xx errors
-    retry: {
-      maxAttempts: 3,
-      initialDelayMs: 1000,
-      maxDelayMs: 30000,
-      multiplier: 2,
-    },
-
-    // Callback when rate limited
-    onRateLimit: (info) => {
-      console.log(`Rate limited! Retry after ${info.retryAfter}s`);
-      console.log(`Request: ${info.requestUrl}`);
-      console.log(`Ray ID: ${info.qbApiRay}`);
-    },
-  },
-});
+const qbl = await qb.exportSolution({ solutionId: 'solution-id' });
+await qb.updateSolution({ solutionId: 'solution-id' }, qbl);
+const file = await qb.downloadFile({ tableId: 'bqtable1', recordId: 12, fieldId: 8, versionNumber: 0 }); // base64
 ```
 
-## XML API (Legacy Endpoints)
+### Manage roles, groups and code pages
 
-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
+The JSON API doesn't cover these, so `createXmlClient(qb)` calls the XML API with the same authentication, retries, read-only mode and schema:
 
 ```typescript
-import { createClient, createXmlClient } from 'quickbase-js';
+import { 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})`);
-}
-```
-
-### Application Tokens
-
-Application tokens are an additional security layer for QuickBase apps. If an app has "Require Application Tokens" enabled, XML API calls must include a valid app token.
-
-**Important:** User tokens bypass app token checks entirely. You only need app tokens when:
-- Using ticket auth (`type: 'ticket'`) with the XML API
-- Using temp tokens (`type: 'temp-token'`) with the XML API
-- The target app has "Require Application Tokens" enabled
-
-The JSON API does not use app tokens.
-
-```typescript
-// Set app token at client level
-const qb = createClient({
-  realm: 'mycompany',
-  auth: { type: 'ticket', username: 'user@example.com', password: 'pass' },
-  appToken: 'your-app-token',  // Used by XML API only
-});
-
-const xml = createXmlClient(qb);
-const roles = await xml.getRoleInfo(appId);  // Includes app token
-
-// Or set it on the XML client directly
-const xmlWithToken = createXmlClient(qb, { appToken: 'your-app-token' });
-```
-
-### 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 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 qb.getAppTables({ appId: 'bpqe82s1' });
-const table = await qb.getTable({ appId: 'bpqe82s1', tableId: 'byyy82s1' });
-
-// Fields
-const fields = await qb.getFields({ tableId: 'byyy82s1' });
-
-// Records
-const records = await qb.runQuery({
-  from: 'byyy82s1',
-  select: [3, 6, 7],
-  where: "{6.GT.100}",
-  sortBy: [{ fieldId: 3, order: 'ASC' }],
-  options: { top: 100, skip: 0 },
-});
-
-// Insert/Update records (values are auto-wrapped)
-const result = await qb.upsert({
-  to: 'byyy82s1',
-  data: [
-    { '6': 'New Record', '7': 42 },
-  ],
-});
-
-// Delete records
-await qb.deleteRecords({
-  from: 'byyy82s1',
-  where: "{3.EX.123}",
-});
-
-// Reports
-const report = await qb.runReport(
-  { reportId: 'abc123', tableId: 'byyy82s1' },
-  { skip: 0, top: 100 }
-);
-
-// Users
-const users = await qb.getUsers(
-  { accountId: '123456' },
-  { appIds: ['bpqe82s1'] }
-);
-```
-
-### Raw Request
-
-For endpoints not covered by typed methods, use the generic `request` method:
-
-```typescript
-const result = await qb.request<MyResponseType>({
-  method: 'POST',
-  path: '/some/endpoint',
-  body: { key: 'value' },
-  query: { param: 'value' },
-});
-```
-
-## 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"
-  }
+  console.log(role.name, role.access.description);
 }
 ```
 
-### 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)"
-  }
-}
-```
+Every method is in the [XML API guide](guides/xml-api.md).
 
-## Error Handling
+### Call any endpoint directly
 
 ```typescript
-import {
-  QuickbaseError,
-  RateLimitError,
-  AuthenticationError,
-  AuthorizationError,
-  NotFoundError,
-  ValidationError,
-  ServerError,
-  QuickbaseTicketError,
-  QuickbaseAppTokenError,
-  QuickbaseXmlError,
-  ReadOnlyError,
-} from 'quickbase-js';
-
-try {
-  await qb.getApp({ appId: 'invalid' });
-} catch (error) {
-  if (error instanceof RateLimitError) {
-    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
-  } else if (error instanceof AuthenticationError) {
-    console.log('Invalid or expired token');
-  } else if (error instanceof QuickbaseTicketError) {
-    console.log('XML Ticket expired or invalid');
-  } else if (error instanceof QuickbaseAppTokenError) {
-    console.log('Missing or invalid App Token');
-  } else if (error instanceof QuickbaseXmlError) {
-    console.log(`XML API error ${error.code}: ${error.text}`);
-  } else if (error instanceof AuthorizationError) {
-    console.log('Permission denied');
-  } else if (error instanceof NotFoundError) {
-    console.log('Resource not found');
-  } else if (error instanceof ValidationError) {
-    console.log('Bad request:', error.message);
-  } else if (error instanceof ServerError) {
-    console.log('Server error:', error.statusCode);
-  } else if (error instanceof QuickbaseError) {
-    console.log(`API error ${error.statusCode}: ${error.message}`);
-  }
-}
+const result = await qb.request<{ id: string }>({ method: 'GET', path: '/apps/bpqe82s1' });
 ```
 
-## Rate Limiting
-
-QuickBase enforces a rate limit of **100 requests per 10 seconds** per user token. This SDK follows [QuickBase's official rate limiting guidance](https://developer.quickbase.com/rateLimit) — relying on server-side `Retry-After` headers by default, with optional client-side throttling.
+`request` uses the client's authentication, retries and throttling.
 
-### How 429 Errors Are Handled
+## Authentication
 
-When the SDK receives a 429 (Too Many Requests) response, it automatically:
+| `auth.type` | Use it for |
+|---|---|
+| `'user-token'` | Servers and scripts |
+| `'temp-token'` | Code pages and other browser code inside QuickBase |
+| `'ticket'` | A user signing in with their QuickBase email and password |
+| `'sso'` | A user signed in through your identity provider (SAML) |
 
-1. **Extracts rate limit info** from response headers (`Retry-After`, `cf-ray`, `qb-api-ray`)
-2. **Calls the `onRateLimit` callback** if configured, allowing you to log or monitor
-3. **Waits before retrying** - uses the `Retry-After` header if present, otherwise exponential backoff with jitter
-4. **Retries the request** up to `maxAttempts` times (default: 3)
-5. **Throws a `RateLimitError`** if all retries are exhausted
+Details are in the [authentication guide](guides/authentication.md).
 
-```
-Request fails with 429
-        ↓
-Extract Retry-After header
-        ↓
-Call onRateLimit callback (if set)
-        ↓
-Wait (Retry-After or exponential backoff)
-        ↓
-Retry request (up to maxAttempts)
-        ↓
-Throw RateLimitError if exhausted
-```
+## Rate limits and retries
 
-### Retry Configuration
+QuickBase allows 100 requests per 10 seconds per user token. The client retries 429s and server errors with exponential backoff, honoring `Retry-After`, and can throttle itself so it never hits the limit:
 
 ```typescript
-const qb = createClient({
+createClient({
   realm: 'mycompany',
   auth: { type: 'user-token', userToken: 'token' },
   rateLimit: {
-    retry: {
-      maxAttempts: 5,        // Default: 3
-      initialDelayMs: 1000,  // Default: 1000ms
-      maxDelayMs: 30000,     // Default: 30000ms
-      multiplier: 2,         // Default: 2
-    },
+    proactiveThrottle: { enabled: true, requestsPer10Seconds: 100 },
+    retry: { maxAttempts: 5 },
   },
 });
 ```
 
-The backoff formula with jitter: `delay = initialDelayMs * (multiplier ^ attempt) ± 10%`
+Timeouts, backoff settings and a rate-limit callback are in the [reliability guide](guides/reliability.md).
 
-### Proactive Throttling
+## Errors
 
-Prevent 429 errors entirely by throttling requests client-side using a sliding window algorithm:
+Every error extends `QuickbaseError`, with a class for each kind of failure:
 
 ```typescript
-const qb = createClient({
-  realm: 'mycompany',
-  auth: { type: 'user-token', userToken: 'token' },
-  rateLimit: {
-    proactiveThrottle: {
-      enabled: true,
-      requestsPer10Seconds: 100,
-    },
-  },
-});
-```
-
-This tracks request timestamps and blocks new requests when the limit would be exceeded, waiting until the oldest request exits the 10-second window.
-
-### Rate Limit Callback
-
-Get notified when rate limited (called before retry):
-
-```typescript
-const qb = createClient({
-  realm: 'mycompany',
-  auth: { type: 'user-token', userToken: 'token' },
-  rateLimit: {
-    onRateLimit: (info) => {
-      console.log(`Rate limited on ${info.requestUrl}`);
-      console.log(`Retry after: ${info.retryAfter} seconds`);
-      console.log(`Ray ID: ${info.qbApiRay}`);
-      console.log(`Attempt: ${info.attempt}`);
-    },
-  },
-});
-```
-
-### Handling RateLimitError
-
-If retries are exhausted, a `RateLimitError` is thrown:
-
-```typescript
-import { RateLimitError } from 'quickbase-js';
+import { RateLimitError, NotFoundError, ReadOnlyError, QuickbaseError } from 'quickbase-js';
 
 try {
   await qb.getApp({ appId: 'bpqe82s1' });
 } catch (error) {
   if (error instanceof RateLimitError) {
-    console.log(`Rate limited after ${error.rateLimitInfo.attempt} attempts`);
-    console.log(`Retry after: ${error.retryAfter} seconds`);
+    console.log(`rate limited; retry after ${error.retryAfter}s`);
+  } else if (error instanceof NotFoundError) {
+    console.log('no such app');
+  } else if (error instanceof ReadOnlyError) {
+    console.log(`write blocked: ${error.method} ${error.path}`);
+  } else if (error instanceof QuickbaseError) {
+    console.log(`QuickBase error ${error.statusCode}: ${error.message}`);
   }
 }
 ```
 
-## Migration from v1
+| Class | Status |
+|---|---|
+| `ValidationError` | 400 |
+| `AuthenticationError` | 401 |
+| `AuthorizationError` | 403 |
+| `NotFoundError` | 404 |
+| `RateLimitError` | 429 |
+| `ServerError` | 5xx |
+| `ReadOnlyError` | a write blocked by `readOnly: true` |
 
-### Authentication
+The XML API adds `QuickbaseTicketError`, `QuickbaseAppTokenError` and `QuickbaseXmlError`.
 
-```typescript
-// v1 - user token
-const qb = quickbase({ realm: 'company', userToken: 'token' });
+## Other options
 
-// v2 - user token (explicit type)
-const qb = createClient({
-  realm: 'company',
-  auth: { type: 'user-token', userToken: 'token' },
-});
+- **`readOnly: true`** refuses every write before it is sent, in both APIs. Reads sent as POST (`runQuery`, `runReport`, `audit`) still work.
+- **Dates**: ISO date strings in responses become `Date` objects. The types say `string`, because QuickBase's spec marks few date fields; set `convertDates: false` to keep strings.
+- **Requirements**: Node.js 18 or later, or any modern browser. The package is ES modules; the browser bundle also defines a `QuickBase` global.
 
-// v1 - temp tokens in Code Pages
-const qb = quickbase({ realm: 'company', useTempTokens: true });
+## Documentation
 
-// v2 - temp tokens in Code Pages
-const qb = createClient({
-  realm: 'company',
-  auth: { type: 'temp-token' },
-});
-```
-
-### Pagination
-
-```typescript
-// v1 - callback-based
-await qb.withPaginationDisabled(async () => qb.runQuery({ body: { from: tableId } }));
-await qb.withPaginationLimit(100, async () => qb.runQuery({ body: { from: tableId } }));
-
-// v2 - fluent API
-await qb.runQuery({ from: tableId }).noPaginate();
-await qb.runQuery({ from: tableId }).paginate({ limit: 100 });
-```
-
-### Request Body
-
-```typescript
-// v1 - body wrapper
-await qb.runQuery({ body: { from: tableId, select: [3, 6] } });
-
-// v2 - direct parameters
-await qb.runQuery({ from: tableId, select: [3, 6] });
-```
+- Guides: [queries and pagination](guides/queries.md), [schema aliases](guides/schema-aliases.md), [authentication](guides/authentication.md), [rate limits and retries](guides/reliability.md), [the XML API](guides/xml-api.md), [migrating from v1](guides/migration.md)
+- [API reference](https://drewbradfordxyz.github.io/quickbase-js/): every method, with QuickBase's descriptions
+- [CHANGELOG](CHANGELOG.md)
 
 ## Development
 
 ```bash
-# Clone with submodules (includes OpenAPI spec)
 git clone --recurse-submodules https://github.com/DrewBradfordXYZ/quickbase-js.git
-
-# Or if already cloned, initialize submodules
-git submodule update --init
-
-# Install dependencies
 npm install
-
-# Run tests
-npm test
-
-# Build
-npm run build
-
-# Type check
-npm run typecheck
-
-# Generate types from OpenAPI spec
-npm run spec:generate
+npm test           # unit tests
+npm run typecheck  # the library, and the docs' examples
+npm run spec:build # regenerate the types from the pinned spec in spec/
 ```
 
-### Updating the OpenAPI Spec
-
-The `spec/` directory is a Git submodule pointing to [quickbase-spec](https://github.com/DrewBradfordXYZ/quickbase-spec). Each SDK pins to a specific commit, so spec updates are controlled:
+`spec/` is a submodule of [quickbase-spec](https://github.com/DrewBradfordXYZ/quickbase-spec), and CI fails when the generated types don't match it. The code in this README and `guides/` comes from `examples/docs.ts`, which `npm run typecheck` checks; change them together.
 
-```bash
-# Update to latest spec
-cd spec
-git pull origin main
-cd ..
-git add spec
-git commit -m "Update quickbase-spec submodule"
-
-# Regenerate types
-npm run spec:generate
-```
-
-### Spec Tools
-
-```bash
-# Full spec processing pipeline
-npm run spec:build
-
-# Individual steps
-npm run spec:convert   # Swagger 2.0 → OpenAPI 3.0
-npm run spec:patch     # Apply fixes from overrides
-npm run spec:validate  # Validate spec
-npm run spec:split     # Split by tag (for editing)
-npm run spec:generate  # Generate TypeScript types
-```
-
-### Documentation
-
-API documentation is auto-generated from source code and hosted at:
-**https://drewbradfordxyz.github.io/quickbase-js/**
-
-To generate docs locally:
-
-```bash
-npm run docs        # Generate docs to ./docs
-npm run docs:watch  # Watch mode for development
-```
+## Related
 
-Documentation is built with [TypeDoc](https://typedoc.org/) and auto-deployed to GitHub Pages on every push to main.
+- [quickbase-go](https://github.com/DrewBradfordXYZ/quickbase-go): the Go SDK, from the same spec
 
 ## License