fanbeam

Fanbeam SDK

TypeScript SDK for the Fanbeam API, generated from OpenAPI specification.

Overview

This SDK provides a type-safe client for interacting with the Fanbeam API. It is automatically generated from the OpenAPI specification and includes endpoints organized into service classes.

Installation

npm install fanbeam
# or
pnpm add fanbeam
# or
yarn add fanbeam

Quick Start

import { posts, media, channels, client } from 'fanbeam';

// Configure the client with your API key
client.setConfig({
  baseUrl: 'https://fanbeam.app/api',
  headers: {
    'X-API-Key': 'your-api-key-here'
  }
});

// Use service classes for type-safe API calls
const postsList = await posts.list();
const post = await posts.get({ params: { id: 'post-id' } });

// Media upload
const upload = await media.initializeUpload({
  body: {
    filename: 'image.jpg',
    contentType: 'image/jpeg',
    size: 1024000
  }
});

// Channel management
const channelsList = await channels.list();

API Services

The SDK organizes endpoints into service classes:

• Posts Service (posts): Post CRUD (list, get, create, update, remove), scheduling, archiving, group variants
• Media Service (media): Media upload initialization and management (initializeUpload, remove, etc.)
• Channels Service (channels): Channel listing and management (list, get, remove)

Each service is generated as a static class with type-safe methods matching the API endpoints.

Usage Examples

List Posts

import { posts } from 'fanbeam';

const response = await posts.list({
  query: {
    page: 1,
    limit: 20
  }
});

if (response.error) {
  console.error('Error:', response.error);
} else {
  console.log('Posts:', response.data);
}

Create Post

import { posts } from 'fanbeam';

const response = await posts.create({
  body: {
    title: 'My Post',
    body: 'Post content',
    scheduledAt: new Date('2024-01-01T12:00:00Z'),
    channelIds: ['channel-id-1', 'channel-id-2']
  }
});

Media Upload

import { media } from 'fanbeam';

// Initialize upload
const uploadResponse = await media.initializeUpload({
  body: {
    filename: 'image.jpg',
    contentType: 'image/jpeg',
    size: 1024000
  }
});

// Upload file using presigned URL
const file = await fetch(uploadResponse.data.presignedUrl, {
  method: 'PUT',
  body: fileData,
  headers: {
    'Content-Type': 'image/jpeg'
  }
});

// Finalize upload
await media.finalizeUpload({
  params: { id: uploadResponse.data.id }
});

Error Handling

import { posts } from 'fanbeam';

try {
  const response = await posts.list();
  if (response.error) {
    console.error('API Error:', response.error.status, response.error.body);
    return;
  }
  console.log('Posts:', response.data);
} catch (error) {
  console.error('Request failed:', error);
}

Custom Client Instance

import { posts, createClient } from 'fanbeam';

const customClient = createClient({
  baseUrl: 'https://staging.fanbeam.app/api',
  headers: {
    'X-API-Key': 'staging-api-key'
  }
});

// Use custom client for specific call
const response = await posts.list({
  client: customClient
});

Type Safety

All request/response types are generated from OpenAPI schemas:

import type { 
  PostsListData,
  PostsListResponses,
  PostsGetData,
  PostsGetResponses
} from 'fanbeam';

// Type-safe request data
const requestData: PostsListData = {
  query: { limit: 10, page: 1 }
};

// Type-safe response
const response: PostsListResponses = await posts.list(requestData);

Authentication

The SDK uses API key authentication via the X-API-Key header. Configure your API key when setting up the client:

client.setConfig({
  headers: {
    'X-API-Key': 'your-api-key-here'
  }
});

Configuration

Base URL

The SDK supports multiple environments:

client.setConfig({
  baseUrl: 'https://fanbeam.app/api' // Production
  // baseUrl: 'https://development.fanbeam.app/api' // Development
  // baseUrl: 'http://local.fanbeam.app:3000/api' // Local
});

Custom Headers

// Global headers
client.setConfig({
  headers: {
    'X-API-Key': 'your-api-key',
    'X-Custom-Header': 'value'
  }
});

// Per-request headers
const response = await posts.list({
  headers: {
    'X-Custom-Header': 'value'
  }
});

Error Handling

The SDK provides structured error responses:

const response = await posts.get({ params: { id: 'invalid' } });

if (response.error) {
  // response.error.status - HTTP status code
  // response.error.body - Error response body
  console.error('Error:', response.error.status, response.error.body);
} else {
  // response.data - Success response data
  console.log('Post:', response.data);
}

Request Options

Throw on Error

// Throw exception on error instead of returning error response
const response = await posts.list({ throwOnError: true });

Custom Fetch

import { createClient } from 'fanbeam';

const client = createClient({
  fetch: customFetchImplementation
});

Pagination

Many endpoints support pagination:

const response = await posts.list({
  query: {
    page: 1,
    limit: 20
  }
});

Reference

For complete API documentation, see the Fanbeam API docs.