HERALD — Social Media Automation System

// schema.prisma
model Post {
  id          String   @id @default(uuid())
  platform    Platform @default(FACEBOOK)
  content     String
  mediaUrls   String[]
  status      PostStatus @default(DRAFT)
  scheduledAt DateTime?
  publishedAt DateTime?
  platformPostId String?
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  
  @@index([status])
  @@index([scheduledAt])
}

// queue/post.queue.ts
@Injectable()
export class PostQueueService {
  async addPublishJob(post: Post, token: MetaToken) {
    const queue = this.queueManager.getQueue(token.id);
    
    await queue.add('publish', {
      postId: post.id,
      tokenId: token.id,
    }, {
      removeOnComplete: true,
      attempts: 3,
      backoff: {
        type: 'exponential',
        delay: 5000,
      },
    });
  }
}

DRAFT ──(user schedules)──► PENDING
    │                         │
    │                  (Outbox Poller picks up)
    │                         │
    │                      QUEUED
    │                         │
    │               (Worker executes)
    │                         │
    ┌──────────────┬──────────┴────────────┐
    │              │                         │
PUBLISHED    PARTIALLY_PUBLISHED       FAILED
    │              │                         │
    │         (some platforms      (all failed)
    │          published)
    │              │
    ▼              ▼
  ARCHIVED       ARCHIVED

// services/media-validator.service.ts
async function validateMediaUrls(urls: string[]): Promise<ValidationResult> {
  const results = await Promise.all(
    urls.map(async (url) => {
      try {
        const response = await axios.head(url, { timeout: 5000 });
        if (!response.headers['content-type']?.startsWith('image/')) {
          return { url, valid: false, reason: 'Not an image' };
        }
        return { url, valid: true };
      } catch (error) {
        return { url, valid: false, reason: 'Unreachable' };
      }
    })
  );
  
  const allValid = results.every(r => r.valid);
  return { valid: allValid, results };
}

// services/ingestion.service.ts
async function ingestFromCSV(filePath: string): Promise<IngestionResult> {
  const content = fs.readFileSync(filePath, 'utf-8');
  const records = parse(content, { columns: true, skip_empty_lines: true });
  
  const posts = records.map((row, index) => ({
    platform: row.platform?.toUpperCase() || 'FACEBOOK',
    content: row.caption,
    mediaUrls: row.images?.split('|').filter(Boolean) || [],
    scheduledAt: row.scheduled_at ? new Date(row.scheduled_at) : null,
  }));
  
  return this.postService.bulkCreate(posts);
}

enum PostStatus {
  DRAFT = 'DRAFT',
  PENDING = 'PENDING',
  QUEUED = 'QUEUED',
  PUBLISHED = 'PUBLISHED',
  PARTIALLY_PUBLISHED = 'PARTIALLY_PUBLISHED',
  FAILED = 'FAILED',
  VALIDATION_FAILED = 'VALIDATION_FAILED',
  ARCHIVED = 'ARCHIVED',
}

// modules/facebook/facebook-post.service.ts
async function publishToPage(post: Post, token: string): Promise<PublishResult> {
  const endpoint = `/${process.env.FB_PAGE_ID}/photos`;
  
  const formData = new FormData();
  formData.append('message', post.content);
  if (post.mediaUrls?.[0]) {
    formData.append('url', post.mediaUrls[0]);
  }
  
  const response = await axios.post(endpoint, formData, {
    headers: { Authorization: `Bearer ${token}` },
  });
  
  return { platformPostId: response.data.id, platform: 'FACEBOOK' };
}

// modules/instagram/ig-post.service.ts
async function publishToInstagram(post: Post, token: string): Promise<PublishResult> {
  // 1. Upload media to container
  const container = await axios.post(
    `/${process.env.IG_BUSINESS_ID}/media`,
    {
      image_url: post.mediaUrls[0],
      caption: post.content,
    },
    { headers: { Authorization: `Bearer ${token}` } }
  );
  
  // 2. Publish from container
  const publish = await axios.post(
    `/${process.env.IG_BUSINESS_ID}/media_publish`,
    { creation_id: container.data.id },
    { headers: { Authorization: `Bearer ${token}` } }
  );
  
  return { platformPostId: publish.data.id, platform: 'INSTAGRAM' };
}

platform,caption,images,scheduled_at
FACEBOOK,"Launch announcement!","https://example.com/img1.jpg|https://example.com/img2.jpg","2026-05-20T10:00:00Z"
INSTAGRAM,"Behind the scenes","https://example.com/bts.jpg",,

// modules/ingestion/google-sheets.service.ts
async function fetchFromSheet(sheetId: string): Promise<Post[]> {
  const response = await this.googleClient.spreadsheets.values.get({
    spreadsheetId: sheetId,
    range: 'Posts!A:E',
  });
  
  return this.mapRowsToPosts(response.data.values);
}

# Schedule a post
herald post create --platform facebook --content "Hello World" --media "https://..."

# List scheduled posts
herald post list --status pending

# Import from CSV
herald import csv ./posts.csv

# Check queue status
herald queue status

# Install dependencies
npm install

# Setup database
npx prisma migrate deploy
npx prisma db seed

# Start services
docker compose up -d redis postgres
npm run start:api
npm run start:worker

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: herald
      POSTGRES_PASSWORD: password
      POSTGRES_DB: herald_db
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data

# Build for production
npm run build

# Start with PM2
pm2 start ecosystem.config.js
pm2 save

# Access at http://your-vps:3000