Social Publishing

[To Build] · agent__social-publisher · BullMQ delayed job · platform provider APIs

Publishes approved and scheduled social media posts to connected social platforms. When a SocialPost reaches its scheduledAt time, a BullMQ delayed job fires and delivers the post to the appropriate platform via its API. Also supports on-demand “Publish Now” from the dashboard.

Related: Social Post Writer · Channels · Campaigns · Content Toolkit Overview

Overview

Why This Is Needed

Social posts are generated by social-post-writer, reviewed and approved through the HITL workflow, and given a scheduledAt timestamp by the Social Calendar Planner — but they are never actually sent anywhere. This is a documented gap in docs/campaigns/README.md and the most visible operational hole in the product: content that clients and DMs believe is “scheduled” silently sits in the database.

Supported Platforms

v1 scope: Facebook, Instagram, LinkedIn, GBP. X and TikTok are P2 within this feature.

How It Works

SocialPost reaches client_approved status with a scheduledAt timestamp set
  ↓
API creates a BullMQ delayed job: delay = scheduledAt - now()
  queue: agent__social-publisher
  jobId: social-post-{socialPostId}  (deduplication key)
  ↓
At scheduledAt time, BullMQ fires the job
  ↓
social-publisher worker:
  1. Load SocialPost + connected SocialPost.channel (ConnectedChannel)
  2. Decrypt OAuth token from ConnectedChannel.tokenInfo
  3. Refresh token if expiry < 10 min away
  4. Call platform API with post content + media URLs
  5. Store platformPostId + platformPostUrl + publishedAt on SocialPost
  6. Emit WebSocket event: social:published { socialPostId, platform, platformPostUrl }
  ↓
Dashboard Social page updates post status to "Published" with platform link

“Publish Now” flow (bypass schedule):

DM or admin clicks "Publish Now" on an approved SocialPost
  ↓
API: POST /tenant/v1/social/:id/publish
  ↓
Enqueues job with delay = 0 (immediate)
  ↓
Same worker flow as above

Job Payload

interface SocialPublishJob {
  tenantId:          string;
  socialPostId:      string;
  connectedChannelId: string;
  platform:          'facebook' | 'instagram' | 'linkedin' | 'x' | 'tiktok' | 'gbp';
  scheduledAt:       string;   // ISO timestamp — informational, job fires at this time via BullMQ delay
}

Publish Result

interface SocialPublishResult {
  socialPostId:     string;
  platform:         string;
  publishedAt:      string;           // ISO timestamp
  platformPostId:   string;           // native ID from the platform
  platformPostUrl:  string | null;    // public URL — null if platform does not return it
  success:          boolean;
  error?:           string;           // populated on failure
}

DB Changes

Add to the SocialPost model in packages/db/prisma/schema.prisma:

platformPostId    String?
platformPostUrl   String?
publishedAt       DateTime?
publishError      String?       // last error message if publish failed
publishAttempts   Int       @default(0)

Error Handling & Retry Strategy

Platform-Specific Constraints

The social-post-writer agent already respects these character limits. The publisher does not truncate — if a post exceeds the limit it will fail with a 4xx; this indicates a prompt regression to investigate.

Scheduling UI Changes

Dashboard Social page:

• Post status badge: Scheduled → Publishing → Published (with platform link) / Failed (with error tooltip)
• “Publish Now” button visible on all client_approved posts with a schedule
• “Reschedule” button to update scheduledAt (cancels the existing BullMQ job, re-enqueues with new delay)

Dashboard Calendar page:

• Published posts show a tick indicator; failed posts show a warning icon
• Clicking a failed post opens a detail panel with the error and a “Retry” button

New API Routes

Open Questions

Implementation Phases

Phase 1 — Foundation

1. Add platformPostId, platformPostUrl, publishedAt, publishError, publishAttempts to SocialPost (migration)
2. Create agent__social-publisher BullMQ queue in packages/queue/src/types.ts
3. Create apps/api/src/workers/social-publisher.worker.ts — platform dispatcher; routes to per-platform handler
4. Implement Facebook + LinkedIn publishers first (most common platforms in current tenant base)
5. Add POST /tenant/v1/social/:id/publish route (immediate enqueue)

Phase 2 — Scheduled Publishing

6. Hook client_approved status transition in blog/social post approval flow to auto-enqueue delayed BullMQ job
7. Add POST /tenant/v1/social/:id/schedule and cancel-schedule routes
8. Dashboard Social page: status badge updates via WebSocket social:published event

Phase 3 — Remaining Platforms

9. Implement Instagram publisher (two-step media create → publish flow)
10. Implement GBP publisher
11. Implement X publisher (flag as optional/plan-gated until API tier is resolved)

Phase 4 — Monitoring

12. Dashboard: failed publish warning badges + retry button
13. DM portal notification for publish failures
14. Add publish success/failure metrics to the Report Writer data sources