Social Scheduler

A Node.js application for scheduling and automating social media posts to Facebook and Instagram using Meta's Graph API.

Features

📅 Smart Scheduling: Schedule posts using cron expressions or specific dates with timezone support
🤖 AI-Powered Captions: Automatic caption generation using OpenAI for alumni photos and events
🎯 Intelligent Schedule Generation: AI-driven natural posting schedules from image directories
🖼️ Content Processing: Automatic content optimization for Facebook and Instagram
📱 Meta Integration: Direct posting to Facebook Pages and Instagram via Graph API
📝 Comprehensive Logging: Detailed logging with daily rotation and multiple log streams
✅ Validation: Content, image, and schedule validation before posting
🕒 Timezone Aware: Global timezone support with optimal posting time suggestions
🔄 Retry Logic: Intelligent retry mechanisms for failed posts
📊 Health Monitoring: Built-in health checks and metrics endpoints
📋 Schedule Management: JSON-based schedule configuration with templates

Project Structure

social-scheduler/
├── package.json              # Dependencies and npm scripts
├── .env                      # Environment variables (template)
├── .gitignore               # Git ignore rules
├── README.md                # Project documentation
├── src/
│   ├── app.js               # Main application entry point
│   ├── config/
│   │   ├── meta-api.js      # Meta API endpoints, limits, and error codes
│   │   └── scheduler.js     # Scheduler settings and cron patterns
│   ├── services/
│   │   ├── caption-generator.js   # OpenAI-powered caption generation
│   │   ├── content-processor.js   # Content optimization and validation
│   │   ├── file-reader.js         # File and schedule configuration reading
│   │   ├── meta-client.js         # Facebook & Instagram API client
│   │   └── schedule-generator.js  # AI-driven schedule generation
│   └── utils/
│       ├── batch-caption.js       # Batch caption generation utility
│       ├── generate-schedule.js   # Schedule generation CLI tool
│       ├── logger.js              # Winston logging with daily rotation
│       └── validators.js          # Comprehensive validation utilities
├── content/
│   ├── posts/               # Text content files (.txt, .md, .json)
│   ├── images/              # Image files for posting
│   │   └── processed/       # Platform-optimized images (auto-generated)
│   ├── captions/            # AI-generated captions with metadata
│   └── schedule.json        # Main schedule configuration
└── logs/                    # Application logs (auto-created)

Installation

Clone the repository

git clone <repository-url>
cd social-scheduler

Install dependencies
```
npm install
```

Configure environment variables

cp .env .env.local
# Edit .env.local with your Meta API credentials

Set up Meta API credentials
- Create a Facebook App at developers.facebook.com
- Get Page access token for Facebook posting
- Get Instagram Business account access token
- Add credentials to your .env file

Configuration

Environment Variables

# Meta API Credentials
FACEBOOK_ACCESS_TOKEN=your_page_access_token
FACEBOOK_PAGE_ID=your_facebook_page_id
INSTAGRAM_ACCESS_TOKEN=your_instagram_access_token

# OpenAI Integration (for AI features)
OPENAI_API_KEY=your_openai_api_key

# Application Settings
NODE_ENV=development
PORT=3000
LOG_LEVEL=info
TIMEZONE=Europe/Nicosia

Schedule Configuration

Create or modify content/schedule.json:

{
  "settings": {
    "timezone": "Europe/Nicosia",
    "retryAttempts": 3,
    "enableNotifications": true
  },
  "posts": [
    {
      "id": "morning_post",
      "content": "Good morning! 🌅",
      "platforms": ["facebook", "instagram"],
      "scheduledTime": "2024-12-15T09:00:00",
      "images": ["content/images/morning.jpg"],
      "priority": "high"
    },
    {
      "id": "alumni_auto_caption",
      "generateCaption": true,
      "metadata": {
        "year": "1985",
        "event": "class photograph",
        "location": "main hall"
      },
      "platforms": ["facebook", "instagram"],
      "scheduledTime": "2024-12-16T14:30:00",
      "images": ["content/images/class_1985.jpg"]
    }
  ]
}

Usage

Running the Application

# Production mode
npm start

# Development mode (with debug logging)
npm run dev

# Direct execution
node src/app.js

Health Monitoring

The application provides several HTTP endpoints:

http://localhost:3000/health - Basic health status
http://localhost:3000/status - Detailed application state
http://localhost:3000/metrics - Performance metrics

AI Features

Generate Captions for Existing Content

# Interactive caption generation
npm run batch-caption

# Generate captions for all images in schedule
npm run batch-caption:schedule

# Generate with configuration file
npm run batch-caption:config

Auto-Generate Posting Schedules

# Interactive schedule generation
npm run generate-schedule

# Automated generation with defaults
npm run generate-schedule:auto

# Preview what would be generated
npm run generate-schedule:dry-run

Content Management

Text Content: Place .txt or .md files in content/posts/
Images: Place image files in content/images/
AI Captions: Generated captions saved in content/captions/ with metadata
Scheduling: Configure posts in content/schedule.json
AI Generation: Use npm scripts for automated caption and schedule creation

Example Content Files

content/posts/sample_post.txt

🚀 Exciting news! We're launching our new feature today.

✨ What's new:
• Advanced scheduling
• Better analytics
• Improved UI

#ProductLaunch #Innovation

Core Components

Meta Client (`src/services/meta-client.js`)

Facebook Graph API v18.0 integration
Instagram Basic Display API support
Rate limiting and error handling
Image upload and post publishing

Caption Generator (`src/services/caption-generator.js`)

OpenAI GPT-4o-mini integration for alumni-focused captions
Contextual metadata processing for school events (year, event, location)
Batch processing with cost estimation and rate limiting
Alumni association writing style with engagement prompts
Automatic caption saving with generation metadata

Schedule Generator (`src/services/schedule-generator.js`)

AI-powered natural posting schedule creation
Intelligent time distribution (10am-8pm constraint)
Metadata extraction from image filenames
Cost estimation and validation safeguards

Content Processor (`src/services/content-processor.js`)

Platform-specific content optimization
Auto-caption integration
Image processing and validation
Hashtag and mention handling
Text length and format validation

File Reader (`src/services/file-reader.js`)

Reads text content from files
Validates image files
Parses schedule.json configuration
Provides structured data for processing

Logger (`src/utils/logger.js`)

Multiple log streams (API, scheduler, performance)
Daily log rotation with 14-day retention
Structured logging with metadata
Console and file output

Validators (`src/utils/validators.js`)

Schedule configuration validation
Content and image validation
DateTime and timezone validation
Meta API response validation
AI generation option validation

Platform Specifications

Facebook

Text: Up to 63,206 characters
Images: JPEG, PNG, GIF, WebP (max 100MB)
Hashtags: Up to 30 recommended
Rate Limits: 200 requests/hour

Instagram

Text: Up to 2,200 characters
Images: JPEG, PNG (max 30MB, requires at least one image)
Hashtags: Up to 30 recommended
Aspect Ratios: 0.8 - 1.91 (4:5 to 16:9)
Rate Limits: 200 requests/hour

Logging

The application uses Winston with daily rotation:

logs/combined-YYYY-MM-DD.log - All log levels
logs/error-YYYY-MM-DD.log - Error-only logs
logs/api-YYYY-MM-DD.log - API operation logs
logs/scheduler-YYYY-MM-DD.log - Job execution logs
logs/performance-YYYY-MM-DD.log - Performance metrics

Log files are compressed after rotation and kept for 14 days.

Development

Adding New Features

New Platforms: Extend meta-client.js with new API integrations
Content Types: Add processors to content-processor.js
AI Features: Enhance caption-generator.js or schedule-generator.js
Validators: Add validation rules to validators.js
Scheduling: Modify cron patterns in config/scheduler.js

Configuration Files

src/config/meta-api.js: API endpoints, limits, error codes
src/config/scheduler.js: Cron patterns, retry policies, queue settings

Testing

# Check application health
curl http://localhost:3000/health

# View detailed status
curl http://localhost:3000/status

# Monitor metrics
curl http://localhost:3000/metrics

Deployment

Production Setup

Set NODE_ENV=production
Configure proper timezone
Set up log rotation monitoring
Configure process manager (PM2, systemd, etc.)
Set up health check monitoring

Docker Support

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

Troubleshooting

Common Issues

API Authentication: Ensure tokens have proper permissions
Rate Limits: Monitor /metrics endpoint for usage
Image Formats: Check platform-specific requirements
Timezone Issues: Validate timezone strings in configuration
Schedule Validation: Check schedule.json format

Error Codes

The application maps Meta API error codes to actionable messages:

190: Invalid access token - refresh credentials
613: Rate limit exceeded - wait and retry
368: Content rejected - review content guidelines

Security

API credentials stored in environment variables
No sensitive data in logs
Rate limiting to prevent API abuse
Input validation and sanitization
Error handling without data exposure

License

ISC

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes following the coding standards
Add tests if applicable
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Support

For issues and questions:

Check the troubleshooting section
Review application logs in logs/ directory
Check health endpoints for system status
Open an issue with detailed error information

Name		Name	Last commit message	Last commit date
content		content
src		src
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation