Letterhead SDK

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

Installation

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.

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>
  );
}

Next.js App Router

@letterhead/core/react is published with a top-of-file "use client" directive on every entry, so you can import SDKProvider directly inside a Server Component (e.g. app/layout.tsx) without an extra wrapper.

If you are pinned to an older SDK version and see TypeError: (0, d.createContext) is not a function, wrap SDKProvider in your own client component:

// app/letterhead-provider.tsx
"use client";
export { SDKProvider } from "@letterhead/core/react";

Use hooks in your components:

import {
  usePosts,
  useSubscribers,
  useCollection,
  useScheduling,
  usePayment,
} 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('[email protected]')}>Sign Up</button>;
}

2. Core SDK Usage

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

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();

Scheduling

// Public booking flow
const defaultAvail = await sdk.scheduling.getDefault('your-org-id');
const { slots } = await sdk.scheduling.slotsByDate(defaultAvail.id, new Date());

await sdk.scheduling.book({
  availability_id: defaultAvail.id,
  attendee_name: 'Ada Lovelace',
  attendee_email: '[email protected]',
  attendee_phone: '+234...',
  start_time: slots[0],
  timezone: 'Africa/Lagos',
  notes: 'Looking forward to it.',
  custom_fields: {
    company: 'Acme',
    job_title: 'CTO',
    project_description: '...',
  },
});

book() returns the created Booking echoing back attendee_phone, timezone, notes, and custom_fields, so you can render a confirmation screen without a follow-up request.

Error handling

All SDK requests reject with LetterheadAPIError, which extends Error:

import { LetterheadAPIError } from '@letterhead/core';

try {
  await sdk.subscribers.add({ email });
} catch (err) {
  if (err instanceof LetterheadAPIError) {
    if (err.isNetworkError) toast.error('Network error — try again.');
    else if (err.status === 409) toast.error('Email is already subscribed.');
    else toast.error(err.message);
  } else {
    throw err;
  }
}

3. RAG Query SDK

For RAG capabilities:

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.
• useScheduling(): Get the Scheduling API.
• usePayment(): Get the Payment API.

License

MIT