@superblocksteam/sdk-api 0.0.4

package/src/integrations/airtable/README.md

@@ -0,0 +1,421 @@
+# Airtable Client
+
+Create, read, update, and delete records in Airtable bases and tables.
+
+## Methods
+
+| Method                                   | Description                                          |
+| ---------------------------------------- | ---------------------------------------------------- |
+| `apiRequest(options, schema, metadata?)` | Make any Airtable API request with schema validation |
+
+## Usage
+
+### List Records
+
+```typescript
+import { api, z, airtable } from "@superblocksteam/sdk-api";
+
+// Integration ID from the integrations panel
+const PROD_AIRTABLE = "a1b2c3d4-5678-90ab-cdef-airtable0001";
+
+const RecordSchema = z.object({
+  id: z.string(),
+  createdTime: z.string(),
+  fields: z.record(z.unknown()),
+});
+
+const ListRecordsResponseSchema = z.object({
+  records: z.array(RecordSchema),
+  offset: z.string().optional(),
+});
+
+export default api({
+  name: "AirtableExample",
+  integrations: {
+    airtable: airtable(PROD_AIRTABLE),
+  },
+  input: z.object({
+    baseId: z.string(),
+    tableId: z.string(),
+  }),
+  output: z.object({
+    records: z.array(
+      z.object({ id: z.string(), fields: z.record(z.unknown()) }),
+    ),
+  }),
+  async run(ctx, { baseId, tableId }) {
+    const result = await ctx.integrations.airtable.apiRequest(
+      {
+        method: "GET",
+        path: `/v0/${baseId}/${tableId}`,
+        params: {
+          maxRecords: 100,
+        },
+      },
+      { response: ListRecordsResponseSchema },
+    );
+
+    return {
+      records: result.records.map((r) => ({ id: r.id, fields: r.fields })),
+    };
+  },
+});
+```
+
+### Create a Record
+
+```typescript
+const CreateRecordResponseSchema = z.object({
+  id: z.string(),
+  createdTime: z.string(),
+  fields: z.record(z.unknown()),
+});
+
+const result = await ctx.integrations.airtable.apiRequest(
+  {
+    method: "POST",
+    path: `/v0/${baseId}/${tableId}`,
+    body: {
+      fields: {
+        Name: "New Task",
+        Status: "To Do",
+        Priority: "High",
+        "Due Date": "2024-12-31",
+        Assignee: ["rec123"], // Linked record IDs
+      },
+    },
+  },
+  { response: CreateRecordResponseSchema },
+);
+
+console.log(`Created record: ${result.id}`);
+```
+
+### Create Multiple Records
+
+```typescript
+const CreateMultipleResponseSchema = z.object({
+  records: z.array(RecordSchema),
+});
+
+const result = await ctx.integrations.airtable.apiRequest(
+  {
+    method: "POST",
+    path: `/v0/${baseId}/${tableId}`,
+    body: {
+      records: [
+        { fields: { Name: "Task 1", Status: "To Do" } },
+        { fields: { Name: "Task 2", Status: "To Do" } },
+        { fields: { Name: "Task 3", Status: "In Progress" } },
+      ],
+    },
+  },
+  { response: CreateMultipleResponseSchema },
+);
+
+console.log(`Created ${result.records.length} records`);
+```
+
+### Get a Single Record
+
+```typescript
+const result = await ctx.integrations.airtable.apiRequest(
+  {
+    method: "GET",
+    path: `/v0/${baseId}/${tableId}/${recordId}`,
+  },
+  { response: RecordSchema },
+);
+
+console.log(`Record: ${result.fields.Name}`);
+```
+
+### Update a Record
+
+```typescript
+const result = await ctx.integrations.airtable.apiRequest(
+  {
+    method: "PATCH",
+    path: `/v0/${baseId}/${tableId}/${recordId}`,
+    body: {
+      fields: {
+        Status: "Done",
+        "Completed Date": new Date().toISOString().split("T")[0],
+      },
+    },
+  },
+  { response: RecordSchema },
+);
+```
+
+### Update Multiple Records
+
+```typescript
+const result = await ctx.integrations.airtable.apiRequest(
+  {
+    method: "PATCH",
+    path: `/v0/${baseId}/${tableId}`,
+    body: {
+      records: [
+        { id: "rec1", fields: { Status: "Done" } },
+        { id: "rec2", fields: { Status: "Done" } },
+      ],
+    },
+  },
+  { response: z.object({ records: z.array(RecordSchema) }) },
+);
+```
+
+### Delete Records
+
+```typescript
+const DeleteResponseSchema = z.object({
+  records: z.array(
+    z.object({
+      id: z.string(),
+      deleted: z.boolean(),
+    }),
+  ),
+});
+
+const result = await ctx.integrations.airtable.apiRequest(
+  {
+    method: "DELETE",
+    path: `/v0/${baseId}/${tableId}`,
+    params: {
+      "records[]": ["rec1", "rec2", "rec3"],
+    },
+  },
+  { response: DeleteResponseSchema },
+);
+```
+
+### Filter and Sort Records
+
+```typescript
+const result = await ctx.integrations.airtable.apiRequest(
+  {
+    method: "GET",
+    path: `/v0/${baseId}/${tableId}`,
+    params: {
+      filterByFormula: "AND({Status} = 'To Do', {Priority} = 'High')",
+      sort: JSON.stringify([
+        { field: "Due Date", direction: "asc" },
+        { field: "Priority", direction: "desc" },
+      ]),
+      view: "Grid view", // Use a specific view
+      maxRecords: 50,
+    },
+  },
+  { response: ListRecordsResponseSchema },
+);
+```
+
+### Get Table Schema
+
+```typescript
+const TableSchemaResponseSchema = z.object({
+  tables: z.array(
+    z.object({
+      id: z.string(),
+      name: z.string(),
+      primaryFieldId: z.string(),
+      fields: z.array(
+        z.object({
+          id: z.string(),
+          name: z.string(),
+          type: z.string(),
+          options: z.unknown().optional(),
+        }),
+      ),
+    }),
+  ),
+});
+
+const result = await ctx.integrations.airtable.apiRequest(
+  {
+    method: "GET",
+    path: `/v0/meta/bases/${baseId}/tables`,
+  },
+  { response: TableSchemaResponseSchema },
+);
+
+result.tables.forEach((table) => {
+  console.log(`Table: ${table.name}`);
+  table.fields.forEach((field) => {
+    console.log(`  - ${field.name} (${field.type})`);
+  });
+});
+```
+
+## Trace Metadata
+
+All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.
+
+## Common Pitfalls
+
+### No Specialized Methods
+
+```typescript
+// WRONG - These methods do not exist
+await ctx.integrations.airtable.listRecords({ ... });
+await ctx.integrations.airtable.createRecord({ ... });
+
+// CORRECT - Use apiRequest
+await ctx.integrations.airtable.apiRequest(
+  { method: "GET", path: `/v0/${baseId}/${tableId}` },
+  { response: ListRecordsResponseSchema }
+);
+```
+
+### URL Encoding Table Names
+
+Table names with spaces need URL encoding:
+
+```typescript
+// If table name is "My Tasks"
+const tableName = encodeURIComponent("My Tasks");
+const path = `/v0/${baseId}/${tableName}`;
+
+// Or use table ID instead (preferred)
+const path = `/v0/${baseId}/tbl123abc`;
+```
+
+### Field Names are Case-Sensitive
+
+```typescript
+// WRONG - Wrong case
+const fields = {
+  name: "Task", // Should be "Name"
+  STATUS: "To Do", // Should be "Status"
+};
+
+// CORRECT - Match exact field names from Airtable
+const fields = {
+  Name: "Task",
+  Status: "To Do",
+};
+```
+
+### Linked Records Use Record IDs
+
+```typescript
+// For linked record fields, use an array of record IDs
+const fields = {
+  Name: "New Task",
+  Project: ["recABC123"], // Single link
+  Assignees: ["recDEF456", "recGHI789"], // Multiple links
+};
+```
+
+### Formula Syntax
+
+Airtable formulas have specific syntax:
+
+```typescript
+// String comparison (use single quotes)
+const filter1 = "{Status} = 'Done'";
+
+// Number comparison
+const filter2 = "{Count} > 10";
+
+// Date comparison
+const filter3 = "IS_AFTER({Due Date}, TODAY())";
+
+// AND/OR
+const filter4 = "AND({Status} = 'To Do', {Priority} = 'High')";
+const filter5 = "OR({Status} = 'Done', {Status} = 'Archived')";
+
+// SEARCH for partial match
+const filter6 = "SEARCH('project', LOWER({Name}))";
+
+// NULL check
+const filter7 = "{Assignee} = BLANK()";
+const filter8 = "NOT({Assignee} = BLANK())";
+```
+
+### Pagination
+
+Airtable returns max 100 records per request:
+
+```typescript
+async function getAllRecords(
+  airtable: AirtableClient,
+  baseId: string,
+  tableId: string,
+) {
+  const allRecords: Record[] = [];
+  let offset: string | undefined;
+
+  do {
+    const result = await airtable.apiRequest(
+      {
+        method: "GET",
+        path: `/v0/${baseId}/${tableId}`,
+        params: {
+          pageSize: 100,
+          ...(offset && { offset }),
+        },
+      },
+      { response: ListRecordsResponseSchema },
+    );
+
+    allRecords.push(...result.records);
+    offset = result.offset;
+  } while (offset);
+
+  return allRecords;
+}
+```
+
+### Rate Limits
+
+Airtable has a rate limit of 5 requests per second per base:
+
+```typescript
+// Add delays for bulk operations
+for (const batch of batches) {
+  await ctx.integrations.airtable.apiRequest(...);
+  await new Promise((r) => setTimeout(r, 200)); // 5 req/sec = 200ms delay
+}
+```
+
+### Batch Operations Limited to 10 Records
+
+```typescript
+// WRONG - More than 10 records
+const body = {
+  records: Array(15).fill({ fields: { Name: "Task" } }), // Will fail
+};
+
+// CORRECT - Batch in groups of 10
+const records = Array(15).fill({ fields: { Name: "Task" } });
+const batches = [];
+for (let i = 0; i < records.length; i += 10) {
+  batches.push(records.slice(i, i + 10));
+}
+```
+
+## Error Handling
+
+```typescript
+import { RestApiValidationError } from "@superblocksteam/sdk-api";
+
+try {
+  const result = await ctx.integrations.airtable.apiRequest(
+    { method: "GET", path: `/v0/${baseId}/${tableId}` },
+    { response: ListRecordsResponseSchema },
+  );
+} catch (error) {
+  if (error instanceof RestApiValidationError) {
+    console.error("Validation failed:", error.details.zodError);
+  }
+}
+```
+
+## API Reference
+
+- [Airtable API Documentation](https://airtable.com/developers/web/api/introduction)
+- [List Records](https://airtable.com/developers/web/api/list-records)
+- [Create Records](https://airtable.com/developers/web/api/create-records)
+- [Formula Reference](https://support.airtable.com/docs/formula-field-reference)

package/src/integrations/airtable/client.ts

@@ -0,0 +1,23 @@
+/**
+ * Airtable client implementation.
+ *
+ * Uses the proto-generated REST API Integration Plugin type from @superblocksteam/types.
+ * Airtable integrations use the REST API Integration plugin under the hood.
+ */
+
+import { RestApiIntegrationClient } from "../base/index.js";
+import type { AirtableClient } from "./types.js";
+
+/**
+ * Internal implementation of AirtableClient.
+ *
+ * Extends RestApiIntegrationClient to inherit the generic apiRequest() method.
+ * This implementation communicates with the orchestrator to execute
+ * Airtable API calls. At runtime, the orchestrator handles authentication
+ * and API request execution.
+ */
+export class AirtableClientImpl
+  extends RestApiIntegrationClient
+  implements AirtableClient {
+  // Inherits: name, pluginId, config, executeQuery, apiRequest()
+}

package/src/integrations/airtable/index.ts

@@ -0,0 +1,2 @@
+export { AirtableClientImpl } from "./client.js";
+export type { AirtableClient } from "./types.js";

package/src/integrations/airtable/types.ts

@@ -0,0 +1,30 @@
+/**
+ * Airtable client types.
+ */
+
+import type { BaseIntegrationClient } from "../../types.js";
+import type { SupportsApiRequest } from "../base/index.js";
+
+/**
+ * Airtable client for API interactions.
+ *
+ * Provides generic API request method for interacting with Airtable's API.
+ * Use apiRequest() to make calls to any Airtable API endpoint.
+ *
+ * @example
+ * ```typescript
+ * // Declare in api(): integrations: { airtable: airtable(INTEGRATION_ID) }
+ * // In run(), access via: ctx.integrations.airtable
+ * const result = await ctx.integrations.airtable.apiRequest(
+ *   {
+ *     method: 'GET',
+ *     path: '/v0/{baseId}/{tableName}',
+ *   },
+ *   { response: ResponseSchema }
+ * );
+ * ```
+ */
+export interface AirtableClient
+  extends BaseIntegrationClient, SupportsApiRequest {
+  // apiRequest() method inherited from SupportsApiRequest
+}