@destink/substack-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jakub Slys
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# Substack SDK
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+
+A modern, type-safe TypeScript client for the Substack API. Connects directly to Substack's endpoints using CycleTLS to bypass Cloudflare bot detection. No third-party proxy or gateway required.
+
+## Why This Fork?
+
+This project is based on [substack-api](https://github.com/jakub-k-slys/substack-api) by [Jakub Slys](https://github.com/jakub-k-slys). The original library routes all API requests through a third-party gateway proxy (`substack-gateway.vercel.app`), which means your Substack session cookies pass through a server you don't control. That's a dealbreaker for anyone handling user data or building a production application.
+
+This fork takes a different architectural approach:
+
+| | substack-api | substack-sdk |
+|---|---|---|
+| **HTTP layer** | Plain axios through a gateway proxy | CycleTLS directly to Substack (bypasses Cloudflare) |
+| **Authentication** | Cookies sent to a third-party proxy | Cookies sent directly to Substack |
+| **Credentials** | Single base64-encoded token | Two explicit cookies (`substack.sid` + `substack.lli`) |
+| **TLS handling** | Relies on gateway to handle Cloudflare | Spoofs browser TLS fingerprints via CycleTLS |
+| **Infrastructure** | Requires the gateway to be running | No external dependencies |
+
+The entity-based API, async iterators, and io-ts runtime validation from the original are preserved.
+
+## QuickStart
+
+```bash
+pnpm add @destink/substack-sdk
+```
+
+```typescript
+import { SubstackClient } from '@destink/substack-sdk';
+
+const client = new SubstackClient({
+  substackSid: process.env.SUBSTACK_SID!,
+  substackLli: process.env.SUBSTACK_LLI!,
+  publicationUrl: 'https://yoursite.substack.com',
+  handle: 'yourhandle'
+});
+
+// Get your profile and iterate through posts
+const profile = await client.ownProfile();
+for await (const post of profile.posts({ limit: 5 })) {
+  console.log(`"${post.title}" - ${post.publishedAt?.toLocaleDateString()}`);
+}
+
+// Test connectivity
+const isConnected = await client.testConnectivity();
+
+// Always close when done (shuts down the CycleTLS subprocess)
+await client.close();
+```
+
+## Authentication
+
+All requests go directly to Substack's API. Authentication requires two session cookies from your browser.
+
+### Step 1: Obtain your session cookies
+
+1. Log in to [substack.com](https://substack.com) in your browser.
+2. Open DevTools > Application > Cookies > `substack.com`.
+3. Copy the values of **`substack.sid`** and **`substack.lli`**.
+
+### Step 2: Pass the cookies to the client
+
+```typescript
+const client = new SubstackClient({
+  substackSid: '<value of substack.sid cookie>',
+  substackLli: '<value of substack.lli cookie>',
+  publicationUrl: 'https://yoursite.substack.com',
+  handle: 'yourhandle'  // required for ownProfile()
+});
+```
+
+## Documentation
+
+- [Installation Guide](docs/installation.md) - Setup and requirements
+- [QuickStart Tutorial](docs/quickstart.md) - Get started in minutes
+- [API Reference](docs/api-reference.md) - Complete method documentation
+- [Entity Model](docs/entity-model.md) - Modern object-oriented API
+- [Examples](docs/examples.md) - Real-world usage patterns
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,420 @@
+import * as t from 'io-ts';
+
+/**
+ * io-ts codecs and inferred types for Substack API response shapes.
+ *
+ * These match the real Substack API responses (not the gateway proxy).
+ * Fields are validated loosely — only the fields used by domain entities
+ * are required; extra fields from Substack are ignored by io-ts.
+ */
+
+declare const SubstackProfileC: t.IntersectionC<[t.TypeC<{
+    id: t.NumberC;
+    handle: t.StringC;
+    name: t.StringC;
+    photo_url: t.StringC;
+}>, t.PartialC<{
+    bio: t.UnionC<[t.StringC, t.NullC]>;
+}>]>;
+type SubstackProfile = t.TypeOf<typeof SubstackProfileC>;
+declare const SubstackFeedItemPostC: t.IntersectionC<[t.TypeC<{
+    id: t.NumberC;
+    title: t.StringC;
+    slug: t.StringC;
+    post_date: t.StringC;
+}>, t.PartialC<{
+    subtitle: t.UnionC<[t.StringC, t.NullC]>;
+    truncated_body_text: t.UnionC<[t.StringC, t.NullC]>;
+    body_html: t.UnionC<[t.StringC, t.NullC]>;
+    canonical_url: t.UnionC<[t.StringC, t.NullC]>;
+    reactions: t.UnionC<[t.RecordC<t.StringC, t.NumberC>, t.NullC]>;
+    restacks: t.UnionC<[t.NumberC, t.NullC]>;
+    cover_image: t.UnionC<[t.StringC, t.NullC]>;
+    publication_id: t.NumberC;
+    comment_count: t.NumberC;
+    type: t.StringC;
+}>]>;
+type SubstackFeedItemPost = t.TypeOf<typeof SubstackFeedItemPostC>;
+declare const SubstackFeedCommentC: t.IntersectionC<[t.TypeC<{
+    id: t.NumberC;
+    body: t.StringC;
+    user_id: t.NumberC;
+    date: t.StringC;
+}>, t.PartialC<{
+    name: t.UnionC<[t.StringC, t.NullC]>;
+    handle: t.UnionC<[t.StringC, t.NullC]>;
+    photo_url: t.UnionC<[t.StringC, t.NullC]>;
+    body_json: t.UnknownC;
+    publication_id: t.UnionC<[t.NumberC, t.NullC]>;
+    post_id: t.UnionC<[t.NumberC, t.NullC]>;
+    type: t.StringC;
+    reaction_count: t.NumberC;
+    reactions: t.UnionC<[t.RecordC<t.StringC, t.NumberC>, t.NullC]>;
+    restacks: t.NumberC;
+    children_count: t.NumberC;
+    attachments: t.ArrayC<t.UnknownC>;
+    ancestor_path: t.StringC;
+    edited_at: t.UnionC<[t.StringC, t.NullC]>;
+    reply_minimum_role: t.UnionC<[t.StringC, t.NullC]>;
+}>]>;
+type SubstackFeedComment = t.TypeOf<typeof SubstackFeedCommentC>;
+declare const SubstackFeedItemC: t.IntersectionC<[t.TypeC<{
+    entity_key: t.StringC;
+    type: t.StringC;
+}>, t.PartialC<{
+    publication: t.UnionC<[t.IntersectionC<[t.TypeC<{
+        id: t.NumberC;
+        subdomain: t.StringC;
+        name: t.StringC;
+    }>, t.PartialC<{
+        custom_domain: t.UnionC<[t.StringC, t.NullC]>;
+        logo_url: t.UnionC<[t.StringC, t.NullC]>;
+        author_id: t.NumberC;
+    }>]>, t.NullC]>;
+    post: t.UnionC<[t.IntersectionC<[t.TypeC<{
+        id: t.NumberC;
+        title: t.StringC;
+        slug: t.StringC;
+        post_date: t.StringC;
+    }>, t.PartialC<{
+        subtitle: t.UnionC<[t.StringC, t.NullC]>;
+        truncated_body_text: t.UnionC<[t.StringC, t.NullC]>;
+        body_html: t.UnionC<[t.StringC, t.NullC]>;
+        canonical_url: t.UnionC<[t.StringC, t.NullC]>;
+        reactions: t.UnionC<[t.RecordC<t.StringC, t.NumberC>, t.NullC]>;
+        restacks: t.UnionC<[t.NumberC, t.NullC]>;
+        cover_image: t.UnionC<[t.StringC, t.NullC]>;
+        publication_id: t.NumberC;
+        comment_count: t.NumberC;
+        type: t.StringC;
+    }>]>, t.NullC]>;
+    comment: t.UnionC<[t.IntersectionC<[t.TypeC<{
+        id: t.NumberC;
+        body: t.StringC;
+        user_id: t.NumberC;
+        date: t.StringC;
+    }>, t.PartialC<{
+        name: t.UnionC<[t.StringC, t.NullC]>;
+        handle: t.UnionC<[t.StringC, t.NullC]>;
+        photo_url: t.UnionC<[t.StringC, t.NullC]>;
+        body_json: t.UnknownC;
+        publication_id: t.UnionC<[t.NumberC, t.NullC]>;
+        post_id: t.UnionC<[t.NumberC, t.NullC]>;
+        type: t.StringC;
+        reaction_count: t.NumberC;
+        reactions: t.UnionC<[t.RecordC<t.StringC, t.NumberC>, t.NullC]>;
+        restacks: t.NumberC;
+        children_count: t.NumberC;
+        attachments: t.ArrayC<t.UnknownC>;
+        ancestor_path: t.StringC;
+        edited_at: t.UnionC<[t.StringC, t.NullC]>;
+        reply_minimum_role: t.UnionC<[t.StringC, t.NullC]>;
+    }>]>, t.NullC]>;
+}>]>;
+type SubstackFeedItem = t.TypeOf<typeof SubstackFeedItemC>;
+declare const SubstackFullPostC: t.IntersectionC<[t.TypeC<{
+    id: t.NumberC;
+    title: t.StringC;
+    slug: t.StringC;
+    post_date: t.StringC;
+}>, t.PartialC<{
+    subtitle: t.UnionC<[t.StringC, t.NullC]>;
+    body_html: t.UnionC<[t.StringC, t.NullC]>;
+    truncated_body_text: t.UnionC<[t.StringC, t.NullC]>;
+    canonical_url: t.UnionC<[t.StringC, t.NullC]>;
+    reactions: t.UnionC<[t.RecordC<t.StringC, t.NumberC>, t.NullC]>;
+    restacks: t.UnionC<[t.NumberC, t.NullC]>;
+    cover_image: t.UnionC<[t.StringC, t.NullC]>;
+    publication_id: t.NumberC;
+    type: t.StringC;
+    is_published: t.BooleanC;
+    comment_count: t.NumberC;
+}>]>;
+type SubstackFullPost = t.TypeOf<typeof SubstackFullPostC>;
+interface SubstackComment {
+    id: number;
+    body: string;
+    body_json?: unknown;
+    publication_id?: number | null;
+    post_id?: number | null;
+    user_id?: number;
+    ancestor_path?: string;
+    type?: string;
+    date?: string;
+    name?: string | null;
+    handle?: string | null;
+    photo_url?: string | null;
+    reaction_count?: number;
+    reactions?: Record<string, number> | null;
+    restacks?: number;
+    deleted?: boolean;
+    children?: SubstackComment[];
+}
+declare const SubstackCreateNoteResponseC: t.TypeC<{
+    id: t.NumberC;
+}>;
+type SubstackCreateNoteResponse = t.TypeOf<typeof SubstackCreateNoteResponseC>;
+
+type RequestScope = 'global' | 'publication' | {
+    subdomain: string;
+};
+declare class HttpClient {
+    private client;
+    private readonly headers;
+    private readonly publicationBaseUrl;
+    private lastRequestTime;
+    private readonly minInterval;
+    constructor(config: {
+        substackSid: string;
+        substackLli: string;
+        publicationUrl: string;
+        maxRequestsPerSecond?: number;
+    });
+    private getClient;
+    private throttle;
+    private resolveBaseUrl;
+    private buildUrl;
+    private parseResponseData;
+    get<T>(path: string, params?: Record<string, string | number | boolean | undefined>, scope?: RequestScope): Promise<T>;
+    post<T>(path: string, data?: unknown, scope?: RequestScope): Promise<T>;
+    put<T>(path: string, data?: unknown, scope?: RequestScope): Promise<T>;
+    delete(path: string, scope?: RequestScope): Promise<void>;
+    close(): Promise<void>;
+}
+
+interface PaginatedPosts {
+    posts: SubstackFeedItem[];
+    nextCursor?: string | null;
+}
+declare class PostService {
+    private readonly client;
+    constructor(client: HttpClient);
+    getPostBySlug(slug: string, subdomain?: string): Promise<SubstackFullPost>;
+    getPostsForProfile(userId: number, options?: {
+        cursor?: string;
+    }): Promise<PaginatedPosts>;
+}
+
+interface PaginatedNotes {
+    notes: SubstackFeedComment[];
+    nextCursor?: string | null;
+}
+declare class NoteService {
+    private readonly client;
+    constructor(client: HttpClient);
+    getNotesForProfile(userId: number, options?: {
+        cursor?: string;
+    }): Promise<PaginatedNotes>;
+}
+
+declare class ProfileService {
+    private readonly client;
+    constructor(client: HttpClient);
+    getOwnProfile(handle: string): Promise<SubstackProfile>;
+    getProfileBySlug(handle: string): Promise<SubstackProfile>;
+}
+
+declare class CommentService {
+    private readonly client;
+    constructor(client: HttpClient);
+    getCommentsForPost(postId: number, subdomain?: string): Promise<SubstackComment[]>;
+}
+
+interface FollowingUser {
+    id: number;
+    handle: string;
+}
+declare class FollowingService {
+    private readonly client;
+    constructor(client: HttpClient);
+    getFollowing(): Promise<FollowingUser[]>;
+}
+
+declare class NewNoteService {
+    private readonly client;
+    constructor(client: HttpClient);
+    publishNote(content: string, attachmentIds?: string[]): Promise<SubstackCreateNoteResponse>;
+}
+
+declare class Comment {
+    private readonly rawData;
+    readonly id: number;
+    readonly body: string;
+    readonly date?: string;
+    readonly authorName?: string;
+    readonly authorHandle?: string;
+    readonly reactionCount?: number;
+    constructor(rawData: SubstackComment);
+}
+
+interface Post {
+    readonly id: number;
+    readonly title: string;
+    readonly subtitle: string;
+    readonly body: string;
+    readonly truncatedBody: string;
+    readonly publishedAt: Date;
+    comments(options?: {
+        limit?: number;
+    }): AsyncIterable<Comment>;
+    like(): Promise<void>;
+    addComment(data: {
+        body: string;
+    }): Promise<Comment>;
+}
+declare class PreviewPost implements Post {
+    private readonly commentService;
+    private readonly postService;
+    readonly id: number;
+    readonly title: string;
+    readonly subtitle: string;
+    readonly body: string;
+    readonly truncatedBody: string;
+    readonly publishedAt: Date;
+    readonly slug: string;
+    readonly publicationSubdomain?: string;
+    constructor(rawData: SubstackFeedItemPost, commentService: CommentService, postService: PostService, publicationSubdomain?: string);
+    fullPost(): Promise<FullPost>;
+    comments(options?: {
+        limit?: number;
+    }): AsyncIterable<Comment>;
+    like(): Promise<void>;
+    addComment(_data: {
+        body: string;
+    }): Promise<Comment>;
+}
+declare class FullPost implements Post {
+    private readonly commentService;
+    private readonly publicationSubdomain?;
+    readonly id: number;
+    readonly title: string;
+    readonly subtitle: string;
+    readonly body: string;
+    readonly truncatedBody: string;
+    readonly publishedAt: Date;
+    readonly htmlBody: string;
+    readonly slug: string;
+    readonly createdAt: Date;
+    readonly reactions?: Record<string, number>;
+    readonly restacks?: number;
+    readonly coverImage?: string;
+    readonly url: string;
+    constructor(rawData: SubstackFullPost, commentService: CommentService, publicationSubdomain?: string | undefined);
+    comments(options?: {
+        limit?: number;
+    }): AsyncIterable<Comment>;
+    like(): Promise<void>;
+    addComment(_data: {
+        body: string;
+    }): Promise<Comment>;
+}
+
+declare class Note {
+    private readonly rawData;
+    readonly id: number;
+    readonly body: string;
+    readonly likesCount: number;
+    readonly author: {
+        id: number;
+        name: string;
+        handle: string;
+        avatarUrl: string;
+    };
+    readonly publishedAt: Date;
+    constructor(rawData: SubstackFeedComment);
+}
+
+declare class Profile {
+    protected readonly rawData: SubstackProfile;
+    protected readonly postService: PostService;
+    protected readonly noteService: NoteService;
+    protected readonly commentService: CommentService;
+    protected readonly perPage: number;
+    readonly id: number;
+    readonly slug: string;
+    readonly handle: string;
+    readonly name: string;
+    readonly url: string;
+    readonly avatarUrl: string;
+    readonly bio?: string;
+    constructor(rawData: SubstackProfile, postService: PostService, noteService: NoteService, commentService: CommentService, perPage: number);
+    posts(options?: {
+        limit?: number;
+    }): AsyncIterable<PreviewPost>;
+    notes(options?: {
+        limit?: number;
+    }): AsyncIterable<Note>;
+}
+
+declare class OwnProfile extends Profile {
+    private readonly profileService;
+    private readonly followingService;
+    private readonly newNoteService;
+    constructor(rawData: SubstackProfile, postService: PostService, noteService: NoteService, commentService: CommentService, profileService: ProfileService, followingService: FollowingService, newNoteService: NewNoteService, perPage: number);
+    publishNote(content: string, options?: {
+        attachmentIds?: string[];
+    }): Promise<SubstackCreateNoteResponse>;
+    following(options?: {
+        limit?: number;
+    }): AsyncIterable<Profile>;
+    notes(options?: {
+        limit?: number;
+    }): AsyncIterable<Note>;
+}
+
+/**
+ * Configuration interfaces for the Substack API client
+ */
+interface SubstackConfig {
+    substackSid: string;
+    substackLli: string;
+    publicationUrl: string;
+    handle?: string;
+    perPage?: number;
+    maxRequestsPerSecond?: number;
+}
+interface PaginationParams {
+    limit?: number;
+    offset?: number;
+}
+interface SearchParams extends PaginationParams {
+    query: string;
+    sort?: 'top' | 'new';
+    author?: string;
+}
+
+/**
+ * Domain interfaces for iterator options and user-facing types
+ */
+interface PostsIteratorOptions {
+    limit?: number;
+}
+interface CommentsIteratorOptions {
+    postId?: number;
+    limit?: number;
+}
+interface NotesIteratorOptions {
+    limit?: number;
+}
+
+declare class SubstackClient {
+    private readonly client;
+    private readonly postService;
+    private readonly noteService;
+    private readonly profileService;
+    private readonly commentService;
+    private readonly followingService;
+    private readonly connectivityService;
+    private readonly newNoteService;
+    private readonly perPage;
+    private readonly handle?;
+    constructor(config: SubstackConfig);
+    testConnectivity(): Promise<boolean>;
+    ownProfile(): Promise<OwnProfile>;
+    profileForHandle(handle: string): Promise<Profile>;
+    postForSlug(slug: string, publicationSubdomain?: string): Promise<FullPost>;
+    close(): Promise<void>;
+}
+
+export { Comment, FullPost, Note, OwnProfile, PreviewPost, Profile, SubstackClient };
+export type { CommentsIteratorOptions, NotesIteratorOptions, PaginationParams, PostsIteratorOptions, SearchParams, SubstackConfig, SubstackCreateNoteResponse };