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

package/docs/01-getting-started/02-installation.md

@@ -0,0 +1,471 @@
+# Installation and Setup
+
+## Prerequisites
+
+Before installing the Social Media Publisher plugin, ensure you have:
+
+- ✅ NextSpark project set up and running
+- ✅ PostgreSQL database configured
+- ✅ Active theme with plugin support
+- ✅ Facebook Developer account (free)
+- ✅ Instagram Business Account (for Instagram publishing)
+- ✅ Facebook Page (for Instagram Business connection or Facebook publishing)
+
+## Step 1: Create Facebook App
+
+### 1.1 Register as Facebook Developer
+
+1. Visit [Facebook Developers](https://developers.facebook.com/)
+2. Click "Get Started" or "My Apps"
+3. Complete developer registration (if needed)
+
+### 1.2 Create New App
+
+1. Click "Create App"
+2. Select "Business" as app type
+3. Fill in app details:
+   - **App Name:** Your SaaS Name Social Media
+   - **App Contact Email:** your@email.com
+   - **Business Account:** (Optional) Select if you have one
+4. Click "Create App"
+
+### 1.3 Configure OAuth Settings
+
+**Add Facebook Login Product:**
+
+1. In app dashboard, click "Add Product"
+2. Find "Facebook Login" → Click "Set Up"
+3. Select "Web" as platform
+4. Skip quick start (we'll configure manually)
+
+**Configure OAuth Redirect URLs:**
+
+1. Go to "Facebook Login" → "Settings"
+2. Add **Valid OAuth Redirect URIs:**
+
+```
+Development:
+http://localhost:5173/api/v1/plugin/social-media-publisher/social/connect/callback
+
+Production:
+https://yourdomain.com/api/v1/plugin/social-media-publisher/social/connect/callback
+```
+
+3. **Client OAuth Login:** ON
+4. **Web OAuth Login:** ON
+5. Save changes
+
+### 1.4 Request Permissions
+
+**For Instagram Business:**
+
+1. Go to "App Review" → "Permissions and Features"
+2. Request these permissions:
+   - `pages_show_list` - Required
+   - `pages_manage_posts` - Required
+   - `pages_read_engagement` - Required
+   - `instagram_basic` - Required
+   - `instagram_content_publish` - Required
+   - `instagram_manage_insights` - Optional (for analytics)
+
+**For Facebook Pages:**
+
+1. Same permissions as above
+2. Already includes everything needed for Page publishing
+
+**Note:** These permissions require App Review for production apps. During development, admins, developers, and testers can use them immediately.
+
+### 1.5 Get App Credentials
+
+1. Go to "Settings" → "Basic"
+2. Copy your credentials:
+   - **App ID** (will be `FACEBOOK_CLIENT_ID`)
+   - **App Secret** (will be `FACEBOOK_CLIENT_SECRET`)
+3. Keep these secure!
+
+## Step 2: Configure Environment Variables
+
+### 2.1 Core Environment File
+
+Create or update your main `.env` file:
+
+```bash
+# Facebook OAuth Credentials
+FACEBOOK_CLIENT_ID=your_app_id_here
+FACEBOOK_CLIENT_SECRET=your_app_secret_here
+
+# App URL (important for OAuth redirects)
+NEXT_PUBLIC_APP_URL=http://localhost:5173
+
+# OAuth Token Encryption (32-byte hex key)
+OAUTH_ENCRYPTION_KEY=your_encryption_key_here
+```
+
+### 2.2 Generate Encryption Key
+
+The `OAUTH_ENCRYPTION_KEY` is used to encrypt OAuth tokens in the database.
+
+**Generate a secure key:**
+
+```bash
+# Using Node.js
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+
+# Output example:
+# a7f9b2c8d1e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9
+```
+
+**Add to `.env`:**
+```bash
+OAUTH_ENCRYPTION_KEY=a7f9b2c8d1e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9
+```
+
+**Security Notes:**
+- ✅ Key must be exactly 32 bytes (64 hex characters)
+- ✅ Generate unique key for each environment
+- ✅ Never commit to version control
+- ✅ Store securely in production (e.g., AWS Secrets Manager)
+- ✅ Rotate periodically (requires re-connecting accounts)
+
+### 2.3 Environment Variable Reference
+
+```bash
+# ==============================================
+# FACEBOOK OAUTH CONFIGURATION
+# ==============================================
+
+# Facebook App ID (from App Dashboard → Settings → Basic)
+FACEBOOK_CLIENT_ID=123456789012345
+
+# Facebook App Secret (from App Dashboard → Settings → Basic)
+FACEBOOK_CLIENT_SECRET=abcdef123456789abcdef123456789ab
+
+# ==============================================
+# APPLICATION URL
+# ==============================================
+
+# Base URL of your application (no trailing slash)
+# Development:
+NEXT_PUBLIC_APP_URL=http://localhost:5173
+
+# Production:
+# NEXT_PUBLIC_APP_URL=https://yourdomain.com
+
+# ==============================================
+# SECURITY
+# ==============================================
+
+# 32-byte encryption key for OAuth tokens (64 hex chars)
+# Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+OAUTH_ENCRYPTION_KEY=your_32_byte_key_in_hex_format
+
+# ==============================================
+# DATABASE (if not already configured)
+# ==============================================
+
+DATABASE_URL=postgresql://user:password@localhost:5432/database
+```
+
+## Step 3: Enable Plugin
+
+### 3.1 Add to Theme Configuration
+
+Edit your theme's `theme.config.ts`:
+
+```typescript
+// contents/themes/[your-theme]/theme.config.ts
+export const yourThemeConfig: ThemeConfig = {
+  name: 'your-theme',
+  // ... other config
+  
+  plugins: [
+    'ai',
+    'social-media-publisher'  // Add this line
+  ]
+}
+```
+
+### 3.2 Verify Plugin Loads
+
+```bash
+# Start development server
+pnpm dev
+
+# Check console for plugin load message:
+# [Social Media Publisher] Plugin loaded - OAuth publishing ready
+```
+
+## Step 4: Database Setup
+
+### 4.1 Run Migrations
+
+The plugin includes migrations for the required tables:
+
+```bash
+# Apply all pending migrations
+pnpm db:migrate
+
+# Or specifically for social media publisher:
+psql $DATABASE_URL -f contents/plugins/social-media-publisher/migrations/001_social_media_tables.sql
+```
+
+### 4.2 Verify Tables Created
+
+```sql
+-- Check if tables exist
+SELECT table_name 
+FROM information_schema.tables 
+WHERE table_name IN ('clients_social_platforms', 'audit_logs');
+
+-- Should return:
+-- clients_social_platforms
+-- audit_logs
+```
+
+### 4.3 Database Schema Overview
+
+**clients_social_platforms (Child Entity):**
+```sql
+CREATE TABLE "clients_social_platforms" (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  "parentId" UUID NOT NULL REFERENCES "clients"(id) ON DELETE CASCADE,
+  platform TEXT NOT NULL,
+  "platformAccountId" TEXT,
+  "platformAccountName" TEXT NOT NULL,
+  "accessToken" TEXT NOT NULL,
+  "tokenExpiresAt" TIMESTAMPTZ NOT NULL,
+  permissions JSONB DEFAULT '[]',
+  "accountMetadata" JSONB DEFAULT '{}',
+  "isActive" BOOLEAN DEFAULT true,
+  "createdAt" TIMESTAMPTZ DEFAULT now(),
+  "updatedAt" TIMESTAMPTZ DEFAULT now()
+);
+```
+
+**audit_logs (Plugin Entity):**
+```sql
+CREATE TABLE "audit_logs" (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  "userId" TEXT NOT NULL,
+  "accountId" UUID,
+  action TEXT NOT NULL,
+  details JSONB DEFAULT '{}',
+  "ipAddress" TEXT,
+  "userAgent" TEXT,
+  "createdAt" TIMESTAMPTZ DEFAULT now()
+);
+```
+
+## Step 5: Configure Facebook App for Production
+
+### 5.1 App Review Process
+
+**For Production Use:**
+
+1. Go to "App Review" → "Permissions and Features"
+2. Click "Request" next to each required permission
+3. Fill out "App Questionnaire" explaining use case
+4. Submit screenshots showing OAuth flow
+5. Wait for approval (typically 1-3 days)
+
+**Required Permissions:**
+- `pages_show_list`
+- `pages_manage_posts`
+- `pages_read_engagement`
+- `instagram_basic`
+- `instagram_content_publish`
+
+### 5.2 Switch to Live Mode
+
+1. App dashboard → Top toggle
+2. Switch from "Development" to "Live"
+3. Confirm app is ready for public use
+
+**Before Going Live:**
+- ✅ Permissions approved
+- ✅ Privacy policy URL added
+- ✅ Terms of service URL added
+- ✅ App icon uploaded
+- ✅ Category selected
+- ✅ Business verification completed
+
+## Step 6: Connect Instagram Business Account
+
+**Important:** Instagram Business accounts must be connected to a Facebook Page.
+
+### 6.1 Link Instagram to Facebook Page
+
+1. Go to your Facebook Page
+2. Click "Settings"
+3. In left sidebar, click "Instagram"
+4. Click "Connect Account"
+5. Log in to Instagram
+6. Authorize connection
+7. Select Instagram Business Account
+
+**Note:** Personal Instagram accounts cannot be used. You must have an Instagram Business or Creator account.
+
+### 6.2 Verify Connection
+
+```bash
+# Test Graph API endpoint
+curl "https://graph.facebook.com/v18.0/{PAGE_ID}?fields=instagram_business_account&access_token={PAGE_TOKEN}"
+
+# Should return:
+{
+  "instagram_business_account": {
+    "id": "17841..." 
+  },
+  "id": "123456..."
+}
+```
+
+## Step 7: Verification
+
+### 7.1 Test OAuth Flow
+
+1. Navigate to a client detail page in your app
+2. Click "Add Social Platform"
+3. Select "Instagram Business"
+4. OAuth popup should open
+5. Authorize with Facebook
+6. Popup should close and accounts appear
+
+### 7.2 Verify Database
+
+```sql
+-- Check connected accounts
+SELECT 
+  id, 
+  "parentId", 
+  platform, 
+  "platformAccountName",
+  "tokenExpiresAt",
+  "isActive"
+FROM "clients_social_platforms"
+WHERE "isActive" = true;
+
+-- Check encrypted tokens (should have format: encrypted:iv:keyId)
+SELECT 
+  id,
+  LENGTH("accessToken") as token_length,
+  "accessToken" LIKE '%:%:%' as is_encrypted
+FROM "clients_social_platforms";
+```
+
+### 7.3 Test Publishing
+
+```bash
+# Test publish endpoint
+curl -X POST http://localhost:5173/api/v1/plugin/social-media-publisher/social/publish \
+  -H "Content-Type: application/json" \
+  -H "Cookie: your-session-cookie" \
+  -d '{
+    "accountId": "social-platform-uuid",
+    "platform": "instagram_business",
+    "imageUrl": "https://example.com/image.jpg",
+    "caption": "Test post"
+  }'
+```
+
+## Troubleshooting
+
+### Issue: "Invalid OAuth Redirect URI"
+
+**Cause:** Redirect URI not configured in Facebook App
+
+**Solution:**
+1. Go to Facebook App → Facebook Login → Settings
+2. Add exact callback URL to "Valid OAuth Redirect URIs"
+3. Format: `https://yourdomain.com/api/v1/plugin/social-media-publisher/social/connect/callback`
+4. Save changes
+
+### Issue: "OAUTH_ENCRYPTION_KEY validation failed"
+
+**Cause:** Missing or invalid encryption key
+
+**Solution:**
+```bash
+# Generate new key
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+
+# Add to .env (must be exactly 64 hex characters)
+OAUTH_ENCRYPTION_KEY=generated_key_here
+
+# Restart server
+pnpm dev
+```
+
+### Issue: "No Instagram Business Account found"
+
+**Cause:** Facebook Page not linked to Instagram Business Account
+
+**Solution:**
+1. Go to Facebook Page Settings
+2. Click "Instagram" in sidebar
+3. Connect Instagram Business Account
+4. Verify connection:
+   ```bash
+   # Should show instagram_business_account field
+   curl "https://graph.facebook.com/v18.0/{PAGE_ID}?fields=instagram_business_account&access_token={TOKEN}"
+   ```
+
+### Issue: "Permission denied" during publish
+
+**Cause:** Missing OAuth permissions
+
+**Solution:**
+1. Disconnect and reconnect account (gets new permissions)
+2. Verify permissions in Facebook App Review
+3. Check RLS policies allow user to access client
+
+### Issue: "App not set up: This app is still in development mode"
+
+**Cause:** Using app with non-admin users while in Development mode
+
+**Solutions:**
+- Add users as "Testers" or "Developers" in App Roles
+- OR Switch app to Live mode (requires App Review)
+
+### Issue: "clients_social_platforms table does not exist"
+
+**Cause:** Migrations not run
+
+**Solution:**
+```bash
+# Run migrations
+pnpm db:migrate
+
+# Or manually:
+psql $DATABASE_URL -f contents/plugins/social-media-publisher/migrations/001_social_media_tables.sql
+```
+
+## Security Checklist
+
+Before going to production, verify:
+
+- [ ] `FACEBOOK_CLIENT_SECRET` not committed to git
+- [ ] `OAUTH_ENCRYPTION_KEY` not committed to git
+- [ ] `.env` in `.gitignore`
+- [ ] Unique encryption key per environment
+- [ ] HTTPS enabled in production
+- [ ] RLS policies active on all tables
+- [ ] Audit logging enabled
+- [ ] Facebook App in Live mode with permissions approved
+- [ ] Token encryption verified (check database format)
+- [ ] Privacy policy URL added to Facebook App
+- [ ] Terms of service URL added to Facebook App
+
+## Next Steps
+
+✅ Plugin installed and configured  
+✅ Facebook App created and approved  
+✅ Database tables created  
+✅ OAuth flow tested  
+✅ Publishing verified
+
+**Continue to:**
+- **[Configuration](./03-configuration.md)** - Detailed configuration options
+- **[OAuth Integration](../02-core-features/01-oauth-integration.md)** - Understanding OAuth flow
+- **[Publishing](../02-core-features/02-publishing.md)** - Start publishing content
+- **[Per-Client Architecture](../03-advanced-usage/03-per-client-architecture.md)** - Understand the data model