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

package/docs/03-advanced-usage/01-provider-apis.md

@@ -0,0 +1,764 @@
+# Provider APIs
+
+## Overview
+
+The Social Media Publisher plugin provides two comprehensive API wrappers for interacting with Facebook Graph API and Instagram Business API. These wrappers abstract the complexity of API calls, handle authentication, and provide type-safe interfaces.
+
+**Available Providers:**
+- **FacebookAPI** - Facebook Pages publishing and insights
+- **InstagramAPI** - Instagram Business publishing and analytics
+
+## FacebookAPI
+
+### Import
+
+```typescript
+import { FacebookAPI } from '@/contents/plugins/social-media-publisher/lib/providers/facebook'
+```
+
+### Publishing Methods
+
+#### `publishTextPost()`
+
+Publish text-only post to Facebook Page.
+
+**Signature:**
+```typescript
+static async publishTextPost(options: {
+  pageId: string
+  pageAccessToken: string
+  message: string
+}): Promise<FacebookPublishResult>
+```
+
+**Parameters:**
+- `pageId` - Facebook Page ID
+- `pageAccessToken` - Page access token (decrypted)
+- `message` - Post text content
+
+**Returns:**
+```typescript
+{
+  success: boolean
+  postId?: string  // e.g., "123456789_987654321"
+  postUrl?: string  // e.g., "https://www.facebook.com/123456789/posts/987654321"
+  error?: string
+  errorDetails?: unknown
+}
+```
+
+**Example:**
+```typescript
+const result = await FacebookAPI.publishTextPost({
+  pageId: '123456789',
+  pageAccessToken: decryptedToken,
+  message: 'Hello from our Facebook Page! 👋'
+})
+
+if (result.success) {
+  console.log(`Published: ${result.postUrl}`)
+} else {
+  console.error(`Failed: ${result.error}`)
+}
+```
+
+**Graph API Call:**
+```
+POST https://graph.facebook.com/v18.0/{PAGE_ID}/feed
+{
+  "message": "Post text here",
+  "access_token": "{PAGE_TOKEN}"
+}
+```
+
+#### `publishPhotoPost()`
+
+Publish photo with optional caption to Facebook Page.
+
+**Signature:**
+```typescript
+static async publishPhotoPost(options: {
+  pageId: string
+  pageAccessToken: string
+  message: string
+  imageUrl: string
+}): Promise<FacebookPublishResult>
+```
+
+**Parameters:**
+- `pageId` - Facebook Page ID
+- `pageAccessToken` - Page access token
+- `message` - Photo caption
+- `imageUrl` - Public HTTPS URL to image
+
+**Example:**
+```typescript
+const result = await FacebookAPI.publishPhotoPost({
+  pageId: '123456789',
+  pageAccessToken: decryptedToken,
+  message: 'Check out our new product!',
+  imageUrl: 'https://cdn.example.com/product.jpg'
+})
+```
+
+**Graph API Call:**
+```
+POST https://graph.facebook.com/v18.0/{PAGE_ID}/photos
+{
+  "url": "https://example.com/image.jpg",
+  "message": "Photo caption",
+  "access_token": "{PAGE_TOKEN}"
+}
+```
+
+**Image Requirements:**
+- Format: JPG, PNG, GIF, BMP
+- Max size: 4MB (recommended), up to 15MB
+- Must be publicly accessible via HTTPS
+
+#### `publishLinkPost()`
+
+Publish link with preview to Facebook Page.
+
+**Signature:**
+```typescript
+static async publishLinkPost(options: {
+  pageId: string
+  pageAccessToken: string
+  message: string
+  link: string
+}): Promise<FacebookPublishResult>
+```
+
+**Example:**
+```typescript
+const result = await FacebookAPI.publishLinkPost({
+  pageId: '123456789',
+  pageAccessToken: decryptedToken,
+  message: 'Read our latest blog post!',
+  link: 'https://example.com/blog/post'
+})
+```
+
+**Graph API Call:**
+```
+POST https://graph.facebook.com/v18.0/{PAGE_ID}/feed
+{
+  "message": "Check this out!",
+  "link": "https://example.com/article",
+  "access_token": "{PAGE_TOKEN}"
+}
+```
+
+**Link Requirements:**
+- Must use HTTPS
+- Facebook auto-generates preview using Open Graph tags
+- Preview customization via meta tags:
+  ```html
+  <meta property="og:title" content="Article Title" />
+  <meta property="og:description" content="Description" />
+  <meta property="og:image" content="https://example.com/preview.jpg" />
+  ```
+
+### Page Management Methods
+
+#### `getUserPages()`
+
+Get list of Facebook Pages user manages.
+
+**Signature:**
+```typescript
+static async getUserPages(userAccessToken: string): Promise<FacebookPageInfo[]>
+```
+
+**Returns:**
+```typescript
+interface FacebookPageInfo {
+  id: string              // Page ID
+  name: string            // Page name
+  category: string        // Page category
+  accessToken: string     // Page-specific access token
+  tasks: string[]         // Permissions granted
+  pictureUrl?: string     // Profile picture URL
+}
+```
+
+**Example:**
+```typescript
+const pages = await FacebookAPI.getUserPages(userAccessToken)
+
+pages.forEach(page => {
+  console.log(`${page.name} (${page.id})`)
+  console.log(`Permissions: ${page.tasks.join(', ')}`)
+})
+```
+
+**Graph API Call:**
+```
+GET https://graph.facebook.com/v18.0/me/accounts
+  ?fields=id,name,category,access_token,tasks,picture
+  &access_token={USER_TOKEN}
+```
+
+#### `getPageInfo()`
+
+Get detailed information about Facebook Page.
+
+**Signature:**
+```typescript
+static async getPageInfo(
+  pageId: string,
+  pageAccessToken: string
+): Promise<FacebookPageStats>
+```
+
+**Returns:**
+```typescript
+interface FacebookPageStats {
+  id: string
+  name: string
+  fanCount: number           // Follower count
+  about?: string
+  category?: string
+  profilePictureUrl?: string
+  coverPhotoUrl?: string
+  link?: string              // Page URL
+}
+```
+
+**Example:**
+```typescript
+const pageInfo = await FacebookAPI.getPageInfo(pageId, pageAccessToken)
+
+console.log(`${pageInfo.name}`)
+console.log(`Followers: ${pageInfo.fanCount.toLocaleString()}`)
+console.log(`About: ${pageInfo.about}`)
+```
+
+**Graph API Call:**
+```
+GET https://graph.facebook.com/v18.0/{PAGE_ID}
+  ?fields=id,name,fan_count,about,category,picture,cover,link
+  &access_token={PAGE_TOKEN}
+```
+
+#### `getPageInsights()`
+
+Get analytics for Facebook Page.
+
+**Signature:**
+```typescript
+static async getPageInsights(
+  pageId: string,
+  pageAccessToken: string
+): Promise<FacebookInsights>
+```
+
+**Returns:**
+```typescript
+interface FacebookInsights {
+  impressions: number     // Total impressions
+  reach: number           // Total reach
+  engagement: number      // Total engagement
+  reactions: number       // Total reactions
+  comments: number        // Total comments
+  shares: number          // Total shares
+}
+```
+
+**Example:**
+```typescript
+const insights = await FacebookAPI.getPageInsights(pageId, pageAccessToken)
+
+console.log(`Impressions: ${insights.impressions}`)
+console.log(`Engagement Rate: ${(insights.engagement / insights.reach * 100).toFixed(2)}%`)
+```
+
+**Note:** Requires `read_insights` permission.
+
+### Instagram Integration Methods
+
+#### `getInstagramBusinessAccount()`
+
+Get Instagram Business Account linked to Facebook Page.
+
+**Signature:**
+```typescript
+static async getInstagramBusinessAccount(
+  pageId: string,
+  pageAccessToken: string
+): Promise<{
+  id: string
+  username: string
+  name?: string
+  profilePictureUrl?: string
+  followersCount?: number
+  followsCount?: number
+  mediaCount?: number
+  biography?: string
+  website?: string
+} | null>
+```
+
+**Returns:** Instagram account info or `null` if not connected
+
+**Example:**
+```typescript
+const igAccount = await FacebookAPI.getInstagramBusinessAccount(
+  pageId,
+  pageAccessToken
+)
+
+if (igAccount) {
+  console.log(`Instagram: @${igAccount.username}`)
+  console.log(`Followers: ${igAccount.followersCount}`)
+} else {
+  console.log('No Instagram account connected to this Page')
+}
+```
+
+**Graph API Call:**
+```
+GET https://graph.facebook.com/v18.0/{PAGE_ID}
+  ?fields=instagram_business_account{id,username,name,profile_picture_url,followers_count,follows_count,media_count,biography,website}
+  &access_token={PAGE_TOKEN}
+```
+
+#### `validatePagePermissions()`
+
+Check which permissions are granted for a Page.
+
+**Signature:**
+```typescript
+static async validatePagePermissions(
+  pageId: string,
+  pageAccessToken: string
+): Promise<{
+  valid: boolean
+  permissions: string[]
+  missing: string[]
+}>
+```
+
+**Example:**
+```typescript
+const validation = await FacebookAPI.validatePagePermissions(
+  pageId,
+  pageAccessToken
+)
+
+console.log('Granted:', validation.permissions)
+console.log('Missing:', validation.missing)
+
+if (validation.missing.includes('pages_manage_posts')) {
+  console.warn('Cannot publish - missing pages_manage_posts permission')
+}
+```
+
+## InstagramAPI
+
+### Import
+
+```typescript
+import { InstagramAPI } from '@/contents/plugins/social-media-publisher/lib/providers/instagram'
+```
+
+### Publishing Methods
+
+#### `publishPhoto()`
+
+Publish photo to Instagram Business Account.
+
+**Signature:**
+```typescript
+static async publishPhoto(options: {
+  igAccountId: string
+  accessToken: string
+  imageUrl: string
+  caption?: string
+}): Promise<InstagramPublishResult>
+```
+
+**Parameters:**
+- `igAccountId` - Instagram Business Account ID
+- `accessToken` - Page access token (for linked Page)
+- `imageUrl` - Public HTTPS URL to image
+- `caption` - Optional caption (max 2,200 chars)
+
+**Returns:**
+```typescript
+{
+  success: boolean
+  postId?: string  // e.g., "17899618652010220"
+  postUrl?: string  // e.g., "https://www.instagram.com/p/ABC123"
+  error?: string
+  errorDetails?: unknown
+}
+```
+
+**Example:**
+```typescript
+const result = await InstagramAPI.publishPhoto({
+  igAccountId: '17841401234567890',
+  accessToken: decryptedToken,
+  imageUrl: 'https://cdn.example.com/photo.jpg',
+  caption: 'My awesome Instagram post! 📸 #photography'
+})
+
+if (result.success) {
+  console.log(`Posted: ${result.postUrl}`)
+}
+```
+
+**Process (2-Step Container):**
+1. **Create Media Container:**
+   ```
+   POST https://graph.facebook.com/v18.0/{IG_ACCOUNT_ID}/media
+   {
+     "image_url": "https://example.com/image.jpg",
+     "caption": "Caption here",
+     "access_token": "{TOKEN}"
+   }
+   ```
+
+2. **Publish Container:**
+   ```
+   POST https://graph.facebook.com/v18.0/{IG_ACCOUNT_ID}/media_publish
+   {
+     "creation_id": "{CONTAINER_ID}",
+     "access_token": "{TOKEN}"
+   }
+   ```
+
+**Image Requirements:**
+- Format: JPG or PNG
+- Size: Max 8MB
+- Dimensions: 320px to 1080px (width)
+- Aspect Ratio: 4:5 to 1.91:1
+- Must be publicly accessible via HTTPS
+
+**Caption Requirements:**
+- Max length: 2,200 characters
+- Max hashtags: 30
+- Max mentions: 20 (@username)
+- Supports emojis and line breaks
+
+#### `publishVideo()`
+
+Publish video to Instagram Business Account.
+
+**Signature:**
+```typescript
+static async publishVideo(options: {
+  igAccountId: string
+  accessToken: string
+  videoUrl: string
+  caption?: string
+}): Promise<InstagramPublishResult>
+```
+
+**Example:**
+```typescript
+const result = await InstagramAPI.publishVideo({
+  igAccountId: '17841401234567890',
+  accessToken: decryptedToken,
+  videoUrl: 'https://cdn.example.com/video.mp4',
+  caption: 'Watch this! 🎬 #video'
+})
+```
+
+**Video Requirements:**
+- Format: MP4 or MOV
+- Size: Max 100MB
+- Duration: 3 to 60 seconds
+- Dimensions: Min 600px (any dimension)
+- Aspect Ratio: 4:5 to 1.91:1
+- Frame Rate: Max 30fps
+
+**Processing Time:**
+- Videos require processing before publishing
+- Method waits up to 30 seconds for `FINISHED` status
+- Polls every 2 seconds for completion
+
+### Account Information Methods
+
+#### `getAccountInfo()`
+
+Get Instagram Business Account information.
+
+**Signature:**
+```typescript
+static async getAccountInfo(
+  igAccountId: string,
+  accessToken: string
+): Promise<InstagramAccountInfo>
+```
+
+**Returns:**
+```typescript
+interface InstagramAccountInfo {
+  id: string
+  username: string
+  accountType?: string
+  profilePictureUrl?: string
+  followersCount?: number
+  followsCount?: number
+  mediaCount?: number
+}
+```
+
+**Example:**
+```typescript
+const info = await InstagramAPI.getAccountInfo(igAccountId, accessToken)
+
+console.log(`@${info.username}`)
+console.log(`Followers: ${info.followersCount?.toLocaleString()}`)
+console.log(`Posts: ${info.mediaCount}`)
+```
+
+**Graph API Call:**
+```
+GET https://graph.facebook.com/v18.0/{IG_ACCOUNT_ID}
+  ?fields=id,username,account_type,profile_picture_url,followers_count,follows_count,media_count
+  &access_token={TOKEN}
+```
+
+#### `getAccountInsights()`
+
+Get Instagram account-level insights.
+
+**Signature:**
+```typescript
+static async getAccountInsights(
+  igAccountId: string,
+  accessToken: string
+): Promise<InstagramInsights>
+```
+
+**Returns:**
+```typescript
+interface InstagramInsights {
+  impressions: number
+  reach: number
+  engagement: number
+  likes: number
+  comments: number
+  saves: number
+  profileViews: number
+}
+```
+
+**Example:**
+```typescript
+const insights = await InstagramAPI.getAccountInsights(igAccountId, accessToken)
+
+console.log(`Total Impressions: ${insights.impressions}`)
+console.log(`Engagement Rate: ${(insights.engagement / insights.reach * 100).toFixed(2)}%`)
+```
+
+**Note:** Requires `instagram_manage_insights` permission.
+
+#### `getMediaInsights()`
+
+Get insights for specific Instagram post.
+
+**Signature:**
+```typescript
+static async getMediaInsights(
+  mediaId: string,
+  accessToken: string
+): Promise<Partial<InstagramInsights>>
+```
+
+**Example:**
+```typescript
+const postInsights = await InstagramAPI.getMediaInsights(
+  '17899618652010220',
+  accessToken
+)
+
+console.log(`Likes: ${postInsights.likes}`)
+console.log(`Comments: ${postInsights.comments}`)
+console.log(`Saves: ${postInsights.saves}`)
+```
+
+**Graph API Call:**
+```
+GET https://graph.facebook.com/v18.0/{MEDIA_ID}/insights
+  ?metric=impressions,reach,engagement,likes,comments,saves
+  &access_token={TOKEN}
+```
+
+## Error Handling
+
+### Common Error Types
+
+**Invalid Token:**
+```typescript
+try {
+  await FacebookAPI.publishTextPost({ ... })
+} catch (error) {
+  if (error.message.includes('Invalid OAuth')) {
+    // Token expired or revoked - need to reconnect
+    console.error('Token invalid - user must reconnect account')
+  }
+}
+```
+
+**Rate Limiting:**
+```typescript
+try {
+  await InstagramAPI.publishPhoto({ ... })
+} catch (error) {
+  if (error.message.includes('rate limit')) {
+    // Too many requests - wait and retry
+    console.error('Rate limit reached - retry later')
+  }
+}
+```
+
+**Permission Errors:**
+```typescript
+try {
+  await FacebookAPI.getPageInsights({ ... })
+} catch (error) {
+  if (error.message.includes('read_insights')) {
+    // Missing required permission
+    console.error('User needs to grant read_insights permission')
+  }
+}
+```
+
+**Image Not Accessible:**
+```typescript
+try {
+  await InstagramAPI.publishPhoto({ ... })
+} catch (error) {
+  if (error.message.includes('publicly accessible')) {
+    // Image URL not reachable
+    console.error('Image must be publicly accessible via HTTPS')
+  }
+}
+```
+
+### Error Handling Pattern
+
+```typescript
+async function safePublish(options: PublishOptions): Promise<PublishResult> {
+  try {
+    const result = await InstagramAPI.publishPhoto(options)
+    
+    if (!result.success) {
+      // Log failure
+      await logAuditEvent('post_failed', {
+        error: result.error,
+        errorDetails: result.errorDetails
+      })
+      
+      return { success: false, error: result.error }
+    }
+    
+    // Log success
+    await logAuditEvent('post_published', {
+      postId: result.postId,
+      postUrl: result.postUrl
+    })
+    
+    return result
+    
+  } catch (error) {
+    // Unexpected error
+    console.error('Unexpected publish error:', error)
+    
+    await logAuditEvent('post_failed', {
+      error: 'Unexpected error',
+      details: error instanceof Error ? error.message : String(error)
+    })
+    
+    return { success: false, error: 'Unexpected error occurred' }
+  }
+}
+```
+
+## Usage Examples
+
+### Batch Publishing
+
+```typescript
+async function publishToMultiplePlatforms(
+  accounts: SocialAccount[],
+  imageUrl: string,
+  caption: string
+) {
+  const results = await Promise.allSettled(
+    accounts.map(async (account) => {
+      const [encrypted, iv, keyId] = account.accessToken.split(':')
+      const token = await TokenEncryption.decrypt(encrypted, iv, keyId)
+      
+      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
+        })
+      }
+    })
+  )
+  
+  return {
+    successful: results.filter(r => r.status === 'fulfilled').length,
+    failed: results.filter(r => r.status === 'rejected').length,
+    results
+  }
+}
+```
+
+### Account Sync
+
+```typescript
+async function syncAccountStats(accountId: string) {
+  const account = await getAccountFromDB(accountId)
+  const [encrypted, iv, keyId] = account.accessToken.split(':')
+  const token = await TokenEncryption.decrypt(encrypted, iv, keyId)
+  
+  if (account.platform === 'instagram_business') {
+    const info = await InstagramAPI.getAccountInfo(
+      account.platformAccountId,
+      token
+    )
+    
+    await updateAccountMetadata(accountId, {
+      followersCount: info.followersCount,
+      mediaCount: info.mediaCount,
+      profilePictureUrl: info.profilePictureUrl,
+      lastSyncAt: new Date().toISOString()
+    })
+  } else {
+    const info = await FacebookAPI.getPageInfo(
+      account.platformAccountId,
+      token
+    )
+    
+    await updateAccountMetadata(accountId, {
+      fanCount: info.fanCount,
+      about: info.about,
+      profilePictureUrl: info.profilePictureUrl,
+      lastSyncAt: new Date().toISOString()
+    })
+  }
+}
+```
+
+## Next Steps
+
+- **[Custom Integrations](./02-custom-integrations.md)** - Build custom features with providers
+- **[Publishing](../02-core-features/02-publishing.md)** - Use providers in publishing endpoint
+- **[Token Management](../02-core-features/03-token-management.md)** - Secure token handling