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

package/lib/validation.ts

@@ -0,0 +1,155 @@
+/**
+ * Social Media Publisher - Validation Schemas
+ *
+ * Zod schemas for request validation
+ */
+
+import { z } from 'zod'
+
+// ============================================
+// PUBLISH REQUEST SCHEMAS
+// ============================================
+
+export const PublishPhotoSchema = z.object({
+  accountId: z.string().uuid('Invalid account ID'),
+  imageUrl: z.string().url('Invalid image URL').nullish(), // ✅ Accepts null/undefined - Facebook allows text-only
+  imageUrls: z.array(z.string().url('Invalid image URL')).optional(), // For carousels
+  caption: z.string().max(2200).optional(),
+  platform: z.enum(['instagram_business', 'facebook_page']),
+}).refine(data => {
+  // Instagram requires at least one image
+  if (data.platform === 'instagram_business') {
+    return (data.imageUrl || (data.imageUrls && data.imageUrls.length > 0))
+  }
+  return true
+}, { message: 'Instagram requires at least one image' }).refine(data => {
+  // Instagram allows maximum 10 images per carousel
+  if (data.platform === 'instagram_business' && data.imageUrls && data.imageUrls.length > 10) {
+    return false
+  }
+  return true
+}, { message: 'Instagram allows maximum 10 images per carousel' })
+
+export const PublishTextSchema = z.object({
+  accountId: z.string().uuid('Invalid account ID'),
+  message: z.string().min(1, 'Message is required').max(5000),
+  platform: z.literal('facebook_page'), // Only Facebook supports text-only posts
+})
+
+export const PublishLinkSchema = z.object({
+  accountId: z.string().uuid('Invalid account ID'),
+  message: z.string().max(5000).optional(),
+  linkUrl: z.string().url('Invalid link URL'),
+  platform: z.literal('facebook_page'),
+})
+
+// ============================================
+// CONNECT ACCOUNT SCHEMAS
+// ============================================
+
+export const ConnectAccountSchema = z.object({
+  code: z.string().min(1, 'Authorization code is required'),
+  state: z.string().min(1, 'State parameter is required'),
+  platform: z.enum(['instagram_business', 'facebook_page']),
+})
+
+// ============================================
+// DISCONNECT ACCOUNT SCHEMAS
+// ============================================
+
+export const DisconnectAccountSchema = z.object({
+  accountId: z.string().uuid('Invalid account ID'),
+})
+
+// ============================================
+// VALIDATION HELPERS
+// ============================================
+
+/**
+ * Validate image URL requirements
+ */
+export function validateImageUrl(url: string): {
+  valid: boolean
+  error?: string
+} {
+  try {
+    const parsed = new URL(url)
+
+    // Must be HTTPS
+    if (parsed.protocol !== 'https:') {
+      return {
+        valid: false,
+        error: 'Image URL must use HTTPS protocol',
+      }
+    }
+
+    // Must not be localhost
+    if (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1') {
+      return {
+        valid: false,
+        error: 'Image URL cannot be localhost',
+      }
+    }
+
+    // Check file extension
+    const validExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.webp']
+    const hasValidExtension = validExtensions.some(ext =>
+      parsed.pathname.toLowerCase().endsWith(ext)
+    )
+
+    if (!hasValidExtension) {
+      return {
+        valid: false,
+        error: `Image must be one of: ${validExtensions.join(', ')}`,
+      }
+    }
+
+    return { valid: true }
+  } catch (error) {
+    return {
+      valid: false,
+      error: 'Invalid URL format',
+    }
+  }
+}
+
+/**
+ * Validate caption length for platform
+ */
+export function validateCaption(
+  caption: string,
+  platform: 'instagram_business' | 'facebook_page'
+): {
+  valid: boolean
+  error?: string
+} {
+  const maxLengths = {
+    instagram_business: 2200,
+    facebook_page: 63206,
+  }
+
+  const maxLength = maxLengths[platform]
+
+  if (caption.length > maxLength) {
+    return {
+      valid: false,
+      error: `Caption exceeds maximum length of ${maxLength} characters for ${platform}`,
+    }
+  }
+
+  return { valid: true }
+}
+
+/**
+ * Check if a platform requires an image to publish
+ * Instagram: Always requires image/video
+ * Facebook: Allows text-only posts
+ */
+export function platformRequiresImage(platform: string): boolean {
+  const platformsRequiringImage = [
+    'instagram_business',
+    'tiktok',
+    'pinterest',
+  ]
+  return platformsRequiringImage.includes(platform)
+}

package/migrations/001_social_media_tables.sql

@@ -0,0 +1,167 @@
+-- Migration: 009_social_media_publisher.sql
+-- Description: Tables for social media publishing plugin
+-- Date: 2025-10-20
+-- Plugin: social-media-publisher
+
+-- ============================================
+-- TABLES
+-- ============================================
+
+-- Social Accounts Table
+-- Stores OAuth-connected social media accounts for publishing
+-- Supports multiple accounts per platform per user
+CREATE TABLE IF NOT EXISTS "social_accounts" (
+  id                          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  "userId"                    TEXT NOT NULL REFERENCES "users"(id) ON DELETE CASCADE,
+  platform                    TEXT NOT NULL CHECK (platform IN ('instagram_business', 'facebook_page')),
+  "platformAccountId"         TEXT NOT NULL,
+  "username"                  TEXT NOT NULL,
+  "accessToken"               TEXT NOT NULL, -- Encrypted (format: encrypted:iv:keyId)
+  "tokenExpiresAt"            TIMESTAMPTZ NOT NULL,
+  permissions                 JSONB DEFAULT '[]'::jsonb,
+  "accountMetadata"           JSONB DEFAULT '{}'::jsonb,
+  "isActive"                  BOOLEAN DEFAULT true,
+  "createdAt"                 TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "updatedAt"                 TIMESTAMPTZ NOT NULL DEFAULT now(),
+
+  -- Constraints
+  UNIQUE("platformAccountId") -- Prevent same account connected multiple times
+);
+
+-- Audit Logs Table
+-- Tracks all actions performed through social media plugin
+-- Note: accountId references clients_social_platforms.id (not enforced with FK to preserve historical logs)
+CREATE TABLE IF NOT EXISTS "audit_logs" (
+  id                          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  "userId"                    TEXT NOT NULL REFERENCES "users"(id) ON DELETE CASCADE,
+  "accountId"                 UUID, -- References clients_social_platforms.id (nullable, no FK to preserve historical logs)
+  action                      TEXT NOT NULL CHECK (action IN (
+    'account_connected',
+    'account_disconnected',
+    'post_published',
+    'post_failed',
+    'token_refreshed',
+    'token_refresh_failed'
+  )),
+  details                     JSONB DEFAULT '{}'::jsonb,
+  "ipAddress"                 TEXT,
+  "userAgent"                 TEXT,
+  "createdAt"                 TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- ============================================
+-- INDEXES
+-- ============================================
+
+-- Social Accounts indexes
+CREATE INDEX IF NOT EXISTS idx_social_accounts_user_platform
+  ON "social_accounts"("userId", platform);
+
+CREATE INDEX IF NOT EXISTS idx_social_accounts_platform_id_unique
+  ON "social_accounts"("platformAccountId");
+
+CREATE INDEX IF NOT EXISTS idx_social_accounts_active
+  ON "social_accounts"("isActive");
+
+CREATE INDEX IF NOT EXISTS idx_social_accounts_token_expiry
+  ON "social_accounts"("tokenExpiresAt");
+
+-- Audit Logs indexes
+CREATE INDEX IF NOT EXISTS idx_audit_logs_user_created
+  ON "audit_logs"("userId", "createdAt");
+
+CREATE INDEX IF NOT EXISTS idx_audit_logs_account_action
+  ON "audit_logs"("accountId", action);
+
+CREATE INDEX IF NOT EXISTS idx_audit_logs_action_created
+  ON "audit_logs"(action, "createdAt");
+
+CREATE INDEX IF NOT EXISTS idx_audit_logs_created_desc
+  ON "audit_logs"("createdAt" DESC);
+
+-- ============================================
+-- RLS (Enable)
+-- ============================================
+
+ALTER TABLE "social_accounts" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "audit_logs" ENABLE ROW LEVEL SECURITY;
+
+-- ============================================
+-- POLICIES
+-- ============================================
+
+-- Social Accounts Policies
+-- Users can only see and manage their own accounts
+CREATE POLICY "social_accounts_select_own"
+  ON "social_accounts" FOR SELECT
+  USING ("userId" = current_setting('app.current_user_id', true));
+
+CREATE POLICY "social_accounts_insert_own"
+  ON "social_accounts" FOR INSERT
+  WITH CHECK ("userId" = current_setting('app.current_user_id', true));
+
+CREATE POLICY "social_accounts_update_own"
+  ON "social_accounts" FOR UPDATE
+  USING ("userId" = current_setting('app.current_user_id', true));
+
+CREATE POLICY "social_accounts_delete_own"
+  ON "social_accounts" FOR DELETE
+  USING ("userId" = current_setting('app.current_user_id', true));
+
+-- Audit Logs Policies
+-- Users can only view their own audit logs
+CREATE POLICY "audit_logs_select_own"
+  ON "audit_logs" FOR SELECT
+  USING ("userId" = current_setting('app.current_user_id', true));
+
+-- Only system can insert audit logs
+CREATE POLICY "audit_logs_insert_system"
+  ON "audit_logs" FOR INSERT
+  WITH CHECK (true); -- System role bypasses RLS
+
+-- Audit logs are immutable (no updates)
+-- No update policy = no one can update
+
+-- Only admins can delete old audit logs
+CREATE POLICY "audit_logs_delete_admin"
+  ON "audit_logs" FOR DELETE
+  USING (current_setting('app.current_user_role', true) = 'admin');
+
+-- ============================================
+-- TRIGGERS (updatedAt)
+-- ============================================
+
+DROP TRIGGER IF EXISTS social_accounts_set_updated_at ON "social_accounts";
+CREATE TRIGGER social_accounts_set_updated_at
+BEFORE UPDATE ON "social_accounts"
+FOR EACH ROW EXECUTE FUNCTION public.set_updated_at();
+
+-- Note: audit_logs doesn't need updatedAt trigger (immutable)
+
+-- ============================================
+-- COMMENTS (Documentation)
+-- ============================================
+
+COMMENT ON TABLE "social_accounts" IS
+  'OAuth-connected social media accounts for publishing (Instagram Business & Facebook Pages)';
+
+COMMENT ON COLUMN "social_accounts"."accessToken" IS
+  'Encrypted OAuth access token (format: encrypted:iv:keyId using AES-256-GCM)';
+
+COMMENT ON COLUMN "social_accounts"."platformAccountId" IS
+  'Instagram Business Account ID or Facebook Page ID from platform';
+
+COMMENT ON COLUMN "social_accounts"."permissions" IS
+  'Array of granted OAuth scopes (e.g., ["instagram_business_basic", "instagram_business_content_publish"])';
+
+COMMENT ON COLUMN "social_accounts"."accountMetadata" IS
+  'Platform-specific metadata: profile picture URL, follower count, linked page info, etc.';
+
+COMMENT ON TABLE "audit_logs" IS
+  'Immutable audit trail for all social media actions (security & compliance)';
+
+COMMENT ON COLUMN "audit_logs"."accountId" IS
+  'References social platform account ID (clients_social_platforms.id). Nullable to preserve historical logs even after account deletion.';
+
+COMMENT ON COLUMN "audit_logs".details IS
+  'Action details: platform, success status, error messages, post IDs, etc.';

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@nextsparkjs/plugin-social-media-publisher",
+  "version": "0.1.0-beta.1",
+  "private": false,
+  "main": "./plugin.config.ts",
+  "requiredPlugins": [],
+  "dependencies": {},
+  "peerDependencies": {
+    "@nextsparkjs/core": "workspace:*",
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zod": "^4.0.0"
+  }
+}

package/plugin.config.ts

@@ -0,0 +1,81 @@
+/**
+ * Social Media Publisher Plugin Configuration
+ *
+ * Enables publishing to Instagram Business & Facebook Pages
+ * with OAuth token management and multi-account support
+ */
+
+import type { PluginConfig } from '@nextsparkjs/core/types/plugin'
+
+// OAuth Providers configuration (plugin-specific metadata)
+const OAUTH_PROVIDERS = {
+  facebook: {
+    name: 'Facebook',
+    authEndpoint: 'https://www.facebook.com/v18.0/dialog/oauth',
+    tokenEndpoint: 'https://graph.facebook.com/v18.0/oauth/access_token',
+    apiVersion: 'v18.0',
+    scopes: {
+      minimal: ['email', 'public_profile'],
+      publishing: [
+        'pages_show_list',
+        'pages_manage_posts',
+        'pages_read_engagement'
+      ]
+    }
+  },
+  instagram: {
+    name: 'Instagram Business',
+    authEndpoint: 'https://www.facebook.com/v18.0/dialog/oauth', // Uses Facebook OAuth
+    tokenEndpoint: 'https://graph.facebook.com/v18.0/oauth/access_token',
+    apiVersion: 'v18.0',
+    scopes: {
+      minimal: ['instagram_basic'],
+      publishing: [
+        'instagram_basic',
+        'instagram_content_publish',
+        'instagram_manage_insights'
+      ]
+    }
+  }
+} as const
+
+// Feature flags (plugin-specific metadata)
+const PLUGIN_FEATURES = {
+  multiAccountSupport: true,
+  tokenAutoRefresh: true,
+  auditLogging: true,
+  permissionValidation: true
+} as const
+
+/**
+ * Social Media Publisher Plugin Configuration
+ * Follows PluginConfig interface for registry compatibility
+ */
+export const socialMediaPublisherPluginConfig: PluginConfig = {
+  name: 'social-media-publisher',
+  displayName: 'Social Media Publisher',
+  version: '1.0.0',
+  description: 'Publish content to Instagram Business & Facebook Pages with OAuth integration',
+  enabled: true,
+  dependencies: [], // No plugin dependencies (uses core OAuth infrastructure)
+
+  // Plugin API - exports metadata for themes/plugins to use
+  api: {
+    providers: OAUTH_PROVIDERS,
+    features: PLUGIN_FEATURES,
+    entities: ['audit-logs']
+  },
+
+  // Plugin lifecycle hooks
+  hooks: {
+    onLoad: async () => {
+      console.log('[Social Media Publisher] Plugin loaded - OAuth publishing ready')
+    }
+  }
+}
+
+// Default export for compatibility
+export default socialMediaPublisherPluginConfig
+
+// Type exports
+export type SocialMediaPublisherConfig = typeof socialMediaPublisherPluginConfig

package/tsconfig.json

@@ -0,0 +1,47 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "baseUrl": ".",
+    "moduleResolution": "node",
+    "paths": {
+      "@/*": ["../../../*"],
+      "@/core/*": ["../../../core/*"],
+      "@/contents/*": ["../../../contents/*"],
+      "~/*": ["./*"]
+    }
+  },
+  "watchOptions": {
+    "watchFile": "useFsEvents",
+    "watchDirectory": "useFsEvents",
+    "fallbackPolling": "dynamicPriority",
+    "synchronousWatchDirectory": false,
+    "excludeDirectories": [
+      "**/node_modules",
+      "**/.next",
+      "**/dist",
+      "**/build",
+      "**/.turbo",
+      "**/coverage",
+      "**/.git"
+    ]
+  },
+  "include": [
+    "**/*.ts",
+    "**/*.tsx",
+    "plugin.config.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    ".next",
+    "dist",
+    "build",
+    ".turbo",
+    "coverage",
+    ".git",
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/__tests__/**",
+    "**/tsconfig.tsbuildinfo"
+  ]
+}

package/types/social.types.ts

@@ -0,0 +1,171 @@
+/**
+ * Social Media Publisher - TypeScript Types
+ */
+
+// ============================================
+// PLATFORM TYPES
+// ============================================
+
+export type SocialPlatform = 'instagram_business' | 'facebook_page'
+
+export type FacebookScope =
+  | 'email'
+  | 'public_profile'
+  | 'pages_show_list'
+  | 'pages_manage_posts'
+  | 'pages_read_engagement'
+  | 'read_insights'
+
+export type InstagramScope =
+  | 'instagram_business_basic'
+  | 'instagram_business_content_publish'
+  | 'instagram_manage_insights'
+
+export type OAuthScope = FacebookScope | InstagramScope
+
+// ============================================
+// ACCOUNT TYPES
+// ============================================
+
+export interface SocialAccount {
+  id: string
+  userId: string
+  platform: SocialPlatform
+  platformAccountId: string
+  username: string
+  accessToken: string // Encrypted
+  tokenExpiresAt: Date
+  permissions: OAuthScope[]
+  accountMetadata: SocialAccountMetadata
+  isActive: boolean
+  createdAt: Date
+  updatedAt: Date
+}
+
+export interface SocialAccountMetadata {
+  profilePictureUrl?: string
+  followersCount?: number
+  postsCount?: number
+  lastSyncAt?: string
+  additionalData?: Record<string, unknown>
+}
+
+// ============================================
+// OAUTH TYPES
+// ============================================
+
+export interface OAuthCallbackParams {
+  code: string
+  state: string
+  error?: string
+  error_description?: string
+}
+
+export interface OAuthTokenResponse {
+  access_token: string
+  token_type: string
+  expires_in: number
+  refresh_token?: string
+  scope?: string
+}
+
+export interface FacebookPageInfo {
+  id: string
+  name: string
+  category: string
+  access_token: string
+  tasks: string[]
+}
+
+export interface InstagramBusinessAccount {
+  id: string
+  username: string
+  profile_picture_url?: string
+  followers_count?: number
+  follows_count?: number
+  media_count?: number
+}
+
+// ============================================
+// PUBLISHING TYPES
+// ============================================
+
+export interface PublishRequest {
+  accountId: string
+  content: PublishContent
+}
+
+export interface PublishContent {
+  // Common fields
+  caption?: string
+
+  // Media
+  imageUrl?: string
+  videoUrl?: string
+
+  // Scheduling
+  scheduledAt?: Date
+
+  // Platform-specific
+  platformOptions?: Record<string, unknown>
+}
+
+export interface PublishResult {
+  success: boolean
+  platform: SocialPlatform
+  postId?: string
+  postUrl?: string
+  error?: string
+}
+
+// ============================================
+// AUDIT LOG TYPES
+// ============================================
+
+export type AuditAction =
+  | 'account_connected'
+  | 'account_disconnected'
+  | 'post_published'
+  | 'post_failed'
+  | 'token_refreshed'
+  | 'token_refresh_failed'
+
+export interface AuditLog {
+  id: string
+  userId: string
+  accountId?: string
+  action: AuditAction
+  details: AuditLogDetails
+  ipAddress?: string
+  userAgent?: string
+  createdAt: Date
+}
+
+export interface AuditLogDetails {
+  platform?: SocialPlatform
+  success: boolean
+  errorMessage?: string
+  metadata?: Record<string, unknown>
+}
+
+// ============================================
+// API RESPONSE TYPES
+// ============================================
+
+export interface ConnectAccountResponse {
+  success: boolean
+  account?: SocialAccount
+  error?: string
+}
+
+export interface DisconnectAccountResponse {
+  success: boolean
+  accountId: string
+  message?: string
+}
+
+export interface GetAccountsResponse {
+  success: boolean
+  accounts: SocialAccount[]
+  total: number
+}