@budytalk/activity-server

A simplified content management server for social media features - handles posts, likes, comments, retweets, bookmarks, and timelines. Database initialization is handled automatically - just import and use!

🌟 Features

Core Content Management

• Posts: Text, image, video, and poll posts with rich metadata
• Reactions: Like, love, laugh, wow, sad, angry reactions with unlike functionality
• Comments: Nested comments with mentions, replies, and deletion
• Retweets: Simple retweets and retweets with comments, plus unretweet functionality
• Bookmarks: Save posts to organized collections with notes
• Timeline System: Personalized timelines based on following relationships
• Trending Algorithm: Discover popular content based on engagement
• Real-time Updates: WebSocket support for live updates

Key Benefits

• No Database Setup: Automatically connects to Neon PostgreSQL - no configuration needed!
• No User Management: Focuses only on content, works with your existing user system
• Simple Integration: Easy-to-use REST API and JavaScript SDK
• Real-time: WebSocket support for instant updates
• Scalable: Built-in PostgreSQL support for production use
• Lightweight: Minimal dependencies, focused functionality
• Production Ready: Built with TypeScript, comprehensive error handling

📦 Installation

npm install @budytalk/activity-server

🚀 Quick Start

Instant Setup (No Database Configuration!)

const { BudyTalkContent } = require('@budytalk/activity-server');

async function main() {
  // Create instance - database connection is built-in!
  const budytalk = new BudyTalkContent();
  
  // Start server (automatically creates all tables)
  await budytalk.start();
  
  console.log('✅ Server running with PostgreSQL!');
  
  // Start using immediately - no setup required!
  const user = await budytalk.syncUserAccount({
    userId: 'user_123',
    username: 'alice',
    displayName: 'Alice Johnson'
  });
  
  const post = await budytalk.createPost({
    userId: user.userId,
    content: 'Hello world! 🎉',
    postType: 'text'
  });
  
  console.log('🎉 Ready to use!');
}

main().catch(console.error);

Custom Database (Optional)

const { BudyTalkContent } = require('@budytalk/activity-server');

// Only if you want to use your own database
const budytalk = new BudyTalkContent({
  database: {
    type: 'postgres',
    url: 'your-database-url'
  }
});

await budytalk.start(); // Still handles table creation automatically

📱 Complete Example

const { BudyTalkContent } = require('@budytalk/activity-server');

async function socialMediaExample() {
  // Initialize with built-in database
  const budytalk = new BudyTalkContent();
  await budytalk.start();
  
  // Sync user accounts from your main system
  const alice = await budytalk.syncUserAccount({
    userId: 'user_123',
    username: 'alice',
    displayName: 'Alice Johnson',
    avatar: 'https://example.com/alice.jpg'
  });
  
  const bob = await budytalk.syncUserAccount({
    userId: 'user_456',
    username: 'bob',
    displayName: 'Bob Smith'
  });
  
  // Bob follows Alice
  await budytalk.followUser(bob.userId, alice.userId);
  
  // Alice creates posts
  const textPost = await budytalk.createPost({
    userId: alice.userId,
    content: 'Hello everyone! 🎉',
    postType: 'text',
    hashtags: ['#hello', '#social'],
    mentions: ['@bob']
  });
  
  const pollPost = await budytalk.createPost({
    userId: alice.userId,
    content: 'What\'s your favorite feature?',
    postType: 'poll',
    poll: {
      question: 'What\'s your favorite feature?',
      options: [
        { text: 'Timeline' },
        { text: 'Reactions' },
        { text: 'Comments' },
        { text: 'Polls' }
      ],
      settings: {
        allowMultipleChoices: false,
        showResults: 'after_vote',
        duration: 24
      }
    }
  });
  
  // Bob interacts with posts
  await budytalk.likePost(bob.userId, textPost.id);
  
  await budytalk.commentOnPost({
    userId: bob.userId,
    postId: textPost.id,
    content: 'Great post! 👏',
    mentions: ['@alice']
  });
  
  // Vote on poll
  if (pollPost.poll) {
    const timelineOption = pollPost.poll.options.find(opt => opt.text === 'Timeline');
    await budytalk.voteOnPoll({
      userId: bob.userId,
      pollId: pollPost.poll.id,
      optionIds: [timelineOption.id]
    });
  }
  
  // Bookmark post
  await budytalk.bookmarkPost({
    userId: bob.userId,
    postId: textPost.id,
    collectionName: 'Favorites',
    notes: 'Great inspiration!'
  });
  
  // Get Bob's timeline (posts from followed users)
  const timeline = await budytalk.getTimeline(bob.userId);
  console.log(`Bob's timeline: ${timeline.length} posts`);
  
  // Get trending posts
  const trending = await budytalk.getTrendingPosts(10, 24);
  console.log(`Trending: ${trending.length} posts`);
}

socialMediaExample().catch(console.error);

🌐 REST API

The server automatically provides a complete REST API:

Posts

# Create post
POST /api/content/posts
{
  "userId": "user_123",
  "content": "Hello world!",
  "postType": "text",
  "hashtags": ["#hello"]
}

# Create poll
POST /api/content/posts
{
  "userId": "user_123",
  "content": "What's your favorite?",
  "postType": "poll",
  "poll": {
    "question": "What's your favorite?",
    "options": [{"text": "Option 1"}, {"text": "Option 2"}]
  }
}

Reactions

# Like post
POST /api/content/reactions
{
  "userId": "user_456",
  "type": "like",
  "postId": "post_123"
}

# Unlike (remove reaction)
DELETE /api/content/reactions/{reactionId}
{
  "userId": "user_456"
}

Comments

# Add comment
POST /api/content/comments
{
  "userId": "user_456",
  "postId": "post_123",
  "content": "Great post!",
  "mentions": ["@alice"]
}

# Delete comment
DELETE /api/content/comments/{commentId}
{
  "userId": "user_456"
}

Bookmarks

# Bookmark post
POST /api/content/bookmarks
{
  "userId": "user_456",
  "postId": "post_123",
  "collectionName": "Favorites",
  "notes": "Great inspiration"
}

# Get bookmarks
GET /api/content/users/{userId}/bookmarks?collection=Favorites

Timelines

# Get user's timeline (from followed users)
GET /api/content/users/{userId}/timeline?limit=20

# Get user's own posts
GET /api/content/users/{userId}/feed?limit=20

# Get trending posts
GET /api/content/trending?limit=20&timeframe=24

🔌 Real-time WebSocket

const io = require('socket.io-client');

const socket = io('http://localhost:3000', {
  query: { userId: 'user_123' }
});

// Listen for new posts
socket.on('new-post', (post) => {
  console.log('New post:', post);
});

// Listen for reactions
socket.on('new-reaction', (reaction) => {
  console.log('New reaction:', reaction);
});

// Listen for comments
socket.on('new-comment', (comment) => {
  console.log('New comment:', comment);
});

// Join hashtag topics
socket.emit('join-topic', 'javascript');
socket.on('new-post-in-topic', (data) => {
  console.log(`New #${data.topic} post:`, data.post);
});

⚙️ Configuration (Optional)

const budytalk = new BudyTalkContent({
  port: 3000,
  database: {
    type: 'postgres', // Built-in Neon PostgreSQL by default
    url: 'your-custom-database-url' // Optional
  },
  websocket: {
    enabled: true,
    cors: {
      origin: ['http://localhost:3000'],
      credentials: true
    }
  },
  cors: {
    origin: ['http://localhost:3000'],
    credentials: true
  },
  logging: {
    level: 'info',
    format: 'simple'
  }
});

🧪 Testing

Quick Test

# Start the server
node -e "
const { BudyTalkContent } = require('@budytalk/activity-server');
const budytalk = new BudyTalkContent();
budytalk.start().then(() => console.log('✅ Server running!'));
"

# Test the API
curl -X POST http://localhost:3000/api/content/users \
  -H "Content-Type: application/json" \
  -d '{"userId":"test","username":"test","displayName":"Test User"}'

Run Examples

# Test basic functionality
npm run test:simple

# Test with built-in PostgreSQL
npm run test:postgres

# Test API endpoints
npm run test:api

# Test bookmark functionality
npm run test:bookmarks

🏗️ Integration with Your App

1. Sync User Accounts

// When users register in your main system
async function onUserRegistered(user) {
  await budytalk.syncUserAccount({
    userId: user.id,
    username: user.username,
    displayName: user.displayName,
    avatar: user.avatar
  });
}

2. Frontend Integration

// React example
import { useState, useEffect } from 'react';
import io from 'socket.io-client';

function Timeline({ userId }) {
  const [posts, setPosts] = useState([]);
  const [socket, setSocket] = useState(null);

  useEffect(() => {
    // Connect to WebSocket
    const newSocket = io('http://localhost:3000', {
      query: { userId }
    });

    newSocket.on('new-post', (post) => {
      setPosts(prev => [post, ...prev]);
    });

    newSocket.on('new-reaction', (reaction) => {
      setPosts(prev => prev.map(post => 
        post.id === reaction.postId 
          ? { ...post, reactionCounts: { ...post.reactionCounts, [reaction.type]: (post.reactionCounts[reaction.type] || 0) + 1 } }
          : post
      ));
    });

    setSocket(newSocket);

    // Load initial timeline
    fetch(`/api/content/users/${userId}/timeline`)
      .then(res => res.json())
      .then(setPosts);

    return () => newSocket.close();
  }, [userId]);

  const handleLike = async (postId) => {
    await fetch('/api/content/reactions', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        userId,
        type: 'like',
        postId
      })
    });
  };

  return (
    <div>
      {posts.map(post => (
        <PostComponent 
          key={post.id} 
          post={post} 
          onLike={() => handleLike(post.id)}
        />
      ))}
    </div>
  );
}

📊 Database Schema

The package automatically creates these tables in PostgreSQL:

• user_accounts: Synced user information
• posts: All posts with metadata
• reactions: Likes, loves, etc.
• comments: Comments and replies
• bookmarks: User bookmarks with collections
• polls: Poll questions and votes
• follows: Following relationships
• timeline_entries: Personalized timelines

🚀 Production Deployment

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
EXPOSE 3000
CMD ["node", "initialize-neon.js"]

Environment Variables (Optional)

PORT=3000
LOG_LEVEL=info
CORS_ORIGIN=https://yourapp.com
WEBSOCKET_ENABLED=true

🎯 Why Choose BudyTalkContent?

✅ Zero Setup: No database configuration required - works out of the box
✅ Focused: Only handles content, not user management
✅ Simple: Easy REST API and JavaScript SDK
✅ Real-time: WebSocket support for live updates
✅ Scalable: Built-in PostgreSQL for production use
✅ Feature-rich: Posts, reactions, comments, retweets, bookmarks, polls
✅ Production-ready: TypeScript, error handling, logging
✅ Flexible: Works with any user management system
✅ Complete CRUD: Full create, read, update, delete operations
✅ Automatic: Database tables created automatically

Perfect for adding social features to existing applications without any database setup complexity!

📄 License

MIT License - see LICENSE file for details

Ready to add powerful social features to your app? Get started with BudyTalkContent today! 🚀

No Database Setup Required!

Just install, import, and start using - the database connection and table creation is handled automatically by the package. Perfect for rapid prototyping and production use!