New Integration: Airtable

Description

Add Airtable integration to sync bases, tables, records, and views data into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/google-sheets/ - Similar spreadsheet/database integration
• integrations/notion/ - Similar database/workspace integration
• integrations/linear/ - Project management integration

Required Files Structure

integrations/airtable/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # Airtable API utilities
│   ├── account-create.ts # OAuth / PAT setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Airtable Web API Integration

OAuth Setup

• Use OAuth 2.0 or Personal Access Token (PAT)
• OAuth 2.0 for third-party integrations
• Required scopes: data.records:read, data.recordComments:read, schema.bases:read
• Base URL: https://api.airtable.com/v0

Key Endpoints

• GET /v0/meta/bases - List all bases
• GET /v0/meta/bases/{baseId}/tables - List tables in a base
• GET /v0/{baseId}/{tableIdOrName} - List records in a table
• GET /v0/{baseId}/{tableIdOrName}/{recordId} - Get a specific record
• GET /v0/meta/bases/{baseId}/views - List views in a base
• GET /v0/{baseId}/{tableIdOrName}/comments - List record comments

Events to Track

1. Records - Created, updated, deleted records across tables
2. Tables - New tables, schema changes, field additions
3. Bases - New bases created, base updates
4. Comments - Comments added to records
5. Views - New views created, view configuration changes

Implementation Tasks

• Set up basic integration structure following integrations/github/src/index.ts pattern
• Implement OAuth 2.0 / PAT authentication in account-create.ts
• Create API utilities in utils.ts with Airtable Web API client
• Implement sync logic in schedule.ts for bases, tables, records
• Convert Airtable data to CORE activity format
• Add error handling and rate limiting (5 req/sec/base)
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• REST API with JSON responses
• Rate limit: 5 requests per second per base (applies across all pricing tiers)
• Pagination returns max 100 records per request, use offset parameter for next page
• Supports filterByFormula for server-side filtering
• Supports sort parameter for server-side sorting
• Interactive API documentation available at https://airtable.com/api (base-specific)
• Official JavaScript client: airtable.js on npm
• Field types include text, number, attachments, linked records, formulas, etc.
• Use returnFieldsByFieldId parameter for stable field references
• Webhooks available for real-time change notifications

Resources

• Airtable Web API Introduction
• Airtable Developers Portal
• Getting Started with Airtable API
• Airtable API Support
• Airtable.js Client Library

Labels

enhancement, integration, new-feature