### Airtable.js Quick Start Example

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/README.md

Demonstrates basic usage of the Airtable.js library, including configuration, accessing a base and table, creating, querying, updating, and deleting records.

```javascript
const Airtable = require('airtable');

Airtable.configure({ apiKey: 'YOUR_API_KEY' });

const base = Airtable.base('appXXXXXX');
const table = base('TableName');

const records = await table.create([
  { Name: 'Alice', Email: 'alice@example.com' },
  { Name: 'Bob', Email: 'bob@example.com' }
]);

const results = await table.select({
  filterByFormula: "{Status} = 'Active'",
  sort: [{ field: 'Name', direction: 'asc' }]
}).all();

await records[0].patchUpdate({ Status: 'Active' });

await records[0].destroy();
```

--------------------------------

### Airtable.js 5-Minute Start

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/START-HERE.md

This snippet demonstrates the basic setup and common operations for interacting with Airtable using Airtable.js. It covers API key configuration, base and table selection, and performing create, update, and delete actions.

```javascript
const Airtable = require('airtable');

// 1. Configure (or use env var AIRTABLE_API_KEY)
Airtable.configure({ apiKey: 'pat...' });

// 2. Get a base
const base = Airtable.base('appXXXXXX');

// 3. Get a table
const table = base('TableName');

// 4. Do something
const records = await table.select().all();
console.log(records.length, 'records');

// 5. Create
const created = await table.create({ Name: 'Alice' });

// 6. Update
await created.patchUpdate({ Status: 'Active' });

// 7. Delete
await created.destroy();
```

--------------------------------

### Example Query with Sorting

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/types.md

This example demonstrates how to construct a query with multiple sort parameters, ordering records first by 'Name' in ascending order and then by 'Created' in descending order.

```typescript
const query = table.select({
  sort: [
    { field: 'Name', direction: 'asc' },
    { field: 'Created', direction: 'desc' }
  ]
});
```

--------------------------------

### Install Airtable.js with npm

Source: https://github.com/airtable/airtable.js/blob/master/README.md

Install the Airtable.js library in your Node.js project using npm. Compatible with Node 10 and above.

```sh
npm install airtable
```

--------------------------------

### Complete Example: Sync Contacts

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/README.md

This example demonstrates how to synchronize contact data with Airtable. It fetches existing records, creates new ones, and updates existing ones based on email addresses.

```javascript
const Airtable = require('airtable');

// Configure
Airtable.configure({
  apiKey: process.env.AIRTABLE_API_KEY
});

// Define schema
const table = Airtable.base('appXXXXXX')('Contacts');

// Example: Sync contacts
async function syncContacts(newContacts) {
  try {
    // Fetch existing
    const existing = await table.select().all();
    const emails = new Set(existing.map(r => r.fields.Email));

    // Create new ones
    const toCreate = newContacts.filter(c => !emails.has(c.email));
    if (toCreate.length > 0) {
      const created = await table.create(
        toCreate.map(c => ({ Email: c.email, Name: c.name }))
      );
      console.log(`Created ${created.length} records`);
    }

    // Update existing
    for (const contact of newContacts) {
      const record = existing.find(r => r.fields.Email === contact.email);
      if (record && record.fields.Name !== contact.name) {
        await record.patchUpdate({ Name: contact.name });
      }
    }

    console.log('Sync complete');
  } catch (err) {
    console.error('Sync failed:', err.message);
  }
}
```

--------------------------------

### Complete Usage Timeline

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/API-SURFACE.md

A step-by-step guide illustrating the typical workflow for using the Airtable.js SDK, from initialization to data manipulation.

```APIDOC
## Complete Usage Timeline

1. **Import** → `const Airtable = require('airtable')`
2. **Configure** → `Airtable.configure({apiKey: '...'})`
3. **Access Base** → `const base = Airtable.base('appXXXXXX')`
4. **Access Table** → `const table = base('TableName')`
5. **Query** → `await table.select({...}).all()`
6. **Create** → `await table.create({...})`
7. **Update** → `await record.patchUpdate({...})`
8. **Delete** → `await record.destroy()`
```

--------------------------------

### Example RecordData for a Contact

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/types.md

This example shows how to create a RecordData object conforming to the ContactFields interface, including a record ID and partial field data.

```typescript
const recordData: RecordData<ContactFields> = {
  id: 'recXXXXXX',
  fields: {
    Name: 'John Doe',
    Email: 'john@example.com'
  },
  commentCount: 2
};
```

--------------------------------

### Select All Records

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/query.md

A basic example to select and retrieve all records from a table. Ensure the table name is correctly specified.

```javascript
const table = base('Contacts');
const records = await table.select().all();

```

--------------------------------

### Initialize Airtable and Load Artists

Source: https://github.com/airtable/airtable.js/blob/master/test/test_files/index.html

Sets up the Airtable base connection and defines functions for loading and deleting artists. This is the initial setup for the application.

```javascript
var Airtable = require('airtable');
var base = new Airtable({ apiKey: 'FILL_OUT_API_KEY' }).base('FILL_OUT_BASE_ID');

var deleteArtist = function(record) {
  record.destroy(function(err) {
    if (err) {
      console.log('Error destroying ', recordId, err);
    } else {
      console.log('Destroyed ', record.getId());
      $('div[data-record-id="'+record.getId()+'"]\[data-record-id="'+record.getId()+'"].remove();
    }
  });
};

var loadArtists = function() {
  $('#artists').empty();
  base('Artists').select({
    sort: [ {field: 'Name', direction: 'asc'} ]
  }).eachPage(function page(records, fetchNextPage) {
    records.forEach(function(record) {
      console.log('Retrieved ', record.get('Name'));
      var $artistInfo = $('<div>');
      $artistInfo.append($('<h3>').text(record.get('Name')));
      $artistInfo.append($('<div>').text(record.get('Bio')));
      var x = $('<button>').text('Delete').click(function() {
        deleteArtist(record);
      });
      $artistInfo.append(x)
      $artistInfo.attr('data-record-id', record.getId());
      $('#artists').append($artistInfo);
    });
    fetchNextPage();
  }, function done(error) {
    console.log(error);
  });
};
```

--------------------------------

### Example FieldSet for Contact Records

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/types.md

This example demonstrates how to extend the FieldSet interface to define specific fields for a 'Contacts' table, including various data types and arrays.

```typescript
interface ContactFields extends FieldSet {
  Name: string;
  Email: string;
  Phone: string;
  Age: number;
  Active: boolean;
  Managers: Collaborator[];
  Tags: string[];
  Attachments: Attachment[];
}

const table = base<ContactFields>('Contacts');
```

--------------------------------

### Create Airtable Instance with API Key

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/configuration.md

Shows the correct way to instantiate the Airtable client by providing a valid API key during configuration. This is the basic setup for authenticated access.

```javascript
// Valid configuration
const airtable = new Airtable({
  apiKey: 'pat...'
});
```

--------------------------------

### Complete Airtable Record Operations Example

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/record.md

Illustrates a full workflow including finding, updating, patching, fetching, and deleting an Airtable record.

```javascript
const Airtable = require('airtable');

Airtable.configure({ apiKey: 'YOUR_API_KEY' });
const table = Airtable.base('appXXXXXX')('ContactsTable');

async function example() {
  // Find a record
  const record = await table.find('recXXXXXX');
  console.log('Name:', record.get('Name'));
  console.log('Email:', record.get('Email'));

  // Update fields locally and save
  record.set('Status', 'Active');
  await record.save();

  // Patch update (merge)
  await record.patchUpdate({
    'LastContact': new Date().toISOString()
  });

  // Refresh data from server
  await record.fetch();

  // Delete the record
  await record.destroy();
}
```

--------------------------------

### Airtable.js Complete Usage Timeline

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/API-SURFACE.md

A step-by-step guide to using the Airtable.js library, from initial import and configuration to accessing bases and tables, performing queries, and managing records through creation, update, and deletion.

```javascript
const Airtable = require('airtable')
Airtable.configure({apiKey: '...'})
```

```javascript
const base = Airtable.base('appXXXXXX')
```

```javascript
const table = base('TableName')
```

```javascript
await table.select({...}).all()
```

```javascript
await table.create({...})
```

```javascript
await record.patchUpdate({...})
```

```javascript
await record.destroy()
```

--------------------------------

### Airtable Formula Syntax Examples

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/query.md

Examples of common Airtable formula patterns that can be used with the `filterByFormula` parameter.

```APIDOC
## Airtable Formula Syntax

The `filterByFormula` parameter accepts Airtable's formula language. Common patterns:

```javascript
// Equality
"{Status} = 'Active'"

// AND/OR
"AND({Status} = 'Active', {Score} > 50)"
"OR({Priority} = 'High', {Urgent} = TRUE())"

// Greater/Less than
"{Score} > 80"
"{CreatedDate} < NOW()"

// Contains
"FIND('keyword', {Description}) > 0"

// Is not empty
"{Email} != ''"

// Complex
"AND({Status} = 'Active', OR({Score} > 80, {VIP} = TRUE()))"
```
```

--------------------------------

### Iterate Through Records

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/types.md

This example demonstrates how to fetch all records for a table and iterate through them, accessing field data using the Records type.

```typescript
const records: Records<ContactFields> = await table.select().all();
records.forEach(record => {
  console.log(record.fields.Name);
});
```

--------------------------------

### Configuring Airtable Client Instance

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/types.md

Example of creating a new Airtable client instance with custom configuration options, including API key, endpoint URL, request timeout, and custom headers.

```typescript
const airtable = new Airtable({
  apiKey: 'pat...',
  endpointUrl: 'https://api-proxy.example.com',
  requestTimeout: 10000,
  customHeaders: { 'X-Custom-Header': 'value' }
});
```

--------------------------------

### Airtable Configuration Precedence Example

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/configuration.md

Demonstrates the order of configuration precedence: constructor options override static configuration, which overrides environment variables. An API key is always required.

```javascript
// Set static config
Airtable.configure({
  apiKey: 'static-key',
  requestTimeout: 5000
});

// Constructor overrides static config
const airtable = new Airtable({
  apiKey: 'instance-key',  // Uses this
  // requestTimeout: not set, uses static: 5000
});

// Reading from environment
process.env.AIRTABLE_API_KEY = 'env-key';
const airtable2 = new Airtable();
// apiKey from env: 'env-key' (static config takes precedence)

// No config anywhere - error
const airtable3 = new Airtable();
// Error: An API key is required to connect to Airtable
```

--------------------------------

### Get Field Value

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/record.md

Demonstrates how to retrieve the value of a specific field from a record object using the get() method. Ensure the record is fetched first.

```javascript
const record = await table.find('recXXXXXX');
const name = record.get('Name');
const email = record.get('Email');
```

--------------------------------

### Airtable Formula Syntax Examples

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/query.md

Illustrates common Airtable formula patterns used with the `filterByFormula` parameter. These examples cover equality, logical operators, comparisons, string searching, and complex conditions.

```javascript
" {Status} = 'Active'"
```

```javascript
"AND({Status} = 'Active', {Score} > 50)"
```

```javascript
"OR({Priority} = 'High', {Urgent} = TRUE())"
```

```javascript
" {Score} > 80"
```

```javascript
" {CreatedDate} < NOW()"
```

```javascript
"FIND('keyword', {Description}) > 0"
```

```javascript
" {Email} != ''"
```

```javascript
"AND({Status} = 'Active', OR({Score} > 80, {VIP} = TRUE()))"
```

--------------------------------

### Accessing a Base

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/README.md

Get a Base instance to interact with a specific Airtable base.

```APIDOC
## Access Base

### Description
Obtain a Base instance by providing the base ID. This serves as an access point to a specific Airtable base.

### Method
`airtable.base(baseId)`

### Parameters
- **baseId** (string) - Required - The ID of the Airtable base.

### Request Example
```javascript
const base = airtable.base('appXXXXXX');
```
```

--------------------------------

### Select Records with Sorting

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/query.md

Order the retrieved records based on one or more fields. This example sorts by 'Name' in ascending order and then by 'Created' in descending order.

```javascript
const table = base('Contacts');
const records = await table.select({
  sort: [
    { field: 'Name', direction: 'asc' },
    { field: 'Created', direction: 'desc' }
  ]
}).all();

```

--------------------------------

### Select Records with Pagination

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/query.md

Control the number of records returned per request using `pageSize` and set an overall limit with `maxRecords`. This example fetches records in pages of 10, up to a maximum of 100.

```javascript
const table = base('Contacts');
const records = await table.select({
  pageSize: 10,
  maxRecords: 100
}).all();

```

--------------------------------

### Accessing Attachment Thumbnails

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/types.md

Example of how to access and log the URLs of different thumbnail sizes for an image attachment. Requires the attachment to have thumbnails.

```typescript
const attachment = record.fields.ProfilePhoto[0];
if (attachment.thumbnails) {
  console.log(`Small: ${attachment.thumbnails.small.url}`);
  console.log(`Large: ${attachment.thumbnails.large.url}`);
}
```

--------------------------------

### Accessing a Table using Base.table() Method

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/base.md

Instantiate a Base and use the `table()` method with the table name to get a Table object. This is an alternative to calling the base directly.

```javascript
const base = Airtable.base('appXXXXXX');
const table = base.table('MyTable');
```

--------------------------------

### Production Configuration with Multiple Bases

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/configuration.md

Configure Airtable.js for production use, setting global configurations like API key and request timeout. This example shows how to access multiple bases.

```javascript
const Airtable = require('airtable');

Airtable.configure({
  apiKey: process.env.AIRTABLE_API_KEY,
  requestTimeout: 30000,
  noRetryIfRateLimited: false
});

const crm = Airtable.base(process.env.CRM_BASE_ID);
const analytics = Airtable.base(process.env.ANALYTICS_BASE_ID);
const warehouse = Airtable.base(process.env.WAREHOUSE_BASE_ID);
```

--------------------------------

### Handling Authentication and Authorization Errors

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/errors.md

Example of catching specific authentication errors like AUTHENTICATION_REQUIRED and NOT_AUTHORIZED. This helps in providing user-friendly feedback for invalid credentials or permissions.

```javascript
try {
  const airtable = new Airtable({ apiKey: 'invalid_key' });
  const base = airtable.base('appXXXXXX');
  await base('Table').find('recXXXXXX');
} catch (err) {
  if (err.error === 'AUTHENTICATION_REQUIRED') {
    console.error('Invalid API key');
  } else if (err.error === 'NOT_AUTHORIZED') {
    console.error('No access to this base');
  }
}
```

--------------------------------

### Task Fields with Collaborator

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/types.md

Example interface extending FieldSet to include a single Collaborator and an array of Collaborators for task management.

```typescript
interface TaskFields extends FieldSet {
  Title: string;
  Assignee: Collaborator;
  Collaborators: Collaborator[];
}
```

--------------------------------

### Document Fields with Attachment

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/types.md

Example interface extending FieldSet to include an array of Attachments for document management. Demonstrates iterating through files and accessing their properties.

```typescript
interface DocumentFields extends FieldSet {
  Title: string;
  Files: Attachment[];
}

const record = await table.find('recXXXXXX');
record.fields.Files.forEach(file => {
  console.log(`${file.filename} (${file.size} bytes)`);
  console.log(`Download: ${file.url}`);
  if (file.thumbnails) {
    console.log(`Thumbnail: ${file.thumbnails.large.url}`);
  }
});
```

--------------------------------

### Accessing a Table using Base Function Call

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/base.md

Instantiate a Base and then call it like a function with the table name to get a Table object. Requires Airtable configuration and base initialization.

```javascript
const Airtable = require('airtable');
Airtable.configure({ apiKey: 'YOUR_API_KEY' });

const base = Airtable.base('appXXXXXX');
const table = base('MyTable');
```

--------------------------------

### Batch Update Records

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/START-HERE.md

Provides an example of how to efficiently update multiple records in a table simultaneously by providing an array of record objects with their IDs and updated fields.

```javascript
await table.update([
  { id: 'rec1', fields: { Status: 'Done' } },
  { id: 'rec2', fields: { Status: 'Done' } }
]);
```

--------------------------------

### Select Specific Fields

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/query.md

Retrieve only a subset of fields for each record using the `fields` option. This example selects 'Name' and 'Email' for active contacts.

```javascript
const table = base('Contacts');
const records = await table.select({
  fields: ['Name', 'Email'],
  filterByFormula: "{Status} = 'Active'"
}).all();

```

--------------------------------

### Handle Bulk Operation Partial Failure

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/errors.md

Note that if any record in a bulk create operation is invalid, the entire batch will fail. This example shows how to catch the error for the whole batch.

```javascript
try {
  const results = await table.create([
    { Title: 'Valid' },
    { Title: 'Also Valid' }
  ]);
  console.log(`Created ${results.length} records`);
} catch (err) {
  // The entire batch fails if any record is invalid
  console.error('Batch failed:', err.message);
}
```

--------------------------------

### Development Configuration with Local API Key

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/configuration.md

Configure Airtable.js for local development using a .env file for the API key. Ensure you have the 'dotenv' package installed.

```javascript
// .env file
AIRTABLE_API_KEY=patXXXXXXXXXXXXXX

// JavaScript
require('dotenv').config();
const Airtable = require('airtable');
const airtable = new Airtable();
const base = airtable.base('appXXXXXX');
```

--------------------------------

### Sync Records from External Source

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/START-HERE.md

Shows how to fetch all existing records from a table and then create new records using the fetched data.

```javascript
const existing = await table.select().all();
const newRecords = await table.create(data);
```

--------------------------------

### Create and Use Table Select Query

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/table.md

Instantiate a table and create a select query. Use this to fetch records with optional filters, sorting, and pagination. The `all()` method fetches all matching records across all pages.

```javascript
const table = base('MyTable');

// Simple select
const query = table.select();

// With filters and sorting
const query = table.select({
  maxRecords: 100,
  pageSize: 25,
  filterByFormula: '{Status} = "Active"',
  sort: [
    { field: 'Name', direction: 'asc' }
  ],
  fields: ['Name', 'Email', 'Status']
});

// Fetch all pages
query.all().then(records => {
  console.log(`Found ${records.length} records`);
});
```

--------------------------------

### Constructor

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/query.md

Creates a Query instance. Typically created through `table.select()`.

```APIDOC
## Constructor

Creates a Query instance. Typically created through `table.select()`.

### Parameters
#### Path Parameters
- **table** (`Table<TFields>`) - Required - Parent table instance
- **params** (`QueryParams<TFields>`) - Required - Validated query parameters
```

--------------------------------

### get Field Value

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/record.md

Retrieves the value of a specific field from the record.

```APIDOC
## get<Field extends keyof TFields>(columnName: Field): TFields[Field]

Gets the value of a field.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| columnName | `keyof TFields` | Yes | Field name |

**Returns:** The field value

**Example:**

```javascript
const record = await table.find('recXXXXXX');
const name = record.get('Name');
const email = record.get('Email');
```
```

--------------------------------

### Airtable Instance Creation and Configuration

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/README.md

Methods for initializing the Airtable SDK and configuring global settings.

```APIDOC
## Airtable Class

### `new Airtable(options)`

#### Description
Creates a new instance of the Airtable client.

#### Returns
- Instance: The newly created Airtable instance.

### `configure(options)`

#### Description
Sets global configuration options for all Airtable instances.

#### Returns
- void

```

--------------------------------

### Get Record ID

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/record.md

Retrieves the unique identifier for a given Airtable record.

```javascript
const record = await table.find('recXXXXXX');
console.log(record.getId()); // 'recXXXXXX'
```

--------------------------------

### Accessing a Table

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/README.md

Get a Table instance to interact with records within a specific table.

```APIDOC
## Access Table

### Description
Get a Table instance by providing the table name. This allows interaction with records in a specific table within a base.

### Method
`base(tableName)`

### Parameters
- **tableName** (string) - Required - The name of the table.

### Request Example
```javascript
const table = base('TableName');
```
```

--------------------------------

### Initialize Airtable Instance

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/README.md

Create a top-level Airtable client instance. Requires an API key.

```javascript
const airtable = new Airtable({ apiKey: 'pat...' });
```

--------------------------------

### Getting the Base ID

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/base.md

Retrieve the unique identifier for the current Airtable base instance.

```APIDOC
## getId(): string

### Description
Returns the base ID for this base instance.

### Returns
`string` — The base ID

### Example
```javascript
const base = Airtable.base('appXXXXXX');
console.log(base.getId()); // 'appXXXXXX'
```
```

--------------------------------

### get(fieldName)

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/record.md

Retrieves the value of a specific field from the record. Supports type safety with generics.

```APIDOC
## get(fieldName: string)

### Description
Retrieves the value of a specific field from the record.

### Method
`record.get(fieldName)`

### Parameters
#### Path Parameters
- **fieldName** (string) - Required - The name of the field to retrieve.

### Request Example
```typescript
// With type safety
interface MyFields {
  Name: string;
}
const record = await table<MyFields>.find('recXXXXXX');
const name: string = record.get('Name');
```

### Response
#### Success Response
- **field value** (any) - The value of the specified field.

#### Response Example
(See Request Example)
```

--------------------------------

### Access a Specific Table

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/README.md

Get a Table instance to access records within a specific table in a base.

```javascript
const table = base('TableName');
```

--------------------------------

### Instantiate Airtable Client

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/airtable.md

Create a new Airtable client instance with configuration options. Ensure an API key is provided either through options, static configuration, or environment variables.

```javascript
const Airtable = require('airtable');

// Using instance with options
const airtable = new Airtable({
  apiKey: 'YOUR_API_KEY',
  endpointUrl: 'https://api.airtable.com',
  requestTimeout: 5000
});

// Using static base method
const base = airtable.base('appXXXXXX');
```

--------------------------------

### Airtable Instance Initialization

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/README.md

Initialize a new Airtable instance with your API key.

```APIDOC
## Initialize Airtable Instance

### Description
Create a top-level Airtable client instance using your API key.

### Method
`new Airtable(options)`

### Parameters
- **options** (object) - Required - Configuration options.
  - **apiKey** (string) - Required - Your Airtable API key.

### Request Example
```javascript
const airtable = new Airtable({ apiKey: 'pat...' });
```
```

--------------------------------

### Getting the Base ID

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/base.md

Retrieve the unique identifier for the current Airtable base instance using the `getId()` method.

```javascript
const base = Airtable.base('appXXXXXX');
console.log(base.getId()); // 'appXXXXXX'
```

--------------------------------

### Promise vs. Callback API Usage

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/record.md

Demonstrates how to use the save method with both promise-based and callback-based approaches.

```javascript
// Using promises
record.save().then(updatedRecord => { ... });

// Using callbacks
record.save((error, updatedRecord) => { ... });
```

--------------------------------

### Initialize Airtable with Environment API Key

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/configuration.md

Initializes a new Airtable instance, reading the API key from the AIRTABLE_API_KEY environment variable if not explicitly provided.

```javascript
// Reads AIRTABLE_API_KEY from environment
const airtable = new Airtable();
```

--------------------------------

### Airtable.base(baseId)

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/airtable.md

Static convenience method to get a base without instantiating Airtable. Uses configured global settings.

```APIDOC
## Airtable.base(baseId: string): Airtable.Base

### Description
Static convenience method to get a base without instantiating Airtable. Uses configured global settings.

### Method
Static method

### Endpoint
N/A (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **baseId** (string) - Required - The Airtable base ID.

### Request Example
```javascript
Airtable.configure({ apiKey: 'YOUR_API_KEY' });
const base = Airtable.base('appXXXXXX');
const table = base('TableName');
```

### Response
#### Success Response (200)
- **Airtable.Base** - A base functor object

#### Response Example
```javascript
// Returns a base object that can be used to access tables
```
```

--------------------------------

### Instance Configuration with Constructor Options

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/configuration.md

Configure a specific Airtable instance by passing options directly to the constructor. This method has the highest priority.

```javascript
const airtable = new Airtable({
  apiKey: 'pat...',
  endpointUrl: 'https://api.airtable.com',
  requestTimeout: 5000,
  customHeaders: { 'X-Custom': 'value' },
  noRetryIfRateLimited: false,
  apiVersion: '0.1.0'
});
```

--------------------------------

### Airtable Class Instance Creation and Methods

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/API-SURFACE.md

Instantiate the Airtable class with options to configure your connection. Use the `base()` method on an instance to interact with a specific Airtable base.

```typescript
new Airtable(opts?: AirtableOptions)

instance.base(baseId: string): Base
```

--------------------------------

### Securely Load Airtable API Key using Environment Variables

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/configuration.md

Demonstrates a secure pattern for managing API keys by loading them from environment variables using dotenv. This prevents hardcoding sensitive credentials.

```bash
# .env (git ignored)
AIRTABLE_API_KEY=pat...
```

```javascript
# JavaScript
require('dotenv').config();
const airtable = new Airtable({
  apiKey: process.env.AIRTABLE_API_KEY
});
```

--------------------------------

### Update Record (Put)

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/README.md

Completely replace a record's fields with new data. Use `find` to get the record first.

```javascript
// Replace (put)
await record.putUpdate({ Name: 'New Name' });
```

--------------------------------

### Query Instance Methods

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/API-SURFACE.md

Methods for performing queries and retrieving multiple records.

```APIDOC
## Query Instance Methods

### firstPage(): Promise<Records<TFields>>

Fetches the first page of records matching the query.

### firstPage(done: (err, records) => void): void

Fetches the first page of records matching the query with a callback.

### all(): Promise<Records<TFields>>

Fetches all records matching the query.

### all(done: (err, records) => void): void

Fetches all records matching the query with a callback.

### eachPage(pageCallback: (records: Records<TFields>, fetchNext: () => void) => void): Promise<void>

Iterates over all pages of records matching the query, executing a callback for each page.

### eachPage(pageCallback: (records: Records<TFields>, fetchNext: () => void) => void, done: (error?: Error) => void): void

Iterates over all pages of records matching the query with a callback for each page and a final completion callback.
```

--------------------------------

### Update Record (Patch)

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/README.md

Partially update a record by merging new data with existing fields. Use `find` to get the record first.

```javascript
// Merge (patch)
const record = await table.find('recXXXXXX');
await record.patchUpdate({ Status: 'Active' });
```

--------------------------------

### Record Constructor

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/record.md

Initializes a new Record instance. This is typically handled internally by table methods like `find()` or `create()`.

```APIDOC
## Constructor

```typescript
constructor(table: Table<TFields>, recordId: string, recordJson?: any)
```

Creates a record instance. Typically created through table methods like `find()` or `create()`.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| table | `Table<TFields>` | Yes | Parent table instance |
| recordId | `string` | Yes | Record ID |
| recordJson | `object` | No | Optional record data from API response |
```

--------------------------------

### Fetch First Page of Records

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/query.md

Fetches the first page of records matching the query. Use this when you only need a subset of the data or the initial batch.

```javascript
const table = base('MyTable');
const query = table.select({ maxRecords: 25 });

const records = await query.firstPage();
console.log(`Found ${records.length} records`);
```

--------------------------------

### Record Constructor

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/record.md

Illustrates the signature for creating a Record instance. Records are usually obtained through table methods like find() or create().

```typescript
constructor(table: Table<TFields>, recordId: string, recordJson?: any)
```

--------------------------------

### Get Airtable Base Object

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/airtable.md

Obtain a Base object for a specific Airtable base ID. This object can then be used to interact with tables within that base.

```javascript
const airtable = new Airtable({ apiKey: 'YOUR_API_KEY' });
const base = airtable.base('appXXXXXX');
const table = base('TableName');
```

--------------------------------

### Callback vs Promise API Usage

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/query.md

Demonstrates how to fetch data using both promise-based and callback-based APIs for Airtable queries. Choose the style that best fits your project's asynchronous handling.

```javascript
// Using promises
table.select().firstPage().then(records => { ... });
```

```javascript
// Using callbacks
table.select().firstPage((error, records) => { ... });
```

--------------------------------

### List All Records

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/README.md

Use this pattern to retrieve all records from a table. Ensure you have initialized the base and table objects.

```javascript
const table = base('Contacts');
const records = await table.select().all();
```

--------------------------------

### Handling Unprocessable Entity Errors

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/errors.md

Example for catching UNPROCESSABLE_ENTITY errors, which indicate invalid field values being sent to the API. This requires validation of data before submission.

```javascript
try {
  // Invalid date format
  await table.create({
    Title: 'Task',
    DueDate: 'invalid-date'
  });
} catch (err) {
  if (err.error === 'UNPROCESSABLE_ENTITY') {
    console.error('Invalid field value:', err.message);
  }
}
```

--------------------------------

### Airtable Constructor

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/airtable.md

Initializes a new Airtable client instance. Configuration options can be provided to customize the client's behavior, such as API key, endpoint URL, and request timeout. An API key is mandatory.

```APIDOC
## Constructor Airtable

### Description
Creates a new Airtable client instance with the specified options.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **opts** (`Airtable.AirtableOptions`) - Optional - Configuration options for this instance.

### Throws
Throws `Error` if no API key is provided through opts, static configuration, or environment variable.

### Example
```javascript
const Airtable = require('airtable');

const airtable = new Airtable({
  apiKey: 'YOUR_API_KEY',
  endpointUrl: 'https://api.airtable.com',
  requestTimeout: 5000
});
```
```

--------------------------------

### firstPage()

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/query.md

Fetches the first page of records matching the query.

```APIDOC
## firstPage()

Fetches the first page of records matching the query.

### Method
GET

### Endpoint
(Implicitly part of the query object)

### Response
#### Success Response (200)
- **records** (`Records<TFields>`) - An array of Record objects

### Request Example
```javascript
const table = base('MyTable');
const query = table.select({ maxRecords: 25 });

const records = await query.firstPage();
console.log(`Found ${records.length} records`);
```
```

--------------------------------

### Initialize Airtable with Environment Endpoint URL

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/configuration.md

Initializes a new Airtable instance, using the endpoint URL from the AIRTABLE_ENDPOINT_URL environment variable if not explicitly provided. An API key must still be supplied.

```javascript
// Reads AIRTABLE_ENDPOINT_URL from environment
const airtable = new Airtable({ apiKey: 'pat...' });
```

--------------------------------

### Manual Pagination

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/query.md

Demonstrates how to manually paginate through records using `eachPage`, allowing for custom processing of records and control over fetching the next page.

```APIDOC
## Manual Pagination

### Description
Manually paginates through records using the `eachPage` method, providing control over fetching subsequent pages.

### Example
```javascript
const table = base('Contacts');
const query = table.select({ pageSize: 100 });

let totalProcessed = 0;

await query.eachPage((records, fetchNext) => {
  totalProcessed += records.length;
  
  records.forEach(record => {
    console.log(`${totalProcessed}: ${record.fields.Name}`);
  });
  
  if (totalProcessed < 1000) {
    fetchNext();
  }
});
```
```

--------------------------------

### Select Records with Filtering

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/query.md

Retrieve records that match specific criteria using the `filterByFormula` option. This example filters for active contacts with a non-empty email address and limits the results to 1000.

```javascript
const table = base('Contacts');
const records = await table.select({
  filterByFormula: "AND({Status} = 'Active', {Email} != '')",
  maxRecords: 1000
}).all();

```

--------------------------------

### Configure Airtable with API Key

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/configuration.md

Initialize the Airtable client using a personal access token. Alternatively, the API key can be set via an environment variable.

```javascript
// Using personal access token
const airtable = new Airtable({
  apiKey: 'patXXXXXXXXXXXXXX'
});

// Or via environment
export AIRTABLE_API_KEY=patXXXXXXXXXXXXXX
const airtable = new Airtable();  // Reads env var
```

--------------------------------

### Base Interface and Instance Methods

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/API-SURFACE.md

The `AirtableBase` interface defines the structure for interacting with a specific Airtable base. Use `base.table()` to get a Table instance and `base.makeRequest()` for custom API calls.

```typescript
interface AirtableBase {
  <TFields extends FieldSet>(tableName: string): Table<TFields>
  table: Base['table']
  makeRequest: Base['makeRequest']
  getId: Base['getId']
}

base<TFields extends FieldSet>(tableName: string): Table<TFields>

base.table<TFields extends FieldSet>(tableName: string): Table<TFields>

base.makeRequest(options?: {
  method?: string;
  path?: string;
  qs?: Record<string, any>;
  headers?: Record<string, string>;
  body?: any;
}): Promise<{ 
  statusCode: number;
  headers: Headers;
  body: any;
}>

base.getId(): string
```

--------------------------------

### Performance Considerations

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/query.md

Tips for optimizing query performance in Airtable, including suggestions for `pageSize`, `maxRecords`, `fields`, `view`, and `returnFieldsByFieldId`.

```APIDOC
## Performance Considerations

- **pageSize**: Default is 100. Larger values fetch more data but use more memory
- **maxRecords**: Limits total results across all pages
- **fields**: Requesting only needed fields can improve performance
- **view**: Using a view with pre-applied filters is faster than client-side filtering
- **returnFieldsByFieldId**: Slightly faster but requires knowing field IDs
```

--------------------------------

### Airtable Class Static Properties and Methods

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/API-SURFACE.md

Access static properties like API version and configuration methods directly from the Airtable class. Use `Airtable.base()` to get a Base instance.

```typescript
Airtable.Base          // Reference to Base class
Airtable.Record        // Reference to Record class
Airtable.Table         // Reference to Table class
Airtable.Error         // Reference to AirtableError class

Airtable.apiKey: string
Airtable.apiVersion: string
Airtable.endpointUrl: string
Airtable.noRetryIfRateLimited: boolean
Airtable.requestTimeout: number

Airtable.configure(options): void
Airtable.base(baseId: string): Base
Airtable.default_config(): AirtableOptions
```

--------------------------------

### Record Instance Methods

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/API-SURFACE.md

Methods available on a Record instance for managing and retrieving data.

```APIDOC
## Record Instance Methods

### get<Field extends keyof TFields>(columnName: Field): TFields[Field]

Retrieves the value of a specified field from the record.

### set<Field extends keyof TFields>(columnName: Field, columnValue: TFields[Field]): void

Sets the value of a specified field in the record.

### save(): Promise<Record<TFields>>

Saves the current state of the record to Airtable.

### save(done: (err, record) => void): void

Saves the current state of the record to Airtable with a callback.

### patchUpdate(cellValuesByName: Partial<TFields>): Promise<Record<TFields>>

Partially updates the record with the provided field values.

### patchUpdate(cellValuesByName: Partial<TFields>, opts: OptionalParameters): Promise<Record<TFields>>

Partially updates the record with provided field values and options.

### patchUpdate(cellValuesByName: Partial<TFields>, opts: OptionalParameters, done: callback): void

Partially updates the record with provided field values, options, and a callback.

### patchUpdate(cellValuesByName: Partial<TFields>, done: callback): void

Partially updates the record with provided field values and a callback.

### putUpdate(cellValuesByName: Partial<TFields>): Promise<Record<TFields>>

Replaces the record with the provided field values.

### putUpdate(cellValuesByName: Partial<TFields>, opts: OptionalParameters): Promise<Record<TFields>>

Replaces the record with the provided field values and options.

### putUpdate(cellValuesByName: Partial<TFields>, opts: OptionalParameters, done: callback): void

Replaces the record with the provided field values, options, and a callback.

### putUpdate(cellValuesByName: Partial<TFields>, done: callback): void

Replaces the record with the provided field values and a callback.

### updateFields(cellValuesByName: Partial<TFields>): Promise<Record<TFields>>

Updates specific fields of the record.

### updateFields(cellValuesByName: Partial<TFields>, opts: OptionalParameters): Promise<Record<TFields>>

Updates specific fields of the record with options.

### updateFields(cellValuesByName: Partial<TFields>, opts: OptionalParameters, done: callback): void

Updates specific fields of the record with options and a callback.

### updateFields(cellValuesByName: Partial<TFields>, done: callback): void

Updates specific fields of the record with a callback.

### replaceFields(cellValuesByName: Partial<TFields>): Promise<Record<TFields>>

Replaces all fields of the record with the provided values.

### replaceFields(cellValuesByName: Partial<TFields>, opts: OptionalParameters): Promise<Record<TFields>>

Replaces all fields of the record with provided values and options.

### replaceFields(cellValuesByName: Partial<TFields>, opts: OptionalParameters, done: callback): void

Replaces all fields of the record with provided values, options, and a callback.

### replaceFields(cellValuesByName: Partial<TFields>, done: callback): void

Replaces all fields of the record with provided values and a callback.

### destroy(): Promise<Record<TFields>>

Deletes the record from Airtable.

### destroy(done: (err, record) => void): void

Deletes the record from Airtable with a callback.

### fetch(): Promise<Record<TFields>>

Fetches the latest version of the record from Airtable.

### fetch(done: (err, record) => void): void

Fetches the latest version of the record from Airtable with a callback.

### getId(): string

Returns the ID of the record.
```

--------------------------------

### Airtable.js Project File Structure

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/README.md

This snippet shows the directory structure of the Airtable.js project, detailing the location of API reference files, type definitions, configuration guides, and error references.

```tree
output/
├── README.md                      (this file)
├── api-reference/
│   ├── airtable.md               (Airtable class)
│   ├── base.md                   (Base class)
│   ├── table.md                  (Table class)
│   ├── record.md                 (Record class)
│   └── query.md                  (Query class)
├── types.md                      (Type definitions)
├── configuration.md              (Configuration guide)
└── errors.md                     (Error reference)
```

--------------------------------

### Making a Raw API Request with Base.makeRequest()

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/base.md

Use the `makeRequest()` method for advanced API interactions, specifying HTTP method, path, query parameters, headers, and body. Handles responses and errors via Promises.

```javascript
const base = Airtable.base('appXXXXXX');

base.makeRequest({
  method: 'GET',
  path: '/MyTable',
  qs: { maxRecords: 10 }
}).then(response => {
  console.log(response.body);
}).catch(error => {
  console.error(error.message);
});
```

--------------------------------

### Setting Request Timeout in Airtable.js

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/errors.md

Configure a custom request timeout for Airtable API calls. This example sets the timeout to 10 seconds. If a request exceeds this duration, it will result in a connection error.

```javascript
const airtable = new Airtable({
  apiKey: 'YOUR_API_KEY',
  requestTimeout: 10000  // 10 seconds
});

try {
  const records = await table.select().all();
} catch (err) {
  if (err.error === 'CONNECTION_ERROR' && err.message.includes('abort')) {
    console.error('Request timed out');
  }
}
```

--------------------------------

### Handling Resource Not Found Errors

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/errors.md

Demonstrates how to catch the NOT_FOUND error, typically occurring when a requested record ID is invalid or a table name does not exist.

```javascript
try {
  const record = await table.find('recWrongID');
} catch (err) {
  if (err.error === 'NOT_FOUND') {
    console.error('Record not found:', err.message);
  }
}
```

--------------------------------

### Manual Pagination with `eachPage`

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/query.md

Process records page by page using the `eachPage` method for more control over pagination. This allows for custom logic within each page and conditional fetching of the next page, processing up to 1000 records.

```javascript
const table = base('Contacts');
const query = table.select({ pageSize: 100 });

let totalProcessed = 0;

await query.eachPage((records, fetchNext) => {
  totalProcessed += records.length;
  
  records.forEach(record => {
    console.log(`${totalProcessed}: ${record.fields.Name}`);
  });
  
  if (totalProcessed < 1000) {
    fetchNext();
  }
});

```

--------------------------------

### Testing Configuration with Mock Endpoint

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/configuration.md

Set up Airtable.js for testing by pointing to a mock API endpoint. This allows for isolated testing without hitting the actual Airtable API.

```javascript
const Airtable = require('airtable');

const testAirtable = new Airtable({
  apiKey: 'test-key',
  endpointUrl: 'http://localhost:3000/mock-api',
  requestTimeout: 5000
});

const base = testAirtable.base('appTEST');
```

--------------------------------

### Access Airtable Base Directly

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/airtable.md

Get a base without instantiating Airtable using a static convenience method. This method uses configured global settings. You can then access a specific table within the base.

```javascript
Airtable.configure({ apiKey: 'YOUR_API_KEY' });
const base = Airtable.base('appXXXXXX');
const table = base('TableName');
```

--------------------------------

### all()

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/api-reference/query.md

Fetches all records matching the query. May take a long time for large result sets, as it makes multiple requests to fetch all pages.

```APIDOC
## all()

Fetches all records matching the query. May take a long time for large result sets, as it makes multiple requests to fetch all pages.

### Method
GET

### Endpoint
(Implicitly part of the query object)

### Response
#### Success Response (200)
- **records** (`Records<TFields>`) - An array of all Record objects

### Request Example
```javascript
const table = base('MyTable');
const query = table.select({
  filterByFormula: '{Status} = "Active"'
});

const records = await query.all();
console.log(`Total records: ${records.length}`);
```
```

--------------------------------

### Custom Type Definition for Project Fields

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/types.md

Example of defining a custom interface for a 'Projects' table using Airtable.js types. This interface specifies field names, their types, and includes custom types like Collaborator and Attachment.

```typescript
import { Airtable } from 'airtable';

interface ProjectFields extends Airtable.FieldSet {
  Title: string;
  Description: string;
  Status: 'Active' | 'Archived';
  Budget: number;
  Owner: Airtable.Collaborator;
  Attachments: Airtable.Attachment[];
}

const projectTable = base<ProjectFields>('Projects');
```

--------------------------------

### Airtable.js Project File Structure

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/INDEX.md

This snippet illustrates the directory and file organization for the Airtable.js project. It helps users locate specific documentation files and understand the project's layout.

```text
output/
├── INDEX.md                       (this file)
├── README.md                      (overview & quick start)
├── types.md                       (type definitions)
├── configuration.md               (configuration reference)
├── errors.md                      (error handling)
└── api-reference/                 (API class references)
    ├── airtable.md               (Airtable class)
    ├── base.md                   (Base class)
    ├── table.md                  (Table class)
    ├── record.md                 (Record class)
    └── query.md                  (Query class)
```

--------------------------------

### Callback Pattern for Airtable Operations

Source: https://github.com/airtable/airtable.js/blob/master/_autodocs/errors.md

Handle Airtable operations using the traditional callback pattern. This example shows how to check for errors, including specific cases like 'NOT_FOUND' and general server errors (5xx status codes).

```javascript
table.find('recXXXXXX', (err, record) => {
  if (err) {
    if (err.error === 'NOT_FOUND') {
      console.error('Record not found');
    } else if (err.statusCode >= 500) {
      console.error('Server error, please retry');
    } else {
      console.error('Error:', err.message);
    }
  } else {
    console.log('Found record:', record.id);
  }
});
```