# 11 — Social Media Automation

## Context
Fogbreak replaces FUB, ShowingTime, Sisu, Paperless Pipeline, DocuSign, RealScout — and adds auto social posting none of them offer. This instruction builds the posting pipeline: AI generates content (instruction 10), this module distributes it.

## What to Build

### 1. Platform API Integrations
Create `app/api/social.php`:

**Instagram/Facebook (Meta Graph API):**
- OAuth 2.0 authentication per agent/brokerage
- Post images, carousels, videos, Stories
- Schedule posts for optimal engagement times
- Rate limiting: 200 calls/hour
- Business/Creator account required

**LinkedIn (Community Management API):**
- OAuth 2.0 via LinkedIn Partner Program
- Text posts, images, videos, carousels, polls
- Company page and personal profile posting

**TikTok (Content Posting API):**
- Direct Post (immediate) and Upload to Inbox (draft)
- Video and photo support
- User authorization per account

### 2. Content Calendar
```sql
CREATE TABLE content_calendar (
    id SERIAL PRIMARY KEY,
    tenant_id INT NOT NULL,
    agent_id INT,
    title VARCHAR(255),
    content_type VARCHAR(30),
    platforms JSONB DEFAULT '[]',
    scheduled_at TIMESTAMPTZ,
    content JSONB DEFAULT '{}',
    media_urls JSONB DEFAULT '[]',
    status VARCHAR(20) DEFAULT 'draft',
    ai_generated BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMPTZ DEFAULT NOW()
);
```

Visual calendar view:
- Month/week/day views
- Drag-and-drop to reschedule
- Color-coded by platform
- Filter by agent
- Bulk scheduling (post same content across multiple days/platforms)

### 3. Auto-Post Triggers
Automatic content generation and posting on events:
- **New listing**: Generate + post to all platforms within 1 hour
- **Open house**: Post reminder 3 days before and day-of
- **Price reduction**: Post update across platforms
- **Just sold**: Celebration post with sold price
- **Market update**: Weekly/monthly market stats post

### 4. Hashtag Engine
Market-aware hashtag generation:
- Core hashtags per market (loaded from database)
- Property-specific hashtags (luxury, waterfront, fixer-upper)
- Trending real estate hashtags
- Platform-specific limits (Instagram: 30, others: fewer)
- A/B test hashtag sets for engagement

### 5. Media Management
- Upload photos from listing
- Auto-select best photos for each platform
- Resize/crop per platform requirements (IG square, FB landscape, etc.)
- Carousel ordering
- Video thumbnail selection

### 6. Engagement Tracking
```sql
-- Track post performance
ALTER TABLE social_posts ADD COLUMN engagement_data JSONB DEFAULT '{}';
-- {likes: 45, comments: 12, shares: 8, saves: 23, impressions: 1200, reach: 890}
```

Pull engagement data via platform APIs (where available):
- Likes, comments, shares, saves
- Impressions and reach
- Click-through rate
- Best performing content analysis

### 7. Multi-Agent Management
- Each agent connects their own social accounts
- Brokerage admin can post on behalf of agents
- Brand-consistent templates applied to all agent posts
- Compliance review queue (optional: posts require broker approval)

## API Endpoints
```
POST /api/social.php?action=connect_account        # OAuth flow start
POST /api/social.php?action=disconnect_account      # Remove connection
POST /api/social.php?action=post                    # Post immediately
POST /api/social.php?action=schedule                # Schedule post
GET  /api/social.php?action=calendar                # Content calendar
GET  /api/social.php?action=engagement&post_id=X    # Post engagement
POST /api/social.php?action=auto_generate&prop=X    # Auto-generate for listing
GET  /api/social.php?action=accounts                # Connected accounts
```

## Cron Jobs
- `social_post_scheduler`: Check for scheduled posts due, execute them
- `social_engagement_sync`: Pull engagement metrics from platforms
- `social_auto_listing`: On new listing, auto-generate and schedule posts
- `social_auto_events`: Auto-post for upcoming open houses, price drops

## Acceptance Criteria
- [ ] Instagram, Facebook, LinkedIn, TikTok posting via official APIs
- [ ] Visual content calendar with drag-and-drop scheduling
- [ ] Auto-post triggers on listing events (new, price drop, sold, open house)
- [ ] Market-aware hashtag generation
- [ ] Media management with platform-specific formatting
- [ ] Engagement tracking with analytics
- [ ] Multi-agent account management
- [ ] All features tenant-aware and market-aware