🤖 Agentic Social Media

A comprehensive TypeScript library for automated social media management, AI-powered content generation, scheduling, analytics, and multi-platform integration.

🌟 Features

🤖 AI-Powered Content Generation

• Smart Content Creation: Generate platform-optimized content using AI
• Tone Customization: Professional, casual, humorous, or inspirational tones
• Hashtag Suggestions: AI-recommended hashtags for maximum reach
• Multi-Language Support: Content generation in multiple languages

📅 Content Calendar & Scheduling

• Visual Calendar: View all scheduled posts across platforms
• Smart Scheduling: AI-suggested optimal posting times
• Bulk Scheduling: Schedule multiple posts at once
• Content Gaps: Identify and fill content gaps automatically
• CSV Export: Export calendars for external tools

📊 Advanced Analytics

• Real-time Metrics: Track impressions, reach, engagement, and more
• Cross-Platform Analytics: Unified dashboard for all platforms
• Audience Insights: Deep analytics about your followers
• Growth Tracking: Monitor follower growth and engagement trends
• Performance Reports: Generate detailed PDF/CSV reports

🔗 Multi-Platform Support

• Twitter/X: Tweets, threads, and engagement tracking
• LinkedIn: Professional posts and company updates
• Instagram: Photos, stories, and reels
• Facebook: Posts, events, and community management
• TikTok: Short-form video content

💬 Social Listening & Monitoring

• Mention Tracking: Monitor brand mentions across platforms
• Sentiment Analysis: AI-powered sentiment classification
• Keyword Monitoring: Track specific keywords and hashtags
• Competitor Analysis: Monitor competitor activity

🎨 Media Management

• Image Upload: Upload and optimize images for each platform
• Video Processing: Auto-resize and format videos
• Asset Library: Organize and reuse media assets
• CDN Integration: Fast media delivery worldwide

🚀 Quick Start

Installation

npm install agentic-social-media

Basic Usage

import { SocialMediaClient } from 'agentic-social-media'

// Initialize client
const client = new SocialMediaClient()

// Generate AI-powered content
const content = await client.generateSocialContent({
  topic: 'artificial intelligence',
  platform: { id: 'twitter', name: 'Twitter', connected: true },
  tone: 'professional',
  length: 'short',
  includeHashtags: true,
  includeEmojis: true
})

console.log(content)
// Output: "Excited to share insights about artificial intelligence. Stay tuned for more updates! #artificial #intelligence ✨"

Scheduling Posts

// Schedule a post
const post = await client.schedulePost({
  content: 'Just launched our new AI-powered feature! 🚀',
  platform: { id: 'twitter', name: 'Twitter', connected: true },
  type: 'text',
  scheduledFor: new Date('2024-01-15T10:00:00Z'),
  hashtags: ['#AI', '#Technology', '#Innovation'],
  mentions: ['@yourcompany']
})

console.log(`Post scheduled: ${post.id}`)

Content Calendar

// Get content calendar for next 30 days
const calendar = await client.getContentCalendar(
  new Date(),
  new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
  ['twitter', 'linkedin', 'instagram']
)

console.log(`Found ${calendar.posts.length} scheduled posts`)

Analytics

// Get analytics for a platform
const analytics = await client.getSocialAnalytics(
  'twitter',
  new Date('2024-01-01'),
  new Date('2024-01-31')
)

console.log(`Engagement Rate: ${analytics.engagementRate}`)
console.log(`Total Impressions: ${analytics.metrics.impressions}`)

📋 Configuration

Environment Variables

# Optional: Configure API keys for enhanced features
TWITTER_API_KEY=your_twitter_api_key
TWITTER_API_SECRET=your_twitter_api_secret
TWITTER_ACCESS_TOKEN=your_twitter_access_token
TWITTER_ACCESS_TOKEN_SECRET=your_twitter_access_token_secret

LINKEDIN_CLIENT_ID=your_linkedin_client_id
LINKEDIN_CLIENT_SECRET=your_linkedin_client_secret

FACEBOOK_APP_ID=your_facebook_app_id
FACEBOOK_APP_SECRET=your_facebook_app_secret

INSTAGRAM_ACCESS_TOKEN=your_instagram_access_token
TIKTOK_ACCESS_TOKEN=your_tiktok_access_token

Platform Configuration

// Connect platforms with credentials
client.connectPlatform('twitter', {
  apiKey: process.env.TWITTER_API_KEY,
  apiSecret: process.env.TWITTER_API_SECRET,
  accessToken: process.env.TWITTER_ACCESS_TOKEN,
  accessTokenSecret: process.env.TWITTER_ACCESS_TOKEN_SECRET
})

client.connectPlatform('linkedin', {
  clientId: process.env.LINKEDIN_CLIENT_ID,
  clientSecret: process.env.LINKEDIN_CLIENT_SECRET
})

🎯 Advanced Usage

Content Generation with Custom Parameters

const content = await client.generateSocialContent({
  topic: 'sustainable technology',
  platform: { id: 'linkedin', name: 'LinkedIn', connected: true },
  tone: 'professional',
  length: 'long',
  includeHashtags: true,
  includeEmojis: false,
  targetAudience: 'business professionals',
  brandVoice: 'innovative and forward-thinking'
})

Social Listening

// Monitor mentions and keywords
const mentions = await client.monitorSocialMentions(
  ['twitter', 'linkedin', 'instagram'],
  ['yourbrand', 'competitor1', 'industrytrend'],
  true // Include sentiment analysis
)

mentions.forEach(mention => {
  console.log(`${mention.platform}: ${mention.content} (${mention.sentiment})`)
})

Content Calendar Management

import { ContentCalendarManager } from 'agentic-social-media'

const calendarManager = new ContentCalendarManager()

// Add posts to calendar
calendarManager.addPost(post1)
calendarManager.addPost(post2)

// Get upcoming posts
const upcoming = calendarManager.getUpcomingPosts(7)
console.log(`${upcoming.length} posts scheduled for next 7 days`)

// Find content gaps
const gaps = calendarManager.getContentGaps('twitter', startDate, endDate)
console.log(`Content gaps found: ${gaps.length}`)

// Get optimal posting times
const bestTimes = calendarManager.getBestTimeToPost('twitter')
console.log(`Best times to post: ${bestTimes.join(', ')}`)

Analytics and Reporting

import { AnalyticsManager } from 'agentic-social-media'

const analyticsManager = new AnalyticsManager()

// Generate comprehensive report
const report = analyticsManager.generateReport(analytics)
console.log(report)

// Export analytics to CSV
const csvData = analyticsManager.exportAnalyticsToCSV(analytics)
fs.writeFileSync('analytics-report.csv', csvData)

// Get audience insights
const insights = analyticsManager.getAudienceInsights(analytics)
console.log(`Audience Quality: ${insights.audienceQuality}`)
console.log(`Best Content Type: ${insights.contentPerformance.bestContentType}`)

🧪 Examples

Check out the /examples directory for complete working examples:

• demo.js - Complete walkthrough of all features
• content-calendar.js - Content calendar management
• analytics.js - Analytics and reporting

Running Examples

# Run the main demo
npm run demo

# Run content calendar demo
npm run demo:content

# Run analytics demo
npm run demo:analytics

🔧 API Reference

SocialMediaClient

generateSocialContent(options: ContentGenerationOptions): Promise<string>

Generate AI-powered social media content.

schedulePost(options: SchedulePostOptions): Promise<Post>

Schedule a post for future publication.

getContentCalendar(startDate: Date, endDate: Date, platforms?: string[]): Promise<ContentCalendar>

Get all scheduled posts within a date range.

getSocialAnalytics(platform: string, startDate: Date, endDate: Date): Promise<Analytics>

Get analytics data for a specific platform and date range.

monitorSocialMentions(platforms: string[], keywords: string[], includeSentiment?: boolean): Promise<SocialMention[]>

Monitor social mentions across platforms.

uploadMediaContent(options: MediaUploadOptions): Promise<MediaUploadResult>

Upload media content for social posts.

ContentCalendarManager

getUpcomingPosts(days?: number): Post[]

Get posts scheduled for the next N days.

getBestTimeToPost(platform: string): string[]

Get optimal posting times for a platform.

getContentGaps(platform: string, startDate: Date, endDate: Date): Date[]

Find days without scheduled posts.

AnalyticsManager

generateReport(analytics: Analytics): string

Generate a comprehensive analytics report.

getAudienceInsights(analytics: Analytics): AudienceInsights

Get detailed audience insights and recommendations.

exportAnalyticsToCSV(analytics: Analytics): string

Export analytics data to CSV format.

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run specific test file
npm test -- --testPathPattern=social-media-client.test.ts

📦 Build

# Build the project
npm run build

# Build in watch mode
npm run dev

# Clean build artifacts
npm run clean

🚀 Deployment

NPM Package

# Login to npm
npm login

# Publish the package
npm publish

GitHub Releases

1. Create a new release on GitHub
2. Tag the version (e.g., v1.0.0)
3. Add release notes
4. Publish the release

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/CakekritsananXi/agentic-social-media.git
cd agentic-social-media

# Install dependencies
npm install

# Run tests
npm test

# Build the project
npm run build

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with TypeScript for type safety
• Uses Zod for runtime validation
• Inspired by modern social media management needs
• Designed for scalability and extensibility

📞 Support

• 📧 Email: your.email@example.com
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: Wiki

🔗 Links

• 🏠 Homepage
• 📦 NPM Package
• 📚 Documentation
• 🐦 Twitter
• 💼 LinkedIn

---

Made with ❤️ by CakekritsananXi