# Content Automation

Automated content publishing for Pinterest and Instagram with AI-powered content generation and scheduling.

## Features

- ✅ **MCP Integration** ⭐ - Natural language control through AI assistants (primary way of working)
  - 📖 [Detailed MCP description](./MCP.md) - setup, prompt examples, troubleshooting
- ✅ **TypeScript** - Full type safety for reliability and better IDE support
- ✅ **Late API** - Publishing to Instagram and Pinterest through a unified API
- ✅ **Local Image Processing** - Automatic conversion (HEIC/PNG/GIF → JPG) and center-crop to platform aspect ratios via `sharp`
- ✅ **SCP Upload to CDN** - Processed images are automatically uploaded to your CDN server via `scp`
- ✅ Unique AI-powered content generation for Pinterest and Instagram (OpenAI with customizable prompts)
- ✅ Publication scheduling through Late API (no local scheduler needed)
- ✅ **Instagram Stories Support** - Publishing Stories through Late API
- ✅ **Instagram Carousel** - Publish 2–10 photos in one post (via MCP)
- ✅ Publishing to both platforms with a single request
- ✅ Processed image tracking
- ✅ OpenAI integration for content generation (optional)
- ✅ CLI commands - alternative way of working through terminal

## Installation

1. Install dependencies:
```bash
npm install
```

2. Build the TypeScript project:
```bash
npm run build
```

3. Copy `.env.example` to `.env` and fill it:
```bash
cp .env.example .env
```

4. Configure environment variables in `.env`:
   - **Late API** (required): Get API key at [getlate.dev](https://getlate.dev)
   - **CDN Base URL** (required): Specify the base CDN URL where images are hosted
   - **SCP Upload** (optional): Configure SCP to auto-upload processed local images to CDN
   - **OpenAI API** (optional): For AI-powered content generation
   - **Content Prompt** (optional): Customize content generation by copying `prompts/content-prompt.example.txt` to `prompts/content-prompt.txt` and editing it

## Getting API Keys

### Late API (Required) ⭐

The project uses **only Late API** for publishing to Instagram and Pinterest.

1. Register at [getlate.dev](https://getlate.dev)
2. Get API key
3. Connect Instagram and Pinterest accounts
4. Get Profile ID and Account IDs from the dashboard
5. Add to `.env`:
   ```
   LATE_API_KEY=your_key
   LATE_PROFILE_ID=your_profile_id
   LATE_INSTAGRAM_ACCOUNT_ID=your_instagram_account_id
   LATE_PINTEREST_ACCOUNT_ID=your_pinterest_account_id
   ```

**Late API Benefits:**
- ✅ No local scheduler needed - Late API publishes on schedule automatically
- ✅ Reliable scheduling on Late servers
- ✅ **Publishing to Instagram AND Pinterest with a single request** - saves API requests!
- ✅ Free plan available (60 requests/minute)
- ✅ Support for 13 platforms (Instagram, Pinterest, Facebook, LinkedIn, Twitter/X, TikTok, YouTube, Reddit, Bluesky, Threads, Google Business, Telegram, Snapchat)

**Supported Platforms:** Instagram, Pinterest, Facebook, LinkedIn, Twitter/X, TikTok, YouTube, Reddit, Bluesky, Threads, Google Business, Telegram, Snapchat

## Usage

The project supports **two ways of working**:

1. **Through MCP agent** (recommended) - Natural language control through AI assistant
2. **Through CLI commands** - Traditional way through terminal

### Setup Check

Before starting, check API connection:

```bash
npm run check
```

This will check:
- Late API connection (required)
- CDN configuration (required)
- SCP upload configuration (optional)
- OpenAI API availability (optional)

### CLI Commands

#### Publishing Images

```bash
npm run publish -- --image=IMG_5857.jpg [options]
```

**Image Input:**
- **Local file** (recommended): Place source images (HEIC, JPG, PNG, GIF) in the images directory. By default the system looks in `images/` (relative to project root); you can override with `IMAGES_SOURCE_DIR` in `.env` (e.g. an absolute path like `/path/to/story-matcher`). The system will convert to JPG, center-crop to platform aspect ratios, upload to CDN via SCP, and use the CDN URLs for publishing.
- **CDN URL**: If the image is already on CDN, pass the full URL — processing is skipped.
- **Filename only**: If SCP is not configured, the filename is resolved against `CDN_BASE_URL` directly (existing behavior).

**Examples:**
```bash
# Local image: auto-process + upload + publish to all platforms
npm run publish -- --image=IMG_5857.HEIC

# Publish in 1 hour
npm run publish -- --image=IMG_5857.jpg 1

# Draft with publication date
npm run publish -- --image=IMG_5857.jpg --date="tomorrow 18:00" --draft

# With context
npm run publish -- --image=IMG_5857.jpg 1 --context="City center"

# Instagram post only
npm run publish -- --image=IMG_5857.jpg --post

# Instagram story only
npm run publish -- --image=IMG_5857.jpg --story

# Instagram story + Pinterest pin (comma-separated)
npm run publish -- --image=IMG_5857.jpg --types=story,pin

# Instagram post + Pinterest pin
npm run publish -- --image=IMG_5857.jpg --types=post,pin

# Pinterest pin only
npm run publish -- --image=IMG_5857.jpg --pin

# With draft
npm run publish -- --image=IMG_5857.jpg --story --draft
```

**Options:**
- `--image=<filename>` - Image filename (required in CLI mode)
- `--context=<text>` - Context for content generation
- `--types=<list>` - Content types comma-separated: `post`, `story`, `pin` (e.g., `--types=story,pin`)
- `--post` - Instagram post only (short form for `--types=post`)
- `--story` - Instagram story only (short form for `--types=story`)
- `--pin` - Pinterest pin only (short form for `--types=pin`)
- (no flags) - All three types (default): Instagram post, Instagram story, Pinterest pin
- `--date=<date>` - Publication date (YYYY-MM-DD HH:MM or "tomorrow 18:00")
- `<hours>` - Alternative to --date: number of hours from current moment
- `--draft` or `-d` - Create as draft

**Content Types:**
- Default (nothing specified) - Publishes all three types: Instagram post, Instagram story, Pinterest pin
- `--types=post,story,pin` - Specify types comma-separated (e.g., `--types=story,pin`)
- `--post` - Publishes only Instagram post
- `--story` - Publishes only Instagram story
- `--pin` - Publishes only Pinterest pin (without Instagram)

**Detailed Documentation:**
- [CLI.md](./CLI.md) - Detailed CLI description with usage examples

### Building the Project

```bash
# Build TypeScript to JavaScript
npm run build

# Build and watch for changes (auto-recompiles on file changes)
npm run watch
```

### Using MCP in Dev Mode

When developing with MCP, use automatic recompilation:

```bash
# Terminal: Run watch for automatic recompilation
npm run watch
```

**How it works:**
1. `watch` automatically recompiles TypeScript when files change
2. Cursor automatically restarts MCP server when `dist/mcp/mcp-server.js` changes
3. You can immediately use updated MCP tools in Cursor chat

**Important:** After changing code in `src/mcp/` or related modules, changes will apply automatically through watch + MCP restart in Cursor.

**🔧 Dev Mode (dry-run):**
- In `watch` mode, `DEV_MODE=true` is automatically enabled
- **Requests to Late API are NOT sent** - instead, JSON ready to send is output
- This allows testing logic without real publications
- For real requests, use `npm run watch:prod` or simply `npm run build` + commands

### Using MCP Agent (Recommended) ⭐

**MCP (Model Context Protocol)** - This is the primary and recommended way to work with the project. Manage publications through AI assistant using natural language directly in Cursor, Claude, or other AI tools.

#### Quick Start with MCP

1. **Build the project:**
   ```bash
   npm run build
   ```

2. **MCP server is automatically available in Cursor** (via `.cursor/mcp.json`)

3. **Use natural language:**
   ```
   "Publish IMG_0802.HEIC tomorrow at 18:00 with context 'Concert hall, evening'"
   "Show list of available images"
   "Generate content for IMG_1460.JPG"
   "Schedule Story for IMG_2228.JPG today at 20:00"
   ```

**MCP Benefits:**
- ✅ **Natural language** - No need to remember commands
- ✅ **AI Integration** - Works directly in Cursor/Claude
- ✅ **Smart automation** - AI can plan publications itself
- ✅ **Contextual understanding** - AI understands your intentions

**Detailed Documentation:**
- [MCP.md](./MCP.md) - Setup, prompt examples, troubleshooting

### Using CLI Commands

Alternative way of working through terminal. Detailed documentation: [CLI.md](./CLI.md)

## Local Image Processing

The system can process local source images automatically — convert formats, crop to platform aspect ratios, and upload to CDN.

### How It Works

```
IMG_123.HEIC  (source image from IMAGES_SOURCE_DIR)
        │
        ├─ sharp: read → center-crop 4:5  → .processed/post/IMG_123.jpg
        ├─ sharp: read → center-crop 9:16 → .processed/story/IMG_123.jpg
        ├─ sharp: read → center-crop 2:3  → .processed/pin/IMG_123.jpg
        │
        ├─ scp: upload to CDN server
        │
        └─ CDN URLs used for publishing via Late API
```

### Supported Source Formats

HEIC, JPG, JPEG, PNG, GIF — all converted to JPEG (quality 90).

### Aspect Ratios (center-crop)

| Content Type | Ratio | Example Resolution |
|---|---|---|
| Instagram Post (`post`) | 4:5 | 1080×1350 |
| Instagram Story (`story`) | 9:16 | 1080×1920 |
| Pinterest Pin (`pin`) | 2:3 | 1000×1500 |

### Setup

1. **Place source images** in the images directory (default: `images/`, override with `IMAGES_SOURCE_DIR` in `.env`).

2. **Configure SCP upload** in `.env` (all 4 variables required together):
   ```
   SCP_HOST=cdn.example.com
   SCP_USER=deploy
   SCP_KEY_PATH=~/.ssh/id_rsa
   SCP_REMOTE_BASE_PATH=/var/www/cdn/images
   ```

3. **Ensure CDN_BASE_URL is set** — used to build public URLs from uploaded files.

### Caching

Processed images are cached in `.processed/`. If the output file already exists, processing is skipped. Delete `.processed/` to force reprocessing.

### Without SCP (URL-only mode)

If SCP is not configured, the system works as before — pass image filenames or URLs directly, and CDN URLs are built from `CDN_BASE_URL`. Local image processing is only triggered when a local filename is provided and SCP is configured.

## Project Structure

The project is organized on a **modular principle** for better scalability and support.

### Main Modules:

- **`src/core/`** - Core infrastructure (cache with LRU eviction, retry with exponential backoff, rate limiting, logger, error definitions, config, validation schemas)
- **`src/services/`** - API services (Late API, CDN uploader)
- **`src/generators/`** - Content generators (AI-powered with customizable prompts)
- **`src/processors/`** - Data processors (image pipeline, sharp processor)
- **`src/utils/`** - Utilities (CDN URL builder, scheduling, date and shared helpers)
- **`src/cli/`** - CLI commands and entry points
- **`src/mcp/`** - MCP integration for AI assistants
- **`src/types/`** - TypeScript types and interfaces
- **`prompts/`** - Content generation prompts (customizable)
- **`.processed/`** - Processed image cache (gitignored)

### Modular Structure Benefits:

✅ **Separation of concerns** - Each module is responsible for its area
✅ **Singleton pattern** - Services are exported as singleton instances
✅ **Direct imports** - Simplified structure without intermediate index.ts
✅ **Scalability** - Easy to add new services
✅ **Testability** - Each module can be tested separately


## Content Format

### Pinterest
- **Title**: SEO-optimized headline
- **Description**: Description with keywords
- **Keywords**: List of keywords
- **CTA**: Call to action (leads to Instagram)

### Instagram Posts
- **Caption**: Emotional story text
- **Hashtags**: 3-5 relevant hashtags (customizable via content prompt)

### Instagram Stories
- Stories do not support long captions
- Text overlays can be used (via API)
- User mentions (user_tags) are supported
- Automatically disappear after 24 hours

## Limitations and Capabilities

### Late API
- ✅ **Only Late API is used** for publishing to Instagram and Pinterest
- ✅ Native scheduling through Late API
- ✅ Does not require local scheduler
- ✅ Publishing to both platforms with a single request
- ✅ Support for media file upload or using public CDN URLs
- ✅ **Supports Stories** - Can publish Stories through Late API
- ⚠️ **Stories limitations**: Can only schedule for the next 24 hours
- ⚠️ Free plan: 60 requests/minute

### CDN for Images

Two modes of operation:

**1. Local processing + SCP upload (recommended):**
- Place source images in the images directory (default: `images/`, configurable via `IMAGES_SOURCE_DIR`)
- Configure SCP variables in `.env`
- System auto-converts, crops, uploads, and builds CDN URLs
- Supports HEIC, JPG, PNG, GIF input formats

**2. Direct CDN URLs (no local processing):**
- Images must already be on CDN in correct aspect ratios
- Specify `CDN_BASE_URL` in `.env`
- Pass filename or full URL in commands
- The system builds CDN URLs by content type:
  - `post` → `{CDN_BASE_URL}/post/{filename}`
  - `story` → `{CDN_BASE_URL}/story/{filename}`
  - `pin` → `{CDN_BASE_URL}/pin/{filename}`
- **Important:** Filenames are case-sensitive - use exact case as on CDN


## Content Generation Customization

The content generation prompt can be customized to match your brand voice and target audience:

1. **Copy the example prompt:**
   ```bash
   cp prompts/content-prompt.example.txt prompts/content-prompt.txt
   ```

2. **Edit `prompts/content-prompt.txt`** with your custom instructions:
   - Adjust tone and style
   - Modify hashtag requirements
   - Change content focus and goals
   - Update output format if needed

3. **The custom prompt is automatically loaded** - no code changes needed!

**Note:** `prompts/content-prompt.txt` is ignored by git, so your customizations remain private. The example file (`content-prompt.example.txt`) serves as a template and is version-controlled.

## Security

- Never commit `.env` file
- Never commit `prompts/content-prompt.txt` (already in `.gitignore`)
- Store API keys in a secure place
- Regularly check Late API key expiration
- Do not share API keys publicly
- `SCP_KEY_PATH` points to your SSH key — ensure it has proper file permissions (`chmod 600`)

## Troubleshooting

### Late API Connection Error
- Check API key correctness: `npm run check`
- Make sure both accounts (Instagram and Pinterest) are connected in Late
- Check API key expiration

### Publication Error
- Make sure Instagram and Pinterest accounts are connected in Late
- Check account access rights
- Make sure images are available on CDN at specified URLs

### Images Not Processing
- Check file formats (supported: HEIC, JPG, PNG, GIF)
- Make sure files are not corrupted
- **Check filename case** - Filename is case-sensitive (e.g., `IMG_5857.jpg` ≠ `img_5857.jpg`)
- Verify the source file exists in the images source directory (default: `images/`, or `IMAGES_SOURCE_DIR` if set)
- Check `.processed/` for cached output — delete to force reprocessing

### SCP Upload Failing
- Verify all 4 SCP variables are set in `.env`: `SCP_HOST`, `SCP_USER`, `SCP_KEY_PATH`, `SCP_REMOTE_BASE_PATH`
- Check that your SSH key exists at the specified `SCP_KEY_PATH` and has correct permissions (`chmod 600`)
- Test SSH connectivity manually: `ssh -i ~/.ssh/id_rsa user@host`
- Check that the remote base path exists and is writable

### CDN Not Working
- Make sure `CDN_BASE_URL` is specified correctly
- Check that images are available at specified URLs
- Make sure URLs are publicly accessible

## License

MIT