@nextsparkjs/plugin-social-media-publisher 0.1.0-beta.1

package/docs/03-advanced-usage/02-custom-integrations.md

@@ -0,0 +1,695 @@
+# Custom Integrations
+
+## Overview
+
+The Social Media Publisher plugin provides flexible building blocks that allow you to create custom publishing workflows, scheduled posts, analytics dashboards, and content management integrations. This guide shows you how to extend the plugin's capabilities.
+
+**What You Can Build:**
+- Batch publishing systems
+- Scheduled post queues
+- Cross-posting automation
+- Analytics dashboards
+- Content approval workflows
+- Custom publishing endpoints
+
+## Building Custom Endpoints
+
+### Custom Publishing Endpoint
+
+Create a custom endpoint with additional business logic:
+
+```typescript
+// app/api/v1/custom/publish-with-approval/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+import { authenticateRequest } from '@/core/lib/api/auth/dual-auth'
+import { InstagramAPI, FacebookAPI } from '@/contents/plugins/social-media-publisher/lib/providers'
+import { TokenEncryption } from '@/core/lib/oauth/encryption'
+import { query } from '@/core/lib/db'
+
+export async function POST(request: NextRequest) {
+  const authResult = await authenticateRequest(request)
+  if (!authResult.success) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const { accountId, imageUrl, caption, requireApproval } = await request.json()
+
+  // Custom business logic: Check if approval needed
+  if (requireApproval) {
+    // Save to pending queue
+    await query(`
+      INSERT INTO "pending_posts" (
+        "accountId", "imageUrl", caption, "createdBy", status
+      ) VALUES ($1, $2, $3, $4, 'pending_approval')
+    `, [accountId, imageUrl, caption, authResult.user!.id])
+
+    return NextResponse.json({
+      success: true,
+      status: 'pending_approval',
+      message: 'Post submitted for approval'
+    })
+  }
+
+  // Direct publish (no approval needed)
+  const account = await getAccount(accountId)
+  const token = await decryptToken(account.accessToken)
+
+  const result = account.platform === 'instagram_business'
+    ? await InstagramAPI.publishPhoto({
+        igAccountId: account.platformAccountId,
+        accessToken: token,
+        imageUrl,
+        caption
+      })
+    : await FacebookAPI.publishPhotoPost({
+        pageId: account.platformAccountId,
+        pageAccessToken: token,
+        message: caption,
+        imageUrl
+      })
+
+  return NextResponse.json(result)
+}
+```
+
+### Approval System Endpoint
+
+Approve and publish pending posts:
+
+```typescript
+// app/api/v1/custom/approve-post/[postId]/route.ts
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ postId: string }> }
+) {
+  const { postId } = await params
+  const authResult = await authenticateRequest(request)
+
+  // Check if user has approval permission
+  if (!hasApprovalPermission(authResult.user!.id)) {
+    return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
+  }
+
+  // Get pending post
+  const post = await query(`
+    SELECT * FROM "pending_posts"
+    WHERE id = $1 AND status = 'pending_approval'
+  `, [postId])
+
+  if (post.rowCount === 0) {
+    return NextResponse.json({ error: 'Post not found' }, { status: 404 })
+  }
+
+  const postData = post.rows[0]
+
+  // Publish the post
+  const account = await getAccount(postData.accountId)
+  const token = await decryptToken(account.accessToken)
+
+  const result = await publishToAccount(account, token, {
+    imageUrl: postData.imageUrl,
+    caption: postData.caption
+  })
+
+  if (result.success) {
+    // Update status
+    await query(`
+      UPDATE "pending_posts"
+      SET status = 'published',
+          "publishedAt" = NOW(),
+          "approvedBy" = $1,
+          "postId" = $2
+      WHERE id = $3
+    `, [authResult.user!.id, result.postId, postId])
+  }
+
+  return NextResponse.json(result)
+}
+```
+
+## Scheduled Publishing
+
+### Database Schema for Scheduled Posts
+
+```sql
+CREATE TABLE "scheduled_posts" (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  "accountId" UUID NOT NULL REFERENCES "clients_social_platforms"(id),
+  "scheduledFor" TIMESTAMPTZ NOT NULL,
+  "imageUrl" TEXT NOT NULL,
+  caption TEXT,
+  status TEXT DEFAULT 'scheduled', -- 'scheduled', 'publishing', 'published', 'failed'
+  "postId" TEXT,
+  "postUrl" TEXT,
+  "createdBy" TEXT NOT NULL,
+  "createdAt" TIMESTAMPTZ DEFAULT now(),
+  "publishedAt" TIMESTAMPTZ,
+  error TEXT
+);
+
+CREATE INDEX "idx_scheduled_posts_scheduledFor" 
+  ON "scheduled_posts"("scheduledFor") 
+  WHERE status = 'scheduled';
+```
+
+### Schedule Endpoint
+
+```typescript
+// app/api/v1/custom/schedule-post/route.ts
+export async function POST(request: NextRequest) {
+  const authResult = await authenticateRequest(request)
+  if (!authResult.success) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const { accountId, imageUrl, caption, scheduledFor } = await request.json()
+
+  // Validate scheduled time is in future
+  const scheduledDate = new Date(scheduledFor)
+  if (scheduledDate <= new Date()) {
+    return NextResponse.json(
+      { error: 'Scheduled time must be in the future' },
+      { status: 400 }
+    )
+  }
+
+  // Save scheduled post
+  const result = await query(`
+    INSERT INTO "scheduled_posts" (
+      "accountId", "scheduledFor", "imageUrl", caption, "createdBy"
+    ) VALUES ($1, $2, $3, $4, $5)
+    RETURNING id
+  `, [accountId, scheduledDate, imageUrl, caption, authResult.user!.id])
+
+  return NextResponse.json({
+    success: true,
+    scheduledPostId: result.rows[0].id,
+    scheduledFor: scheduledDate.toISOString()
+  })
+}
+```
+
+### Cron Job to Process Scheduled Posts
+
+```typescript
+// app/api/cron/process-scheduled-posts/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+import { query } from '@/core/lib/db'
+import { publishScheduledPost } from '@/lib/scheduled-posts'
+
+export async function GET(request: NextRequest) {
+  // Verify cron secret (Vercel Cron)
+  const authHeader = request.headers.get('authorization')
+  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  // Get posts ready to publish (within next 5 minutes)
+  const posts = await query(`
+    SELECT * FROM "scheduled_posts"
+    WHERE status = 'scheduled'
+    AND "scheduledFor" <= NOW() + INTERVAL '5 minutes'
+    ORDER BY "scheduledFor" ASC
+    LIMIT 10
+  `)
+
+  const results = []
+
+  for (const post of posts.rows) {
+    // Mark as publishing
+    await query(`
+      UPDATE "scheduled_posts"
+      SET status = 'publishing'
+      WHERE id = $1
+    `, [post.id])
+
+    try {
+      // Publish
+      const result = await publishScheduledPost(post)
+
+      if (result.success) {
+        // Mark as published
+        await query(`
+          UPDATE "scheduled_posts"
+          SET status = 'published',
+              "publishedAt" = NOW(),
+              "postId" = $1,
+              "postUrl" = $2
+          WHERE id = $3
+        `, [result.postId, result.postUrl, post.id])
+
+        results.push({ id: post.id, success: true })
+      } else {
+        // Mark as failed
+        await query(`
+          UPDATE "scheduled_posts"
+          SET status = 'failed',
+              error = $1
+          WHERE id = $2
+        `, [result.error, post.id])
+
+        results.push({ id: post.id, success: false, error: result.error })
+      }
+    } catch (error) {
+      // Mark as failed
+      await query(`
+        UPDATE "scheduled_posts"
+        SET status = 'failed',
+            error = $1
+        WHERE id = $2
+      `, [error instanceof Error ? error.message : 'Unknown error', post.id])
+
+      results.push({ id: post.id, success: false, error: String(error) })
+    }
+  }
+
+  return NextResponse.json({
+    success: true,
+    processed: results.length,
+    results
+  })
+}
+
+// Helper function
+async function publishScheduledPost(post: any) {
+  const account = await getAccount(post.accountId)
+  const token = await decryptToken(account.accessToken)
+
+  if (account.platform === 'instagram_business') {
+    return await InstagramAPI.publishPhoto({
+      igAccountId: account.platformAccountId,
+      accessToken: token,
+      imageUrl: post.imageUrl,
+      caption: post.caption
+    })
+  } else {
+    return await FacebookAPI.publishPhotoPost({
+      pageId: account.platformAccountId,
+      pageAccessToken: token,
+      message: post.caption,
+      imageUrl: post.imageUrl
+    })
+  }
+}
+```
+
+### Vercel Cron Configuration
+
+```json
+// vercel.json
+{
+  "crons": [
+    {
+      "path": "/api/cron/process-scheduled-posts",
+      "schedule": "*/5 * * * *"
+    }
+  ]
+}
+```
+
+## Cross-Posting Automation
+
+### Publish to Multiple Accounts at Once
+
+```typescript
+// app/api/v1/custom/cross-post/route.ts
+export async function POST(request: NextRequest) {
+  const authResult = await authenticateRequest(request)
+  if (!authResult.success) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const { accountIds, imageUrl, caption } = await request.json()
+
+  // Validate user has access to all accounts
+  const accounts = await query(`
+    SELECT csp.*
+    FROM "clients_social_platforms" csp
+    JOIN "clients" c ON c.id = csp."parentId"
+    WHERE csp.id = ANY($1)
+    AND c."userId" = $2
+    AND csp."isActive" = true
+  `, [accountIds, authResult.user!.id])
+
+  if (accounts.rowCount !== accountIds.length) {
+    return NextResponse.json(
+      { error: 'Access denied to one or more accounts' },
+      { status: 403 }
+    )
+  }
+
+  // Publish to all accounts
+  const results = await Promise.allSettled(
+    accounts.rows.map(async (account) => {
+      const token = await decryptToken(account.accessToken)
+
+      if (account.platform === 'instagram_business') {
+        return await InstagramAPI.publishPhoto({
+          igAccountId: account.platformAccountId,
+          accessToken: token,
+          imageUrl,
+          caption
+        })
+      } else {
+        return await FacebookAPI.publishPhotoPost({
+          pageId: account.platformAccountId,
+          pageAccessToken: token,
+          message: caption,
+          imageUrl
+        })
+      }
+    })
+  )
+
+  const successful = results.filter(r => 
+    r.status === 'fulfilled' && r.value.success
+  )
+  const failed = results.filter(r => 
+    r.status === 'rejected' || (r.status === 'fulfilled' && !r.value.success)
+  )
+
+  return NextResponse.json({
+    success: successful.length > 0,
+    total: accountIds.length,
+    successful: successful.length,
+    failed: failed.length,
+    results: results.map((r, i) => ({
+      accountId: accountIds[i],
+      accountName: accounts.rows[i].platformAccountName,
+      status: r.status === 'fulfilled' && r.value.success ? 'published' : 'failed',
+      postUrl: r.status === 'fulfilled' ? r.value.postUrl : null,
+      error: r.status === 'rejected' 
+        ? r.reason 
+        : (r.status === 'fulfilled' && !r.value.success ? r.value.error : null)
+    }))
+  })
+}
+```
+
+## Analytics Dashboard Integration
+
+### Aggregate Analytics Endpoint
+
+```typescript
+// app/api/v1/custom/analytics/summary/route.ts
+export async function GET(request: NextRequest) {
+  const authResult = await authenticateRequest(request)
+  if (!authResult.success) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const { searchParams } = new URL(request.url)
+  const clientId = searchParams.get('clientId')
+
+  // Get all active accounts for client
+  const accounts = await query(`
+    SELECT csp.*
+    FROM "clients_social_platforms" csp
+    JOIN "clients" c ON c.id = csp."parentId"
+    WHERE csp."parentId" = $1
+    AND c."userId" = $2
+    AND csp."isActive" = true
+  `, [clientId, authResult.user!.id])
+
+  const analytics = await Promise.all(
+    accounts.rows.map(async (account) => {
+      const token = await decryptToken(account.accessToken)
+
+      try {
+        if (account.platform === 'instagram_business') {
+          const insights = await InstagramAPI.getAccountInsights(
+            account.platformAccountId,
+            token
+          )
+          
+          return {
+            accountId: account.id,
+            accountName: account.platformAccountName,
+            platform: account.platform,
+            ...insights
+          }
+        } else {
+          const insights = await FacebookAPI.getPageInsights(
+            account.platformAccountId,
+            token
+          )
+          
+          return {
+            accountId: account.id,
+            accountName: account.platformAccountName,
+            platform: account.platform,
+            ...insights
+          }
+        }
+      } catch (error) {
+        return {
+          accountId: account.id,
+          accountName: account.platformAccountName,
+          platform: account.platform,
+          error: error instanceof Error ? error.message : 'Failed to fetch insights'
+        }
+      }
+    })
+  )
+
+  // Calculate totals
+  const totals = analytics.reduce((acc, curr) => {
+    if (!curr.error) {
+      acc.impressions += curr.impressions || 0
+      acc.reach += curr.reach || 0
+      acc.engagement += curr.engagement || 0
+    }
+    return acc
+  }, { impressions: 0, reach: 0, engagement: 0 })
+
+  return NextResponse.json({
+    success: true,
+    totals,
+    accounts: analytics
+  })
+}
+```
+
+### Publish History Dashboard
+
+```typescript
+// app/api/v1/custom/analytics/publish-history/route.ts
+export async function GET(request: NextRequest) {
+  const authResult = await authenticateRequest(request)
+  if (!authResult.success) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const { searchParams } = new URL(request.url)
+  const days = parseInt(searchParams.get('days') || '30')
+
+  // Get publish history from audit logs
+  const history = await query(`
+    SELECT 
+      DATE(al."createdAt") as date,
+      al.details->>'platform' as platform,
+      COUNT(*) FILTER (WHERE al.action = 'post_published') as successful,
+      COUNT(*) FILTER (WHERE al.action = 'post_failed') as failed,
+      array_agg(DISTINCT al."accountId") as account_ids
+    FROM "audit_logs" al
+    WHERE al."userId" = $1
+    AND al.action IN ('post_published', 'post_failed')
+    AND al."createdAt" > NOW() - INTERVAL '${days} days'
+    GROUP BY DATE(al."createdAt"), al.details->>'platform'
+    ORDER BY date DESC
+  `, [authResult.user!.id])
+
+  return NextResponse.json({
+    success: true,
+    period: `${days} days`,
+    history: history.rows
+  })
+}
+```
+
+## Content Management Integration
+
+### Save Post as Template
+
+```typescript
+// app/api/v1/custom/templates/save/route.ts
+export async function POST(request: NextRequest) {
+  const authResult = await authenticateRequest(request)
+  if (!authResult.success) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const { name, caption, imageUrl, tags } = await request.json()
+
+  const result = await query(`
+    INSERT INTO "post_templates" (
+      name, caption, "imageUrl", tags, "createdBy"
+    ) VALUES ($1, $2, $3, $4, $5)
+    RETURNING id
+  `, [name, caption, imageUrl, tags, authResult.user!.id])
+
+  return NextResponse.json({
+    success: true,
+    templateId: result.rows[0].id
+  })
+}
+```
+
+### Use Template to Publish
+
+```typescript
+// app/api/v1/custom/templates/publish/[templateId]/route.ts
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ templateId: string }> }
+) {
+  const { templateId } = await params
+  const authResult = await authenticateRequest(request)
+  const { accountId, customCaption } = await request.json()
+
+  // Get template
+  const template = await query(`
+    SELECT * FROM "post_templates"
+    WHERE id = $1
+  `, [templateId])
+
+  if (template.rowCount === 0) {
+    return NextResponse.json({ error: 'Template not found' }, { status: 404 })
+  }
+
+  const { imageUrl, caption } = template.rows[0]
+  const finalCaption = customCaption || caption
+
+  // Publish using template
+  const account = await getAccount(accountId)
+  const token = await decryptToken(account.accessToken)
+
+  const result = await publishToAccount(account, token, {
+    imageUrl,
+    caption: finalCaption
+  })
+
+  return NextResponse.json(result)
+}
+```
+
+## Webhook Integration
+
+### Receive Notifications from Meta
+
+```typescript
+// app/api/webhooks/meta/route.ts
+export async function POST(request: NextRequest) {
+  const signature = request.headers.get('x-hub-signature-256')
+  const body = await request.text()
+
+  // Verify signature
+  if (!verifyWebhookSignature(signature, body)) {
+    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 })
+  }
+
+  const event = JSON.parse(body)
+
+  // Handle different event types
+  for (const entry of event.entry) {
+    for (const change of entry.changes) {
+      if (change.field === 'feed') {
+        // Post published or updated
+        await handleFeedChange(change.value)
+      } else if (change.field === 'comments') {
+        // New comment
+        await handleNewComment(change.value)
+      }
+    }
+  }
+
+  return NextResponse.json({ success: true })
+}
+
+// Verification endpoint (GET)
+export async function GET(request: NextRequest) {
+  const { searchParams } = new URL(request.url)
+  const mode = searchParams.get('hub.mode')
+  const token = searchParams.get('hub.verify_token')
+  const challenge = searchParams.get('hub.challenge')
+
+  if (mode === 'subscribe' && token === process.env.WEBHOOK_VERIFY_TOKEN) {
+    return new NextResponse(challenge, { status: 200 })
+  }
+
+  return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
+}
+```
+
+## Best Practices
+
+### Do's ✅
+
+**1. Validate Permissions:**
+```typescript
+// Always check user has access to resources
+const hasAccess = await checkUserAccessToAccount(userId, accountId)
+if (!hasAccess) throw new Error('Access denied')
+```
+
+**2. Handle Failures Gracefully:**
+```typescript
+// Don't fail entire batch if one post fails
+const results = await Promise.allSettled(publishOperations)
+```
+
+**3. Rate Limit Custom Endpoints:**
+```typescript
+// Implement rate limiting
+const rateLimit = rateLimit({
+  interval: 60 * 1000, // 1 minute
+  uniqueTokenPerInterval: 500,
+})
+
+await rateLimit.check(request, 10, userId) // 10 requests per minute
+```
+
+**4. Audit Custom Actions:**
+```typescript
+// Log custom operations
+await logAudit('custom_bulk_publish', {
+  accountCount: accountIds.length,
+  successful: results.successful,
+  failed: results.failed
+})
+```
+
+### Don'ts ❌
+
+**1. Don't Skip Token Validation:**
+```typescript
+// ❌ Bad
+const token = await decryptToken(account.accessToken)
+await publishDirectly(token)
+
+// ✅ Good
+if (isTokenExpired(account.tokenExpiresAt)) {
+  await refreshToken(account.id)
+}
+const token = await decryptToken(account.accessToken)
+```
+
+**2. Don't Expose Internal Errors:**
+```typescript
+// ❌ Bad
+catch (error) {
+  return NextResponse.json({ error: error.stack })
+}
+
+// ✅ Good
+catch (error) {
+  console.error('Internal error:', error)
+  return NextResponse.json({ error: 'Publishing failed' })
+}
+```
+
+## Next Steps
+
+- **[Provider APIs](./01-provider-apis.md)** - API wrappers reference
+- **[Per-Client Architecture](./03-per-client-architecture.md)** - Understand data model
+- **[Agency Management](../04-use-cases/01-agency-management.md)** - Real-world examples