@ltphat2204/teable-sdk

A premium, modern, and type-safe TypeScript SDK for Teable.

Features

• 🚀 Full TypeScript Support: Get full IDE completion and type safety for your record fields.
• ✅ Zod Validation: Runtime configuration validation ensures your setup is correct.
• 🔄 Auto-Pagination: Fetch thousands of records effortlessly with built-in pagination handling.
• 📦 Multi-Format: Supports ESM, CommonJS, and UMD out of the box.
• 🛡️ Robust Error Handling: Clear error classes and descriptive messages for API failures.
• 🎯 Table-Centric API: Intuitive helper class for working with specific tables.

Installation

npm install @ltphat2204/teable-sdk
# or
yarn add @ltphat2204/teable-sdk
# or
pnpm add @ltphat2204/teable-sdk

Quick Start

Create a Client

import { createTeableClient } from '@ltphat2204/teable-sdk';

const client = createTeableClient({
  baseURL: 'https://app.teable.io',
  token: 'your_api_token_here',
});

Working with a Specific Table (Recommended)

This approach gives you the best type safety and developer experience.

interface MyFields {
  Name: string;
  Status: 'Active' | 'Inactive';
  Age: number;
}

const table = client.table<MyFields>('your_table_id');

// List records
const { records } = await table.listRecords({
  take: 10,
  filter: { Name: { is: 'John' } }
});

// Get all records (auto-pagination)
const allRecords = await table.getAllRecords();

// Create a record
const newRecord = await table.createRecord({
  Name: 'Jane Doe',
  Status: 'Active',
  Age: 25,
});

// Update a record
await table.updateRecord('record_id', {
  Status: 'Inactive',
});

Generic Record Operations

If you prefer a more stateless approach or need to dynamic table IDs:

const records = await client.records.get('table_id', { take: 50 });

API Documentation

TeableClient

The main entry point for the SDK.

• table<TFields>(tableId: string): Returns a TeableTable instance.
• records: Access the generic Records API.
• http: Direct access to the Axios instance.

TeableTable

A helper class for a specific table.

• listRecords(options): List records with filtering, sorting, and pagination.
• getAllRecords(options): Fetch all records, automatically handling pagination.
• getRecord(recordId, options): Fetch a single record.
• createRecord(fields, options): Create a single record.
• createRecords(records, options): Bulk create records.
• updateRecord(recordId, fields, options): Update a single record.
• updateRecords(records, options): Bulk update records.
• deleteRecord(recordId): Delete a single record.
• deleteRecords(recordIds): Bulk delete records.
• findRecord(filter, options): Find the first record matching a filter.
• getFields(): Get table field metadata.

License

MIT © ltphat2204