@hasna/connectors 0.0.1

package/connectors/connect-substack/CLAUDE.md

@@ -0,0 +1,168 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+connect-substack is a TypeScript connector for Substack's unofficial API with multi-profile configuration support. It provides both a CLI tool and a TypeScript library for programmatic access. Since Substack doesn't have a public API, this connector uses reverse-engineered endpoints with cookie-based authentication.
+
+## Build & Run Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build for distribution
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (`type: module`)
+- Async/await for all async operations
+- Minimal dependencies: commander, chalk
+- Type annotations required everywhere
+
+## Project Structure
+
+```
+src/
+├── api/           # API client modules
+│   ├── client.ts  # HTTP client with authentication
+│   └── index.ts   # Main connector class
+├── cli/
+│   └── index.ts   # CLI commands
+├── types/
+│   └── index.ts   # TypeScript types
+├── utils/
+│   ├── config.ts  # Multi-profile configuration
+│   └── output.ts  # CLI output formatting
+└── index.ts       # Library exports
+```
+
+## Authentication
+
+API Key authentication. Credentials can be set via:
+- Environment variable (see below)
+- Profile configuration: `connect-substack config set-key <key>`
+
+
+## Key Patterns
+
+### Multi-Profile Configuration
+
+Profiles stored in `~/.connect/connect-substack/profiles/`:
+- Each profile is a separate JSON file
+- `current_profile` file tracks active profile
+- `--profile` flag overrides for single command
+- Environment variables `SUBSTACK_SUBDOMAIN` and `SUBSTACK_TOKEN` override profile config
+
+### Authentication
+
+Uses cookie-based authentication with the `substack.sid` session token:
+1. Log in to Substack in your browser
+2. Open Developer Tools > Application > Cookies
+3. Find the `substack.sid` cookie value
+4. Use this as the token in the connector
+
+Credentials can be set via:
+- Environment variables: `SUBSTACK_SUBDOMAIN`, `SUBSTACK_TOKEN`
+- Profile configuration: `connect-substack config set --subdomain <name> --token <token>`
+
+### Service APIs
+
+Each Substack feature has its own API module:
+- **PostsApi**: List posts, get post, create draft, publish, delete
+- **SubscribersApi**: List subscribers, get stats, export
+- **CommentsApi**: List comments on posts
+- **StatsApi**: Publication stats, subscriber growth
+- **PublicationApi**: Publication info, sections, user info
+
+## CLI Commands
+
+### Posts
+```bash
+connect-substack posts list                    # List published posts
+connect-substack posts list --drafts           # List drafts
+connect-substack posts list -n 50              # Limit results
+connect-substack posts list -t newsletter      # Filter by type
+connect-substack posts get <postId>            # Get post by ID
+connect-substack posts get <slug>              # Get post by slug
+connect-substack posts create --title "Title" --body "Content"  # Create draft
+connect-substack posts create --title "Title" --body "Content" --publish  # Create and publish
+connect-substack posts create --title "Title" --body "Content" --publish --send  # Publish and email
+connect-substack posts publish <draftId>       # Publish a draft
+connect-substack posts publish <draftId> --send  # Publish and send email
+connect-substack posts delete <draftId>        # Delete a draft
+```
+
+### Subscribers
+```bash
+connect-substack subscribers list              # List all subscribers
+connect-substack subscribers list -t paid      # Filter by type (free, paid, comp, gift)
+connect-substack subscribers list -s "email"   # Search by email/name
+connect-substack subscribers stats             # Get subscriber statistics
+connect-substack subscribers export            # Export subscribers (CSV)
+connect-substack subscribers export --format json  # Export as JSON
+```
+
+### Comments
+```bash
+connect-substack comments list <postId>        # List comments on a post
+connect-substack comments list <postId> --sort newest  # Sort by newest
+```
+
+### Stats & Publication
+```bash
+connect-substack stats                         # Get publication statistics
+connect-substack publication                   # Get publication info
+connect-substack pub                           # Alias for publication
+connect-substack me                            # Get current user info
+```
+
+### Output Formats
+```bash
+connect-substack -f yaml posts list    # YAML output (default)
+connect-substack -f json posts list    # JSON output
+connect-substack -f pretty posts list  # Pretty-printed output
+```
+
+### Profile & Config
+```bash
+connect-substack profile list                  # List profiles
+connect-substack profile use <name>            # Switch profile
+connect-substack profile create <name>         # Create profile
+connect-substack profile create <name> --subdomain <sub> --token <tok> --use
+connect-substack config set --subdomain <name> --token <token>  # Set credentials
+connect-substack config show                   # Show configuration
+connect-substack config clear                  # Clear configuration
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SUBSTACK_SUBDOMAIN` | Publication subdomain (overrides profile) |
+| `SUBSTACK_TOKEN` | Session token - substack.sid cookie (overrides profile) |
+
+## Data Storage
+
+```
+~/.connect/connect-substack/
+├── current_profile   # Active profile name
+└── profiles/
+    ├── default.json  # Default profile
+    └── {name}.json   # Named profiles
+```
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling

package/connectors/connect-substack/GEMINI.md

@@ -0,0 +1,168 @@
+# GEMINI.md
+
+This file provides guidance to Gemini when working with this repository.
+
+## Project Overview
+
+connect-substack is a TypeScript connector for Substack's unofficial API with multi-profile configuration support. It provides both a CLI tool and a TypeScript library for programmatic access. Since Substack doesn't have a public API, this connector uses reverse-engineered endpoints with cookie-based authentication.
+
+## Build & Run Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build for distribution
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (`type: module`)
+- Async/await for all async operations
+- Minimal dependencies: commander, chalk
+- Type annotations required everywhere
+
+## Project Structure
+
+```
+src/
+├── api/           # API client modules
+│   ├── client.ts  # HTTP client with authentication
+│   └── index.ts   # Main connector class
+├── cli/
+│   └── index.ts   # CLI commands
+├── types/
+│   └── index.ts   # TypeScript types
+├── utils/
+│   ├── config.ts  # Multi-profile configuration
+│   └── output.ts  # CLI output formatting
+└── index.ts       # Library exports
+```
+
+## Authentication
+
+API Key authentication. Credentials can be set via:
+- Environment variable (see below)
+- Profile configuration: `connect-substack config set-key <key>`
+
+
+## Key Patterns
+
+### Multi-Profile Configuration
+
+Profiles stored in `~/.connect/connect-substack/profiles/`:
+- Each profile is a separate JSON file
+- `current_profile` file tracks active profile
+- `--profile` flag overrides for single command
+- Environment variables `SUBSTACK_SUBDOMAIN` and `SUBSTACK_TOKEN` override profile config
+
+### Authentication
+
+Uses cookie-based authentication with the `substack.sid` session token:
+1. Log in to Substack in your browser
+2. Open Developer Tools > Application > Cookies
+3. Find the `substack.sid` cookie value
+4. Use this as the token in the connector
+
+Credentials can be set via:
+- Environment variables: `SUBSTACK_SUBDOMAIN`, `SUBSTACK_TOKEN`
+- Profile configuration: `connect-substack config set --subdomain <name> --token <token>`
+
+### Service APIs
+
+Each Substack feature has its own API module:
+- **PostsApi**: List posts, get post, create draft, publish, delete
+- **SubscribersApi**: List subscribers, get stats, export
+- **CommentsApi**: List comments on posts
+- **StatsApi**: Publication stats, subscriber growth
+- **PublicationApi**: Publication info, sections, user info
+
+## CLI Commands
+
+### Posts
+```bash
+connect-substack posts list                    # List published posts
+connect-substack posts list --drafts           # List drafts
+connect-substack posts list -n 50              # Limit results
+connect-substack posts list -t newsletter      # Filter by type
+connect-substack posts get <postId>            # Get post by ID
+connect-substack posts get <slug>              # Get post by slug
+connect-substack posts create --title "Title" --body "Content"  # Create draft
+connect-substack posts create --title "Title" --body "Content" --publish  # Create and publish
+connect-substack posts create --title "Title" --body "Content" --publish --send  # Publish and email
+connect-substack posts publish <draftId>       # Publish a draft
+connect-substack posts publish <draftId> --send  # Publish and send email
+connect-substack posts delete <draftId>        # Delete a draft
+```
+
+### Subscribers
+```bash
+connect-substack subscribers list              # List all subscribers
+connect-substack subscribers list -t paid      # Filter by type (free, paid, comp, gift)
+connect-substack subscribers list -s "email"   # Search by email/name
+connect-substack subscribers stats             # Get subscriber statistics
+connect-substack subscribers export            # Export subscribers (CSV)
+connect-substack subscribers export --format json  # Export as JSON
+```
+
+### Comments
+```bash
+connect-substack comments list <postId>        # List comments on a post
+connect-substack comments list <postId> --sort newest  # Sort by newest
+```
+
+### Stats & Publication
+```bash
+connect-substack stats                         # Get publication statistics
+connect-substack publication                   # Get publication info
+connect-substack pub                           # Alias for publication
+connect-substack me                            # Get current user info
+```
+
+### Output Formats
+```bash
+connect-substack -f yaml posts list    # YAML output (default)
+connect-substack -f json posts list    # JSON output
+connect-substack -f pretty posts list  # Pretty-printed output
+```
+
+### Profile & Config
+```bash
+connect-substack profile list                  # List profiles
+connect-substack profile use <name>            # Switch profile
+connect-substack profile create <name>         # Create profile
+connect-substack profile create <name> --subdomain <sub> --token <tok> --use
+connect-substack config set --subdomain <name> --token <token>  # Set credentials
+connect-substack config show                   # Show configuration
+connect-substack config clear                  # Clear configuration
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SUBSTACK_SUBDOMAIN` | Publication subdomain (overrides profile) |
+| `SUBSTACK_TOKEN` | Session token - substack.sid cookie (overrides profile) |
+
+## Data Storage
+
+```
+~/.connect/connect-substack/
+├── current_profile   # Active profile name
+└── profiles/
+    ├── default.json  # Default profile
+    └── {name}.json   # Named profiles
+```
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling

package/connectors/connect-substack/README.md

@@ -0,0 +1,146 @@
+# connect-substack
+
+Substack connector CLI - Posts, subscribers, stats with multi-profile support
+
+## Installation
+
+```bash
+bun install -g @hasna/connect-substack
+```
+
+## Quick Start
+
+```bash
+# Set your API key
+connect-substack config set-key YOUR_API_KEY
+
+# Or use environment variable
+export SUBSTACK_SUBDOMAIN=YOUR_API_KEY
+```
+
+## CLI Commands
+
+### Posts
+```bash
+connect-substack posts list                    # List published posts
+connect-substack posts list --drafts           # List drafts
+connect-substack posts list -n 50              # Limit results
+connect-substack posts list -t newsletter      # Filter by type
+connect-substack posts get <postId>            # Get post by ID
+connect-substack posts get <slug>              # Get post by slug
+connect-substack posts create --title "Title" --body "Content"  # Create draft
+connect-substack posts create --title "Title" --body "Content" --publish  # Create and publish
+connect-substack posts create --title "Title" --body "Content" --publish --send  # Publish and email
+connect-substack posts publish <draftId>       # Publish a draft
+connect-substack posts publish <draftId> --send  # Publish and send email
+connect-substack posts delete <draftId>        # Delete a draft
+```
+
+### Subscribers
+```bash
+connect-substack subscribers list              # List all subscribers
+connect-substack subscribers list -t paid      # Filter by type (free, paid, comp, gift)
+connect-substack subscribers list -s "email"   # Search by email/name
+connect-substack subscribers stats             # Get subscriber statistics
+connect-substack subscribers export            # Export subscribers (CSV)
+connect-substack subscribers export --format json  # Export as JSON
+```
+
+### Comments
+```bash
+connect-substack comments list <postId>        # List comments on a post
+connect-substack comments list <postId> --sort newest  # Sort by newest
+```
+
+### Stats & Publication
+```bash
+connect-substack stats                         # Get publication statistics
+connect-substack publication                   # Get publication info
+connect-substack pub                           # Alias for publication
+connect-substack me                            # Get current user info
+```
+
+### Output Formats
+```bash
+connect-substack -f yaml posts list    # YAML output (default)
+connect-substack -f json posts list    # JSON output
+connect-substack -f pretty posts list  # Pretty-printed output
+```
+
+### Profile & Config
+```bash
+connect-substack profile list                  # List profiles
+connect-substack profile use <name>            # Switch profile
+connect-substack profile create <name>         # Create profile
+connect-substack profile create <name> --subdomain <sub> --token <tok> --use
+connect-substack config set --subdomain <name> --token <token>  # Set credentials
+connect-substack config show                   # Show configuration
+connect-substack config clear                  # Clear configuration
+```
+
+## Profile Management
+
+```bash
+# Create profiles for different accounts
+connect-substack profile create work --api-key xxx --use
+connect-substack profile create personal --api-key yyy
+
+# Switch profiles
+connect-substack profile use work
+
+# Use profile for single command
+connect-substack -p personal <command>
+
+# List profiles
+connect-substack profile list
+```
+
+## Library Usage
+
+```typescript
+import { Substack } from '@hasna/connect-substack';
+
+const client = new Substack({ apiKey: 'YOUR_API_KEY' });
+
+// Use the client
+// See CLAUDE.md for detailed API documentation
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SUBSTACK_SUBDOMAIN` | Publication subdomain (overrides profile) |
+| `SUBSTACK_TOKEN` | Session token - substack.sid cookie (overrides profile) |
+
+## Data Storage
+
+Configuration stored in `~/.connect/connect-substack/`:
+
+```
+~/.connect/connect-substack/
+├── current_profile   # Active profile name
+└── profiles/
+    ├── default.json  # Default profile
+    └── {name}.json   # Named profiles
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## License
+
+MIT

package/connectors/connect-substack/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@hasna/connect-substack",
+  "version": "0.0.1",
+  "description": "Substack connector CLI - Posts, subscribers, stats with multi-profile support",
+  "type": "module",
+  "bin": {
+    "connect-substack": "./bin/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "dev": "bun run ./src/cli/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "substack",
+    "newsletter",
+    "posts",
+    "subscribers",
+    "connector",
+    "cli",
+    "typescript",
+    "bun",
+    "hasna"
+  ],
+  "author": "Hasna",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/opensource-connectors.git"
+  }
+}

package/connectors/connect-substack/src/api/client.ts

@@ -0,0 +1,147 @@
+import type { SubstackConfig } from '../types';
+import { SubstackApiError } from '../types';
+
+/**
+ * Get the Substack API base URL for a subdomain
+ */
+function getApiBase(subdomain: string): string {
+  return `https://${subdomain}.substack.com/api/v1`;
+}
+
+export interface SubstackRequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  body?: unknown;
+  headers?: Record<string, string>;
+  params?: Record<string, string | number | boolean | undefined>;
+}
+
+/**
+ * Substack API Client
+ * Uses cookie-based authentication with the substack.sid session token
+ */
+export class SubstackClient {
+  private readonly subdomain: string;
+  private readonly token: string;
+
+  constructor(config: SubstackConfig) {
+    if (!config.subdomain) {
+      throw new Error('Substack subdomain is required');
+    }
+    if (!config.token) {
+      throw new Error('Substack session token is required');
+    }
+    this.subdomain = config.subdomain;
+    this.token = config.token;
+  }
+
+  /**
+   * Get the API base URL
+   */
+  getApiBase(): string {
+    return getApiBase(this.subdomain);
+  }
+
+  /**
+   * Make a request to the Substack API
+   */
+  async request<T>(path: string, options: SubstackRequestOptions = {}): Promise<T> {
+    const { method = 'GET', body, headers = {}, params } = options;
+
+    let url = `${this.getApiBase()}${path}`;
+
+    // Add query params
+    if (params) {
+      const searchParams = new URLSearchParams();
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          searchParams.append(key, String(value));
+        }
+      });
+      const queryString = searchParams.toString();
+      if (queryString) {
+        url += `?${queryString}`;
+      }
+    }
+
+    const requestHeaders: Record<string, string> = {
+      'Cookie': `substack.sid=${this.token}`,
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+      'User-Agent': 'connect-substack/0.0.1',
+      ...headers,
+    };
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+      credentials: 'include',
+    };
+
+    if (body) {
+      fetchOptions.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    // Handle response
+    let data: unknown;
+    const contentType = response.headers.get('content-type') || '';
+
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    if (contentType.includes('application/json')) {
+      const text = await response.text();
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          data = text;
+        }
+      }
+    } else {
+      data = await response.text();
+    }
+
+    if (!response.ok) {
+      const requestId = response.headers.get('x-request-id') || undefined;
+      let errorMessage = `Substack API Error: ${response.status} ${response.statusText}`;
+      let errorCode: string | undefined;
+
+      if (typeof data === 'object' && data !== null) {
+        const errData = data as Record<string, unknown>;
+        errorCode = errData.code as string | undefined;
+        const errMsg = errData.message || errData.error || errData.errors;
+        if (typeof errMsg === 'string') {
+          errorMessage = errMsg;
+        } else if (Array.isArray(errMsg) && errMsg.length > 0) {
+          errorMessage = errMsg.map((e) => (typeof e === 'object' ? (e as Record<string, unknown>).message || JSON.stringify(e) : String(e))).join(', ');
+        }
+      } else if (typeof data === 'string' && data) {
+        errorMessage = data;
+      }
+
+      throw new SubstackApiError(errorMessage, response.status, errorCode, requestId);
+    }
+
+    return data as T;
+  }
+
+  /**
+   * Get the subdomain
+   */
+  getSubdomain(): string {
+    return this.subdomain;
+  }
+
+  /**
+   * Get a preview of the token (for display/debugging)
+   */
+  getTokenPreview(): string {
+    if (this.token.length > 8) {
+      return `${this.token.substring(0, 4)}...${this.token.substring(this.token.length - 4)}`;
+    }
+    return '***';
+  }
+}