content_automation

# 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