@spotable/attio-sdk/README.md

Client for Attio REST API

# Attio SDK

> ⚠️ **Experimental:** This package is in active development and not ready for production use. APIs and features may change without notice.

A TypeScript SDK for interacting with the [Attio REST API](https://docs.attio.com/rest-api/overview).

## Features

- CLI for generating TypeScript SDK from Attio schema
- Fetch-based HTTP client
- Type-safe API requests and responses
- Object, Attribute, Record, List, List Entry, Note, Task, standard objects and custom objects fetchers
- Webhooks support

## Usage

First, install the SDK and its peer dependencies:

```sh
pnpm add @spotable/attio-sdk
```

To generate the SDK from your Attio schema, run the following command. You can use the `--help` flag to see all available options for the `generate` command. Ensure that your Attio API key is provided via the `ATTIO_API_KEY` environment variable.

> :warning: Keep your API key secure. Never hardcode it in your source code or expose it publicly. Always add your configuration file to `.gitignore` to prevent accidental commits.

```sh
attio-sdk generate --output ./output-directory --standard-types
```

Import and initialize the client:

```typescript
import { AttioClient } from './output-directory';

const client = new AttioClient({ apiKey: 'YOUR_API_KEY' });

// Example: Fetch all objects
const objects = await client.objects.getAll();
```

### Fetchers

The Attio SDK provides fetchers for interacting with different resources in the Attio API. Each fetcher exposes methods for creating, reading, updating, and deleting entities, as well as querying and subscribing to webhook events.

- `client.objects` — Manage Attio objects (standard and custom)
- `client.attributes` — Manage attributes for objects and lists
- `client.records` — Manage records for objects
- `client.lists` — Manage lists
- `client.listEntries` — Manage entries within lists
- `client.notes` — Manage notes attached to records or objects
- `client.tasks` — Manage tasks
- `client.<OBJECT_SLUG>` — Access custom objects using their slug (e.g., `client.companies`)
- `client.webhooks` — Manage and subscribe to webhooks

#### Webhook Events

Each fetcher supports subscribing to [webhook events](https://docs.attio.com/rest-api/webhook-reference). Use `client.webhooks.on(eventType, handler)` to listen for specific events. Handlers receive an event object containing the original payload and the relevant entity. The SDK automatically fetches the relevant entity data for each event, so you have immediate access to the updated resource without making additional API calls.

**Example:**

```typescript
// Using fetcher-specific event handlers:
client.notes.onCreated((event) => {
   console.log('Original payload:', event.payload);
   console.log('New note created:', event.data);
});

// Manually subscribing:
client.webhooks.on('note.created', (event) => {
   console.log('Original payload:', event.payload);
   console.log('New note created:', event.data);
});
```

## Development

1. Clone the repository and install dependencies:

   ```sh
   pnpm install
   ```

2. Install the dependencies:

   ```sh
   pnpm install
   ```

3. Run the `attio-sdk` command without building:

   ```sh
   pnpm dev <command> <options>
   ```

## Contributing

- Open issues or pull requests for bugs and features
- Follow the code style enforced by ESLint

## License

MIT