npm package: @letterhead/core
Description: The official SDK for Letterhead
Author: Eric
Latest version: 0.1.1

# Letterhead SDK

The official SDK for Letterhead, providing seamless integration with Data Collection, Scheduling, RAG (Retrieval-Augmented Generation), and React components.

## Installation

```bash
npm install @letterhead/core
# or
yarn add @letterhead/core
# or
pnpm add @letterhead/core
```

## Features

- **Data Collection**: Create and manage custom forms, surveys, and data endpoints.
- **Scheduling**: Integrate availability and booking capabilities.
- **RAG Querying**: Interact with organization documents using AI.
- **React Support**: Built-in hooks and providers for easy React integration.

## Usage

This SDK supports both standard Node.js/JavaScript environments and React applications.

### 1. React Integration

For React applications (including Next.js Client Components), import from `@letterhead/core/react`.

**Important**: Wrap your application with `SDKProvider`.

```tsx
import { SDKProvider } from '@letterhead/core/react';

function App() {
  const config = {
    apiUrl: 'https://api.letterhead.cloud', // Replace with your API URL
    organizationId: 'your-org-id',
    apiKey: 'your-api-key', // Optional for public endpoints
  };

  return (
    <SDKProvider config={config}>
      <YourApp />
    </SDKProvider>
  );
}
```

Use hooks in your components:

```tsx
import { usePosts, useSubscribers, useCollection } from '@letterhead/core/react';

function BlogPosts() {
  const postsApi = usePosts();

  useEffect(() => {
    postsApi.list().then(response => {
      console.log(response.posts);
    });
  }, []);

  return <div>{/* Render posts */}</div>;
}

function NewsletterSignup() {
  const subscribersApi = useSubscribers();

  const handleSignup = async (email) => {
    await subscribersApi.add({ email });
  };

  return <button onClick={() => handleSignup('test@example.com')}>Sign Up</button>;
}
```

### 2. Core SDK Usage

For server-side usage (Node.js, Next.js Server Components operations), import from `@letterhead/core`.

```ts
import { createDataCollectionSDK } from '@letterhead/core';

const sdk = createDataCollectionSDK({
  apiUrl: 'https://api.letterhead.ai',
  organizationId: 'your-org-id',
  apiKey: 'your-public-key',
});

// Access Blog Posts
const posts = await sdk.posts.list();

// Access Scheduling
const availability = await sdk.scheduling.getAvailability('avail-id');

// Access Data Collection
const submissions = await sdk.collection('surveys').list();
```

### 3. RAG Query SDK

For RAG capabilities:

```ts
import { createRAGQuerySDK } from '@letterhead/core';

const ragSdk = createRAGQuerySDK({
  apiUrl: 'https://api.letterhead.ai',
  apiKey: 'your-api-key',
});

// Streaming Query
await ragSdk.query(
  { question: "What is the return policy?" },
  {
    onContent: (chunk, accumulated) => {
      console.log("Stream:", chunk);
    },
    onDone: (response) => {
      console.log("Final Answer:", response);
    }
  }
);
```

## API Reference

### Data Collection SDK
- `sdk.posts`: Manage blog posts (list, get, create, update, delete).
- `sdk.subscribers`: Manage newsletter subscribers.
- `sdk.scheduling`: Access availability and book slots.
- `sdk.collection(name)`: Interact with specific data collections (add entry, list entries, get schema).

### React Hooks
- `useSDK()`: Get the core SDK instance.
- `usePosts()`: Get the Posts API.
- `useSubscribers()`: Get the Subscribers API.
- `useCollection(name)`: Get a specific Collection API.

## License

MIT