@skynetxbt/flow-airtable

@skynetxbt/flow-airtable

A comprehensive Airtable integration flow for SkynetXBT that provides full CRUD (Create, Read, Update, Delete) operations with advanced filtering, sorting, and data manipulation capabilities.

Features

• Complete CRUD Operations: Create, read, update, and delete records
• Advanced Filtering: Support for Airtable formula-based filtering
• Flexible Sorting: Multi-field sorting with custom directions
• Type Safety: Full TypeScript support with comprehensive type definitions
• Dynamic Operations: Support for dynamic input replacement using placeholders
• Helper Methods: Convenient methods for common operations
• Error Handling: Comprehensive error handling and logging
• Formula Helpers: Built-in helpers for common filter patterns

Installation

npm install @skynetxbt/flow-airtable

Configuration

Environment Variables

Set the following environment variables:

AIRTABLE_API_KEY=your_airtable_api_key
AIRTABLE_BASE_ID=your_airtable_base_id

Getting Your Credentials

• API Key: Go to your Airtable account page and generate a personal access token
• Base ID: Find your base ID in the Airtable API documentation for your base (starts with "app")

Usage

Basic Usage

import AirtableFlow from '@skynetxbt/flow-airtable';

// Initialize with environment variables
const airtableFlow = new AirtableFlow();

// Or initialize with explicit credentials
const airtableFlow = new AirtableFlow({
  apiKey: 'your-api-key',
  baseId: 'your-base-id'
});

Reading Data

Read All Records

// Read all records from a table
const result = await airtableFlow.readAll('Customers', {
  maxRecords: 100,
  sort: [{ field: 'Name', direction: 'asc' }]
});

console.log(result.data); // Array of records
console.log(result.recordCount); // Number of records returned

Read with Filters

// Filter active customers in New York
const result = await airtableFlow.readWithFilter(
  'Customers',
  "AND({Status} = 'Active', {City} = 'New York')",
  { maxRecords: 50 }
);

// Filter using helper methods
import { AirtableFormulas } from '@skynetxbt/flow-airtable';

const filter = AirtableFormulas.and(
  AirtableFormulas.exactMatch('Status', 'Active'),
  AirtableFormulas.exactMatch('City', 'New York')
);

const result = await airtableFlow.readWithFilter('Customers', filter);

Advanced Filtering Examples

// Date range filter
const dateFilter = "AND(IS_AFTER({Created}, '2024-01-01'), IS_BEFORE({Created}, '2024-12-31'))";

// Numeric range filter
const priceFilter = "AND({Price} >= 100, {Price} <= 500)";

// Text search filter
const searchFilter = "SEARCH('premium', LOWER({Product Name}))";

// Multiple conditions
const complexFilter = `
  AND(
    OR({Status} = 'Pending', {Status} = 'Processing'),
    {Amount} > 100,
    NOT({Customer} = '')
  )
`;

Writing Data

Create Records

// Create a single record
const result = await airtableFlow.create('Customers', {
  'Name': 'John Doe',
  'Email': '[e-mail]',
  'Status': 'Active',
  'City': 'San Francisco'
});

console.log(result.recordId); // ID of created record

Update Records

// Update an existing record
const result = await airtableFlow.update('Customers', 'recXXXXXXXXXXXXXX', {
  'Status': 'Inactive',
  'Notes': 'Customer requested deactivation'
});

Delete Records

// Delete a record
const result = await airtableFlow.delete('Customers', 'recXXXXXXXXXXXXXX');

Deterministic Operations with Placeholders

// Create a flow with predefined operations
const customerReaderFlow = new AirtableFlow({
  operation: {
    action: 'read',
    tableName: 'Customers',
    filterByFormula: "AND({Status} = 'Active', {City} = '${{input}}')",
    maxRecords: 10
  }
});

// Execute with dynamic input
const context = {
  agentId: { generation: 0, familyCode: "", serialNumber: "" },
  userPublicKey: "user123",
  message: "New York", // This replaces ${{input}} in the filter
  variables: {}
};

const result = await customerReaderFlow.execute(context);

Using Formula and Filter Helpers

import { AirtableFormulas, AirtableFilters } from '@skynetxbt/flow-airtable';

// Use built-in filter presets
const activeCustomersFilter = AirtableFilters.activeCustomers();
const recentOrdersFilter = AirtableFilters.recentOrders();
const highValueOrdersFilter = AirtableFilters.highValueOrders(1000);

// Create custom filters with formula helpers
const customFilter = AirtableFormulas.and(
  AirtableFormulas.exactMatch('Status', 'Active'),
  AirtableFormulas.textSearch('Name', 'john'),
  AirtableFormulas.numericRange('Age', 25, 65)
);

// Use the filters
const result = await airtableFlow.readWithFilter('Customers', customFilter);

Batch Operations

// Create multiple records
const customers = [
  { 'Name': 'Alice Johnson', 'Email': '[e-mail]' },
  { 'Name': 'Bob Wilson', 'Email': '[e-mail]' },
  { 'Name': 'Carol Brown', 'Email': '[e-mail]' }
];

const createdRecords = [];
for (const customer of customers) {
  const result = await airtableFlow.create('Customers', customer);
  if (result.success) {
    createdRecords.push(result);
  }
}

Types

The flow includes comprehensive TypeScript types:

import { 
  AirtableOperation,
  AirtableResponse,
  CustomerFields,
  OrderFields,
  ProductFields,
  AirtableFormulas,
  AirtableFilters
} from '@skynetxbt/flow-airtable';

// Use typed field definitions
const customer: CustomerFields = {
  'Name': 'John Doe',
  'Email': '[e-mail]',
  'Status': 'Active'
};

Error Handling

try {
  const result = await airtableFlow.readAll('Customers');
  if (result.success) {
    console.log('Data:', result.data);
  } else {
    console.error('Error:', result.error);
  }
} catch (error) {
  console.error('Exception:', error.message);
}

Common Use Cases

Customer Management

// Get all active customers
const activeCustomers = await airtableFlow.readWithFilter(
  'Customers', 
  AirtableFilters.activeCustomers()
);

// Create new customer
const newCustomer = await airtableFlow.create('Customers', {
  'Name': 'Jane Smith',
  'Email': '[e-mail]',
  'Status': 'Active'
});

Order Processing

// Get recent high-value orders
const filter = AirtableFormulas.and(
  AirtableFilters.recentOrders(),
  AirtableFilters.highValueOrders(500)
);

const orders = await airtableFlow.readWithFilter('Orders', filter);

// Update order status
await airtableFlow.update('Orders', orderId, {
  'Status': 'Shipped',
  'Tracking Number': 'TRK123456789'
});

Inventory Management

// Get low stock products
const lowStockFilter = "{In Stock} <= {Reorder Level}";
const lowStockProducts = await airtableFlow.readWithFilter('Products', lowStockFilter);

// Update stock levels
await airtableFlow.update('Products', productId, {
  'In Stock': newStockLevel,
  'Last Updated': new Date().toISOString()
});

Best Practices

• Use Environment Variables: Store API credentials securely
• Implement Error Handling: Always check response success status
• Use Type Safety: Leverage TypeScript types for better development experience
• Optimize Queries: Use filters and limits to reduce API calls
• Batch Operations: For multiple records, consider batching to reduce API calls
• Formula Helpers: Use built-in formula helpers for complex filters

API Reference

Methods

• readAll(tableName, options?): Read all records from a table
• readWithFilter(tableName, filter, options?): Read records with filter
• create(tableName, fields): Create a new record
• update(tableName, recordId, fields): Update an existing record
• delete(tableName, recordId): Delete a record
• execute(context): Execute with FlowContext (for use in flow system)

Types

• AirtableOperation: Operation configuration interface
• AirtableResponse: Response format interface
• CustomerFields, OrderFields, ProductFields: Common field type definitions
• AirtableFormulas: Static class with formula helper methods
• AirtableFilters: Static class with common filter presets

Contributing

Contributions are welcome! Please read the contributing guidelines and submit pull requests for any improvements.