Substack API

A TypeScript client for interacting with the Substack webservice API. This library provides a clean, type-safe interface to fetch publication details, posts, comments, and perform searches across Substack publications.

Features

• 🔍 Publication Management - Fetch publication details and metadata
• 📝 Post Operations - Get posts, search by criteria, and access individual posts
• 💬 Comment System - Retrieve comments and comment threads
• 📄 Pagination Support - Built-in pagination for all list operations
• 🛡️ TypeScript First - Full type safety with comprehensive type definitions
• ⚡ Error Handling - Comprehensive error handling with custom error types
• 🔧 Configurable - Support for different API versions and custom configurations

Quick Start

Install the package:

npm install substack-api

Basic usage:

import { Substack } from 'substack-api';

// Create a client for a specific publication
const client = new Substack({
  hostname: 'example.substack.com'
});

// Fetch recent posts
const posts = await client.getPosts({ limit: 5 });

// Search for posts
const results = await client.searchPosts({
  query: 'typescript',
  type: 'newsletter'
});

Documentation

📚 Read the full documentation →

The documentation includes:

• Installation Guide - Detailed installation instructions
• Quickstart Tutorial - Get up and running quickly
• API Reference - Complete API documentation
• Examples - Real-world usage examples
• Development Guide - Contributing and development setup

Testing

The project includes comprehensive testing:

• Unit Tests: Fast, isolated tests for individual components
• End-to-End Tests: Integration tests against real Substack servers

# Run unit tests
npm test

# Run E2E tests (requires API credentials)
npm run test:e2e

# Run all tests
npm run test:all

For E2E tests, copy .env.example to .env and add your Substack API credentials.

License

MIT