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

package/docs/04-use-cases/03-analytics-reporting.md

@@ -0,0 +1,748 @@
+# Analytics and Reporting
+
+## Overview
+
+This guide covers how to leverage the Social Media Publisher plugin's analytics capabilities to track performance, generate reports, and make data-driven decisions for social media management.
+
+**Covered Topics:**
+- Account-level analytics
+- Post performance tracking
+- Client reporting
+- Comparative analysis
+- Export and visualization
+- ROI measurement
+
+## Account-Level Analytics
+
+### Instagram Business Insights
+
+**Fetch Account Metrics:**
+```typescript
+import { InstagramAPI } from '@/contents/plugins/social-media-publisher/lib/providers/instagram'
+import { TokenEncryption } from '@/core/lib/oauth/encryption'
+
+export async function getInstagramAnalytics(accountId: string) {
+  // Get account with encrypted token
+  const account = await query(`
+    SELECT * FROM "clients_social_platforms"
+    WHERE id = $1
+  `, [accountId])
+
+  if (account.rowCount === 0) throw new Error('Account not found')
+
+  // Decrypt token
+  const [encrypted, iv, keyId] = account.rows[0].accessToken.split(':')
+  const decryptedToken = await TokenEncryption.decrypt(encrypted, iv, keyId)
+
+  // Fetch insights from Instagram API
+  const insights = await InstagramAPI.getAccountInsights(
+    account.rows[0].platformAccountId,
+    decryptedToken
+  )
+
+  // Fetch account info
+  const info = await InstagramAPI.getAccountInfo(
+    account.rows[0].platformAccountId,
+    decryptedToken
+  )
+
+  return {
+    account: {
+      id: account.rows[0].id,
+      username: account.rows[0].platformAccountName,
+      followersCount: info.followersCount,
+      followsCount: info.followsCount,
+      mediaCount: info.mediaCount,
+      profilePictureUrl: info.profilePictureUrl
+    },
+    insights: {
+      impressions: insights.impressions,
+      reach: insights.reach,
+      engagement: insights.engagement,
+      likes: insights.likes,
+      comments: insights.comments,
+      saves: insights.saves,
+      profileViews: insights.profileViews
+    },
+    metrics: {
+      engagementRate: ((insights.engagement / insights.reach) * 100).toFixed(2),
+      averageEngagementPerPost: (insights.engagement / info.mediaCount).toFixed(0),
+      savesRate: ((insights.saves / insights.reach) * 100).toFixed(2)
+    }
+  }
+}
+```
+
+**Display in Dashboard:**
+```typescript
+// app/dashboard/analytics/[accountId]/page.tsx
+export default async function AccountAnalyticsPage({
+  params
+}: {
+  params: Promise<{ accountId: string }>
+}) {
+  const { accountId } = await params
+  const analytics = await getInstagramAnalytics(accountId)
+
+  return (
+    <div className="max-w-6xl mx-auto p-6">
+      {/* Header */}
+      <div className="flex items-center gap-4 mb-8">
+        <img
+          src={analytics.account.profilePictureUrl}
+          alt={analytics.account.username}
+          className="w-20 h-20 rounded-full"
+        />
+        <div>
+          <h1 className="text-2xl font-bold">@{analytics.account.username}</h1>
+          <p className="text-gray-600">
+            {analytics.account.followersCount.toLocaleString()} followers
+          </p>
+        </div>
+      </div>
+
+      {/* Metrics Grid */}
+      <div className="grid grid-cols-4 gap-4 mb-8">
+        <MetricCard
+          title="Total Impressions"
+          value={analytics.insights.impressions.toLocaleString()}
+          icon="👁️"
+        />
+        <MetricCard
+          title="Reach"
+          value={analytics.insights.reach.toLocaleString()}
+          icon="📊"
+        />
+        <MetricCard
+          title="Engagement"
+          value={analytics.insights.engagement.toLocaleString()}
+          icon="❤️"
+        />
+        <MetricCard
+          title="Engagement Rate"
+          value={`${analytics.metrics.engagementRate}%`}
+          icon="📈"
+        />
+      </div>
+
+      {/* Detailed Metrics */}
+      <div className="grid grid-cols-2 gap-6">
+        <Card>
+          <CardHeader>Engagement Breakdown</CardHeader>
+          <CardContent>
+            <div className="space-y-3">
+              <MetricRow label="Likes" value={analytics.insights.likes} />
+              <MetricRow label="Comments" value={analytics.insights.comments} />
+              <MetricRow label="Saves" value={analytics.insights.saves} />
+              <MetricRow label="Profile Views" value={analytics.insights.profileViews} />
+            </div>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>Performance Metrics</CardHeader>
+          <CardContent>
+            <div className="space-y-3">
+              <MetricRow 
+                label="Engagement Rate" 
+                value={`${analytics.metrics.engagementRate}%`} 
+              />
+              <MetricRow 
+                label="Avg. Engagement/Post" 
+                value={analytics.metrics.averageEngagementPerPost} 
+              />
+              <MetricRow 
+                label="Saves Rate" 
+                value={`${analytics.metrics.savesRate}%`} 
+              />
+              <MetricRow 
+                label="Total Posts" 
+                value={analytics.account.mediaCount} 
+              />
+            </div>
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  )
+}
+
+function MetricCard({ title, value, icon }: {
+  title: string
+  value: string
+  icon: string
+}) {
+  return (
+    <div className="border rounded-lg p-4">
+      <div className="text-2xl mb-2">{icon}</div>
+      <p className="text-sm text-gray-600">{title}</p>
+      <p className="text-2xl font-bold">{value}</p>
+    </div>
+  )
+}
+
+function MetricRow({ label, value }: { label: string; value: number | string }) {
+  return (
+    <div className="flex justify-between items-center">
+      <span className="text-gray-600">{label}</span>
+      <span className="font-semibold">{value}</span>
+    </div>
+  )
+}
+```
+
+### Facebook Page Insights
+
+**Similar to Instagram but with Page-specific metrics:**
+```typescript
+export async function getFacebookPageAnalytics(accountId: string) {
+  // Similar structure to Instagram
+  const account = await getAccount(accountId)
+  const decryptedToken = await decryptToken(account.accessToken)
+
+  const insights = await FacebookAPI.getPageInsights(
+    account.platformAccountId,
+    decryptedToken
+  )
+
+  const pageInfo = await FacebookAPI.getPageInfo(
+    account.platformAccountId,
+    decryptedToken
+  )
+
+  return {
+    account: {
+      id: account.id,
+      name: account.platformAccountName,
+      fanCount: pageInfo.fanCount,
+      about: pageInfo.about,
+      link: pageInfo.link
+    },
+    insights: {
+      impressions: insights.impressions,
+      reach: insights.reach,
+      engagement: insights.engagement,
+      reactions: insights.reactions,
+      comments: insights.comments,
+      shares: insights.shares
+    }
+  }
+}
+```
+
+## Post Performance Tracking
+
+### Individual Post Analytics
+
+**Track Post Performance from Audit Logs:**
+```typescript
+export async function getPostPerformance(clientId: string, days: number = 30) {
+  // Get all published posts from audit logs
+  const posts = await query(`
+    SELECT 
+      al.id,
+      al."createdAt" as "publishedAt",
+      al.details->>'postId' as "postId",
+      al.details->>'postUrl' as "postUrl",
+      al.details->>'platform' as platform,
+      al.details->>'accountName' as "accountName",
+      al.details->>'caption' as caption,
+      al.details->>'imageUrl' as "imageUrl",
+      al."accountId"
+    FROM "audit_logs" al
+    JOIN "clients_social_platforms" csp ON csp.id = al."accountId"
+    WHERE csp."parentId" = $1
+    AND al.action = 'post_published'
+    AND al."createdAt" > NOW() - INTERVAL '${days} days'
+    ORDER BY al."createdAt" DESC
+  `, [clientId])
+
+  // Enrich with real-time insights from APIs
+  const enrichedPosts = await Promise.all(
+    posts.rows.map(async (post) => {
+      try {
+        const account = await getAccount(post.accountId)
+        const token = await decryptToken(account.accessToken)
+
+        let insights = {}
+        
+        if (post.platform === 'instagram_business') {
+          insights = await InstagramAPI.getMediaInsights(post.postId, token)
+        } else {
+          // Facebook post insights
+          // Note: Requires additional API implementation
+        }
+
+        return {
+          ...post,
+          insights
+        }
+      } catch (error) {
+        return {
+          ...post,
+          insights: null,
+          error: 'Failed to fetch insights'
+        }
+      }
+    })
+  )
+
+  return enrichedPosts
+}
+```
+
+**Display Top Performing Posts:**
+```typescript
+// app/dashboard/analytics/top-posts/page.tsx
+export default async function TopPostsPage({
+  searchParams
+}: {
+  searchParams: Promise<{ clientId?: string; days?: string }>
+}) {
+  const params = await searchParams
+  const clientId = params.clientId
+  const days = parseInt(params.days || '30')
+
+  const posts = await getPostPerformance(clientId, days)
+
+  // Sort by engagement
+  const sortedPosts = posts
+    .filter(p => p.insights)
+    .sort((a, b) => (b.insights.engagement || 0) - (a.insights.engagement || 0))
+
+  return (
+    <div className="max-w-6xl mx-auto p-6">
+      <h1 className="text-2xl font-bold mb-6">
+        Top Performing Posts ({days} days)
+      </h1>
+
+      <div className="grid grid-cols-1 gap-4">
+        {sortedPosts.slice(0, 10).map((post, index) => (
+          <div key={post.id} className="border rounded-lg p-4 flex gap-4">
+            {/* Rank */}
+            <div className="text-3xl font-bold text-gray-300 w-12">
+              #{index + 1}
+            </div>
+
+            {/* Image */}
+            <img
+              src={post.imageUrl}
+              alt=""
+              className="w-32 h-32 object-cover rounded"
+            />
+
+            {/* Content */}
+            <div className="flex-1">
+              <div className="flex justify-between items-start">
+                <div>
+                  <p className="font-medium">{post.accountName}</p>
+                  <p className="text-sm text-gray-600">
+                    {new Date(post.publishedAt).toLocaleDateString()}
+                  </p>
+                </div>
+                <a
+                  href={post.postUrl}
+                  target="_blank"
+                  className="text-blue-600 text-sm"
+                >
+                  View Post →
+                </a>
+              </div>
+              
+              <p className="text-sm mt-2 line-clamp-2">{post.caption}</p>
+
+              {/* Metrics */}
+              <div className="flex gap-6 mt-3">
+                <Metric 
+                  label="Impressions" 
+                  value={post.insights.impressions} 
+                />
+                <Metric 
+                  label="Engagement" 
+                  value={post.insights.engagement} 
+                />
+                <Metric 
+                  label="Likes" 
+                  value={post.insights.likes} 
+                />
+                <Metric 
+                  label="Comments" 
+                  value={post.insights.comments} 
+                />
+                <Metric 
+                  label="Saves" 
+                  value={post.insights.saves} 
+                />
+              </div>
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+function Metric({ label, value }: { label: string; value: number }) {
+  return (
+    <div>
+      <p className="text-xs text-gray-600">{label}</p>
+      <p className="font-semibold">{value?.toLocaleString() || '0'}</p>
+    </div>
+  )
+}
+```
+
+## Client Reporting
+
+### Monthly Report Generation
+
+**Comprehensive Client Report:**
+```typescript
+export async function generateMonthlyReport(
+  clientId: string,
+  year: number,
+  month: number
+) {
+  // Date range
+  const startDate = new Date(year, month - 1, 1)
+  const endDate = new Date(year, month, 0)
+
+  // Get client info
+  const client = await query(`
+    SELECT * FROM "clients" WHERE id = $1
+  `, [clientId])
+
+  // Get all accounts
+  const accounts = await query(`
+    SELECT * FROM "clients_social_platforms"
+    WHERE "parentId" = $1 AND "isActive" = true
+  `, [clientId])
+
+  // Get publishing activity
+  const publishingStats = await query(`
+    SELECT 
+      al.details->>'platform' as platform,
+      COUNT(*) FILTER (WHERE al.action = 'post_published') as successful,
+      COUNT(*) FILTER (WHERE al.action = 'post_failed') as failed
+    FROM "audit_logs" al
+    WHERE al."accountId" = ANY($1)
+    AND al."createdAt" BETWEEN $2 AND $3
+    GROUP BY al.details->>'platform'
+  `, [accounts.rows.map(a => a.id), startDate, endDate])
+
+  // Fetch insights for each account
+  const accountInsights = 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
+          )
+          const info = await InstagramAPI.getAccountInfo(
+            account.platformAccountId,
+            token
+          )
+
+          return {
+            accountName: account.platformAccountName,
+            platform: account.platform,
+            followersCount: info.followersCount,
+            ...insights
+          }
+        } else {
+          const insights = await FacebookAPI.getPageInsights(
+            account.platformAccountId,
+            token
+          )
+          const info = await FacebookAPI.getPageInfo(
+            account.platformAccountId,
+            token
+          )
+
+          return {
+            accountName: account.platformAccountName,
+            platform: account.platform,
+            fanCount: info.fanCount,
+            ...insights
+          }
+        }
+      } catch (error) {
+        return {
+          accountName: account.platformAccountName,
+          platform: account.platform,
+          error: 'Failed to fetch insights'
+        }
+      }
+    })
+  )
+
+  // Calculate totals
+  const totals = accountInsights.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 }
+  )
+
+  const totalPosts = publishingStats.rows.reduce(
+    (sum, row) => sum + row.successful,
+    0
+  )
+
+  return {
+    client: client.rows[0],
+    period: {
+      month,
+      year,
+      startDate,
+      endDate
+    },
+    summary: {
+      totalPosts,
+      totalAccounts: accounts.rowCount,
+      totalImpressions: totals.impressions,
+      totalReach: totals.reach,
+      totalEngagement: totals.engagement,
+      engagementRate: ((totals.engagement / totals.reach) * 100).toFixed(2)
+    },
+    accounts: accountInsights,
+    publishingStats: publishingStats.rows
+  }
+}
+```
+
+**Export as PDF:**
+```typescript
+import { jsPDF } from 'jspdf'
+
+export async function exportReportAsPDF(clientId: string, month: number, year: number) {
+  const report = await generateMonthlyReport(clientId, year, month)
+
+  const doc = new jsPDF()
+  const monthNames = ['January', 'February', 'March', 'April', 'May', 'June',
+                      'July', 'August', 'September', 'October', 'November', 'December']
+
+  // Title Page
+  doc.setFontSize(24)
+  doc.text(report.client.name, 20, 30)
+  doc.setFontSize(18)
+  doc.text(`Social Media Report`, 20, 45)
+  doc.setFontSize(14)
+  doc.text(`${monthNames[month - 1]} ${year}`, 20, 55)
+
+  // Summary
+  doc.addPage()
+  doc.setFontSize(16)
+  doc.text('Executive Summary', 20, 30)
+  
+  doc.setFontSize(12)
+  let y = 50
+  doc.text(`Total Posts Published: ${report.summary.totalPosts}`, 20, y)
+  y += 10
+  doc.text(`Total Impressions: ${report.summary.totalImpressions.toLocaleString()}`, 20, y)
+  y += 10
+  doc.text(`Total Reach: ${report.summary.totalReach.toLocaleString()}`, 20, y)
+  y += 10
+  doc.text(`Total Engagement: ${report.summary.totalEngagement.toLocaleString()}`, 20, y)
+  y += 10
+  doc.text(`Engagement Rate: ${report.summary.engagementRate}%`, 20, y)
+
+  // Account Breakdown
+  doc.addPage()
+  doc.setFontSize(16)
+  doc.text('Account Performance', 20, 30)
+
+  y = 50
+  report.accounts.forEach((account) => {
+    if (account.error) return
+
+    doc.setFontSize(14)
+    doc.text(`${account.accountName}`, 20, y)
+    
+    doc.setFontSize(11)
+    y += 10
+    doc.text(`Platform: ${account.platform === 'instagram_business' ? 'Instagram' : 'Facebook'}`, 30, y)
+    y += 8
+    doc.text(`Followers: ${(account.followersCount || account.fanCount || 0).toLocaleString()}`, 30, y)
+    y += 8
+    doc.text(`Impressions: ${(account.impressions || 0).toLocaleString()}`, 30, y)
+    y += 8
+    doc.text(`Engagement: ${(account.engagement || 0).toLocaleString()}`, 30, y)
+    y += 15
+
+    if (y > 250) {
+      doc.addPage()
+      y = 30
+    }
+  })
+
+  // Save
+  doc.save(`${report.client.slug}-report-${year}-${month}.pdf`)
+}
+```
+
+## Comparative Analysis
+
+### Month-over-Month Comparison
+
+```typescript
+export async function getComparativeAnalytics(clientId: string) {
+  const currentMonth = new Date().getMonth() + 1
+  const currentYear = new Date().getFullYear()
+  const previousMonth = currentMonth === 1 ? 12 : currentMonth - 1
+  const previousYear = currentMonth === 1 ? currentYear - 1 : currentYear
+
+  const [current, previous] = await Promise.all([
+    generateMonthlyReport(clientId, currentYear, currentMonth),
+    generateMonthlyReport(clientId, previousYear, previousMonth)
+  ])
+
+  return {
+    current: current.summary,
+    previous: previous.summary,
+    changes: {
+      posts: calculateChange(current.summary.totalPosts, previous.summary.totalPosts),
+      impressions: calculateChange(current.summary.totalImpressions, previous.summary.totalImpressions),
+      reach: calculateChange(current.summary.totalReach, previous.summary.totalReach),
+      engagement: calculateChange(current.summary.totalEngagement, previous.summary.totalEngagement),
+      engagementRate: calculateChange(
+        parseFloat(current.summary.engagementRate),
+        parseFloat(previous.summary.engagementRate)
+      )
+    }
+  }
+}
+
+function calculateChange(current: number, previous: number) {
+  if (previous === 0) return { value: 0, percentage: 0 }
+  
+  const difference = current - previous
+  const percentage = ((difference / previous) * 100).toFixed(1)
+  
+  return {
+    value: difference,
+    percentage: parseFloat(percentage),
+    isPositive: difference >= 0
+  }
+}
+```
+
+**Display Comparison:**
+```typescript
+export function ComparativeAnalyticsDashboard({ data }: { data: any }) {
+  return (
+    <div className="grid grid-cols-2 gap-6">
+      {/* Current Month */}
+      <div>
+        <h3 className="font-medium mb-4">This Month</h3>
+        <div className="space-y-3">
+          <MetricWithChange
+            label="Posts"
+            current={data.current.totalPosts}
+            change={data.changes.posts}
+          />
+          <MetricWithChange
+            label="Impressions"
+            current={data.current.totalImpressions}
+            change={data.changes.impressions}
+          />
+          <MetricWithChange
+            label="Engagement"
+            current={data.current.totalEngagement}
+            change={data.changes.engagement}
+          />
+          <MetricWithChange
+            label="Engagement Rate"
+            current={`${data.current.engagementRate}%`}
+            change={data.changes.engagementRate}
+          />
+        </div>
+      </div>
+
+      {/* Previous Month */}
+      <div>
+        <h3 className="font-medium mb-4">Last Month</h3>
+        <div className="space-y-3">
+          <SimplMetric label="Posts" value={data.previous.totalPosts} />
+          <SimpleMetric label="Impressions" value={data.previous.totalImpressions} />
+          <SimpleMetric label="Engagement" value={data.previous.totalEngagement} />
+          <SimpleMetric label="Engagement Rate" value={`${data.previous.engagementRate}%`} />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function MetricWithChange({ label, current, change }: {
+  label: string
+  current: number | string
+  change: { value: number; percentage: number; isPositive: boolean }
+}) {
+  return (
+    <div className="border rounded p-3">
+      <p className="text-sm text-gray-600">{label}</p>
+      <div className="flex justify-between items-end">
+        <p className="text-2xl font-bold">{current}</p>
+        <div className={`text-sm ${change.isPositive ? 'text-green-600' : 'text-red-600'}`}>
+          {change.isPositive ? '↑' : '↓'} {Math.abs(change.percentage)}%
+        </div>
+      </div>
+    </div>
+  )
+}
+```
+
+## Best Practices
+
+### Data Refresh Strategy
+
+```typescript
+// Cache insights for 24 hours
+export async function getCachedInsights(accountId: string) {
+  const cacheKey = `insights:${accountId}`
+  
+  // Check cache
+  const cached = await redis.get(cacheKey)
+  if (cached) return JSON.parse(cached)
+
+  // Fetch fresh data
+  const insights = await getInstagramAnalytics(accountId)
+
+  // Cache for 24 hours
+  await redis.setex(cacheKey, 86400, JSON.stringify(insights))
+
+  return insights
+}
+```
+
+### Rate Limit Handling
+
+```typescript
+// Batch insights fetching to avoid rate limits
+export async function batchFetchInsights(accountIds: string[]) {
+  const results = []
+  
+  for (const accountId of accountIds) {
+    results.push(await getCachedInsights(accountId))
+    
+    // Wait 1 second between requests
+    await new Promise(resolve => setTimeout(resolve, 1000))
+  }
+  
+  return results
+}
+```
+
+## Next Steps
+
+- **[Agency Management](./01-agency-management.md)** - Multi-client workflows
+- **[Content Publishing](./02-content-publishing.md)** - Publishing workflows
+- **[Provider APIs](../03-advanced-usage/01-provider-apis.md)** - API reference