`SOCIAL_POSTING_DOCUMENTATION.md`

202 lines
# Social Media Auto-Posting System Documentation

## Overview
Comprehensive logging system for automated social media posting to Twitter/X and Bluesky, featuring Bubbe's signature sarcastic responses.

## Files Created

### 1. `/root/Projects/dear-bubbe-nextjs/social-autoposter.js`
Main script that handles social media posting with detailed logging.

**Features:**
- Full timestamp logging with millisecond precision
- Parallel posting to Twitter and Bluesky
- Comprehensive error handling and retry logic
- Detailed logging of all post attempts
- Automatic session management for Bluesky
- Post formatting to meet platform character limits

### 2. `/root/Projects/dear-bubbe-nextjs/view-social-logs.sh`
Utility script to view and analyze social post logs.

**Usage:**
```bash
./view-social-logs.sh           # View recent formatted logs
./view-social-logs.sh --tail    # Follow log in real-time
./view-social-logs.sh --last 20 # View last 20 entries
./view-social-logs.sh --success # Show only successful posts
./view-social-logs.sh --failed  # Show only failed posts
./view-social-logs.sh --summary # Show statistics
```

### 3. `/root/Projects/dear-bubbe-nextjs/logs/social-posts-detailed.log`
JSON-formatted log file containing all social posting activity.

## Log Entry Format

Each log entry contains:
```json
{
  "timestamp": "2025-11-19 20:50:32.018",
  "level": "INFO|ERROR|WARN",
  "message": "Description of event",
  "platform": "twitter|bluesky",
  "userMessageSnippet": "First 50 chars of user message...",
  "bubbeResponseSnippet": "First 100 chars of Bubbe response...",
  "fullUserMessage": "Complete user message",
  "fullBubbeResponse": "Complete Bubbe response",
  "status": "success|failed",
  "postLength": 280,
  "postId": "1234567890",
  "url": "https://twitter.com/i/web/status/1234567890",
  "error": "Error message if failed",
  "responseTime": "1234ms"
}
```

## Configuration

Add credentials to `/root/Projects/dear-bubbe-nextjs/.env.local`:

```bash
# Twitter/X API v2 - Get from developer.twitter.com
TWITTER_BEARER_TOKEN=your_twitter_bearer_token_here

# Bluesky - Your Bluesky account credentials
BLUESKY_IDENTIFIER=your.handle@bsky.social
BLUESKY_PASSWORD=your_bluesky_app_password_here
```

## Usage Examples

### Run a Test Post
```bash
node social-autoposter.js --test
```

### Post a Specific Message
```bash
node social-autoposter.js "What's the weather like today?"
```

### View Log Summary
```bash
./view-social-logs.sh --summary
```

Output:
```
📊 Summary Statistics
-------------------
Total log entries: 14
Overall:
  ✅ Successful posts: 0
  ❌ Failed posts: 2
Twitter/X:
  ✅ Successful: 0
  ❌ Failed: 1
Bluesky:
  ✅ Successful: 0
  ❌ Failed: 1
```

## Tracked Information

### Per Post Attempt:
- **Exact timestamp** with date, time, and milliseconds
- **Platform** (Twitter or Bluesky)
- **User message** (full text and snippet)
- **Bubbe response** (full text and snippet)
- **Success/failure status**
- **Post ID** if successful
- **Post URL** if successful
- **Error message** if failed
- **Response time** in milliseconds

### Session Information:
- Session start/end timestamps
- Total session duration
- Success status for each platform
- Generated URLs for successful posts

## Example Log Output

### Successful Post (when credentials are configured):
```json
{
  "timestamp": "2025-11-19 20:50:33.529",
  "level": "INFO",
  "message": "Successfully posted to Twitter",
  "postId": "1234567890",
  "responseTime": "523ms",
  "url": "https://twitter.com/i/web/status/1234567890"
}
```

### Failed Post:
```json
{
  "timestamp": "2025-11-19 20:50:33.529",
  "level": "ERROR",
  "message": "Social post attempt to twitter",
  "platform": "twitter",
  "userMessageSnippet": "What's the weather like today?",
  "bubbeResponseSnippet": "Vey, what do I care about the weather...",
  "status": "failed",
  "error": "Twitter Bearer Token not configured"
}
```

## Monitoring

### Real-time Monitoring
```bash
# Follow logs in real-time
./view-social-logs.sh --tail

# Check service status
pm2 status bubbe

# View recent activity
tail -f logs/social-posts-detailed.log | jq '.'
```

### Automated Posting (Cron)
To schedule automated posts, add to crontab:
```bash
# Post every 6 hours with a random prompt
0 */6 * * * cd /root/Projects/dear-bubbe-nextjs && node social-autoposter.js --test >> logs/cron.log 2>&1
```

## Error Handling

The system handles:
- Missing credentials
- API authentication failures
- Network timeouts
- Rate limiting
- Session expiration (auto-refresh for Bluesky)
- Character limit enforcement
- Invalid responses

## Testing

Test runs were performed with sample messages:
1. "What's the weather like today?" - Logged successfully
2. "Should I invest in stocks?" - Logged successfully

Both tests confirmed:
- ✅ Timestamps are recorded accurately
- ✅ Full message content is logged
- ✅ Platform-specific details are tracked
- ✅ Error messages are captured
- ✅ Response times are measured
- ✅ Log file is created and formatted correctly

## Notes

- Logs are stored in JSON format for easy parsing
- Each platform is posted to in parallel for efficiency
- Bluesky sessions auto-refresh when expired
- Posts are truncated to meet platform limits (280 chars for Twitter, 300 for Bluesky)
- The system maintains Bubbe's personality in all responses