# 🤖 VG Products — Integration & Features Documentation

Welcome to the official documentation for **VG Products**. This document provides an in-depth explanation of all integration features, architectural components, and API capabilities currently implemented in the platform.

---

## 📑 Table of Contents
1. [Platform Overview](#-platform-overview)
2. [User Authentication & Security](#-user-authentication--security)
3. [Social Media Connectivity (Meta/Instagram)](#-social-media-connectivity-metainstagram)
4. [Content & Engagement Management](#-content--engagement-management)
5. [AI-Powered Automation Suite](#-ai-powered-automation-suite)
6. [Payment & Subscription Infrastructure](#-payment--subscription-infrastructure)
7. [API Reference List](#-api-reference-list)

---

## 🌟 Platform Overview
VG Products is an all-in-one social media management and automation platform designed to help businesses manage their Instagram interaction through AI-driven insights and automated engagement. It bridges the gap between manual management and pure automation by providing a suite of tools for content monitoring and automated response systems.

---

## 🔐 User Authentication & Security

### 🔹 Local Authentication
- **JWT Implementation**: Secure token-based authentication using `jsonwebtoken`.
- **Encryption**: Password hashing via `bcrypt` for secure user data storage.
- **Session Management**: Configurable JWT expiration (default 30 days).

### 🔹 Google OAuth Integration
- **One-Tap Login**: Seamless authentication via Google using `passport-google-oauth20`.
- **Auto-Provisioning**: Automatic user record creation upon successful third-party authentication.

---

## 📱 Social Media Connectivity (Meta/Instagram)

### 🔹 Facebook Login & Instagram Graph API
VG Products uses the **Instagram Graph API** to interact with professional accounts.
- **Short-Lived to Long-Lived Token Exchange**: Automatically upgrades user access tokens to 60-day "Long-Lived" tokens for persistent connectivity.
- **Granular Permissions**: Requests only necessary scopes (`instagram_basic`, `instagram_manage_comments`, `pages_show_list`, etc.).

### 🔹 Channel & Account Management
- **Page Listing**: Fetches all Facebook Pages owned by the user.
- **IG Account Linking**: Identifies which Instagram Business accounts are linked to specific Facebook Pages.
- **Connection Persistence**: Securely stores page-level tokens for background automation tasks.

---

## 💬 Content & Engagement Management

### 🔹 Media Monitoring
- **Post Retrieval**: Fetches recent Instagram media (images, videos, reels) with metadata like captions, timestamps, and permalinks.
- **Detailed View**: Access specific media metrics and full-resolution content.

### 🔹 Comprehensive Comment System
- **Real-time Interaction**: Fetch comments for any Instagram post.
- **Standard Actions**: Support for replying to comments, deleting unwanted content, and toggling visibility (Hide/Unhide).
- **Engagement Tracking**: View comment counts and commenter details.

---

## 🤖 AI-Powered Automation Suite

The core value proposition of VG Products is its intelligent automation engine.

### 🔹 Smart Auto-Reply Engine
- **Context-Aware Processing**: Analyzes the post caption, the user's account bio, and the comment text to generate a relevant reply.
- **AI Generation**: Leverages advanced LLM logic to craft human-like responses that align with the brand's voice.
- **Intelligent Filtering**:
    - **Self-Exclusion**: Automatically skips comments made by the account itself.
    - **Time Window**: Defaults to processing comments within the last 24 hours to ensure relevance.
    - **Duplicate Prevention**: Tracks `repliedComments` to avoid double-responding to the same user.

### 🔹 Automation Governance
- **Rate Limiting**: Built-in delays between replies to comply with Meta's rate limits and prevent "bot-like" behavior flags.
- **History Management**: Users can view automation summaries (Processed vs. Replied) and clear their reply history.

---

## 💳 Payment & Subscription Infrastructure

Powered by **Stripe**, VG Products features a robust monetization layer.

### 🔹 Tiered Subscription Plans
- **Basic, Standard, & Premium**: Flexible pricing tiers available in both **Monthly** and **Yearly** billing cycles.
- **Flexible Upgrades**: Managed through Stripe Checkout sessions.

### 🔹 Free Trial Activation
- **7-Day Trial**: One-time activation for new users to explore premium features with zero upfront cost.
- **Automated Expiry**: Features are automatically restricted once the trial period ends.

### 🔹 Billing Management
- **Self-Service Portal**: Direct integration with the **Stripe Billing Portal**, allowing users to manage payment methods (last 4 digits overview), download invoices, and cancel subscriptions without contacting support.
- **Webhook Synchronization**: Real-time updates for subscription status through Stripe Webhooks (Payment Succeeded, Failed, Cancelled).

---

## 🚀 API Reference List

### Authentication
- `GET /api/auth/status`: Check connectivity status.
- `GET /api/auth/login`: Initiate Facebook OAuth.
- `POST /api/auth/disconnect`: Revoke social connections.

### Social Meta-Data
- `GET /api/social/channels`: List available Facebook Pages.
- `POST /api/social/connect`: Link a specific Instagram Business account.
- `GET /api/social/media`: Fetch Instagram posts.

### Comments & Automation
- `POST /api/social/comments/:id/reply`: Manual reply.
- `DELETE /api/social/comments/:id`: Remove comment.
- `POST /api/social/automation/auto-reply`: Start the AI automation cycle.
- `GET /api/social/automation/replied-comments`: View reply history.

### Payments
- `POST /api/payment/create-checkout-session`: Start a subscription buy.
- `POST /api/payment/activate-trial`: Start 7-day trial.
- `POST /api/payment/create-portal-session`: Open Stripe Billing Portal.

---
*Documentation Version: 1.0.0*  
*Last Updated: 2026-02-20*