airtable-books

Automatically fills in book metadata in an Airtable base using ISBN lookup. Add an ISBN, run the script, and all fields — title, authors, publisher, cover, description, rating, and more — are populated in one go.

Uses Google Books as the primary data source, with Open Library as an automatic fallback for books that don't appear in Google's catalogue (older titles, non-English books, etc.).

---

Setup

1. Clone the repo

2. Install dependencies:

   npm install
   

3. Copy .env.example to .env and fill in your credentials:

   cp .env.example .env
   

   Variable	Where to get it
   AIRTABLE_API_KEY	Airtable → Personal Access Tokens
   AIRTABLE_BASE_ID	Your base URL: airtable.com/{BASE_ID}/...
   GOOGLE_BOOKS_API_KEY	Google Cloud Console → Books API

4. In Airtable, make sure your Books table has a view called "Books Update" containing the records you want to sync. Records are removed from the view automatically once synced (via the Status field).

---

Usage

npm start

The script will:

• Fetch all records in the "Books Update" view
• Look up each ISBN — Google Books first, Open Library if no result is found
• Write all metadata fields directly to Airtable in a single PATCH
• Set Status to Synced so the record leaves the view

Console output uses ✓ / ✗ / ⚠ prefixes per record, and logs which data source was used.

---

Airtable Schema

Base: Book Library Rooz · Table: Books

Field	Type	Notes
Title	singleLineText	Primary field
ISBN	singleLineText	Input — never overwritten
Author	multipleSelects	All authors from API
Publisher	multipleSelects
Description	richText
Published Date	date
Page Count	number
Rating	rating (1–5)	Rounded from API float
Maturity	checkbox	true if rated Mature
Covers	multipleAttachments	Thumbnail from API
Status	singleSelect	Set to Synced after update

For full schema with field IDs see airtable/schema.md.

---

Data Sources

Source	Role	Auth
Google Books API	Primary	API key (env)
Open Library API	Fallback	None required

Open Library kicks in automatically when Google Books returns no result for an ISBN. Both sources map to the same fields so no changes to the script are needed when a fallback is used.

---

Project structure

airtable-books/
├── scripts/
│   └── update-books.mjs          ← main script
├── airtable/
│   └── schema.md                 ← full Airtable schema with field IDs
├── context/
│   ├── architecture.md           ← stack, data flow, field mapping
│   ├── conventions.md            ← code style, naming, ESM rules
│   └── product.md                ← what this is and why
├── skills/
│   ├── add-field.md              ← how to add a new metadata field
│   └── debug-issue.md            ← how to diagnose sync problems
├── prompts/
│   ├── scripts/add-data-source.md   ← how to add another API source
│   └── workflows/plan-feature.md   ← planning template before any change
├── CLAUDE.md                     ← Claude context (keep lean)
├── .env.example                  ← credential template
└── package.json