@toolkit-p2p/feed

@toolkit-p2p/feed

Social feed and content aggregation for toolkit-p2p with CRDT-based post management and Web of Trust filtering.

Features

• Post Management: Create, edit, delete posts with CRDT consistency
• Media Support: Attachments with content-addressed storage
• Reactions: Add emoji reactions to posts
• Threading: Reply to posts and build conversation threads
• Timeline Aggregation: Multiple feed types (following, global, recommended, profile, tag)
• Social Graph Filtering: Filter content based on follows, trust scores, and degrees of separation
• Content Moderation: User-defined rules for filtering and content warnings
• Search: Full-text search across posts and tags

Installation

pnpm add @toolkit-p2p/feed

Usage

Basic Setup

import { PostManager, Feed } from '@toolkit-p2p/feed';
import { BulletinBoard } from '@toolkit-p2p/bulletin';
import { SocialGraph } from '@toolkit-p2p/social';

// Initialize dependencies
const bulletin = new BulletinBoard(/* ... */);
const socialGraph = new SocialGraph(/* ... */);

// Create post manager and feed
const postManager = new PostManager(bulletin, 'my-peer-id');
const feed = new Feed(postManager, socialGraph);

Creating Posts

// Simple post
const post = await postManager.createPost('Hello, decentralized world!');

// Post with media
const post = await postManager.createPost('Check out this image', {
  media: [{
    cid: 'bafybeig...',
    type: MediaType.IMAGE,
    mimeType: 'image/jpeg',
    size: 12345,
  }],
  tags: ['photography', 'nature'],
});

// Reply to a post
const reply = await postManager.createPost('Great post!', {
  replyTo: post.id,
});

Reading Feeds

// Get feed from followed peers
const followingFeed = await feed.getFollowingFeed({ limit: 20 });

// Get global feed
const globalFeed = await feed.getGlobalFeed({ limit: 50 });

// Get recommended feed based on Web of Trust
const recommended = await feed.getRecommendedFeed({
  limit: 20,
  minTrustScore: 0.5,
  maxDegrees: 2,
});

// Get posts by specific author
const profileFeed = await feed.getProfileFeed('peer-id', { limit: 10 });

// Get posts with a tag
const tagFeed = await feed.getTagFeed('javascript', { limit: 15 });

Threads

// Get full thread with replies
const thread = await feed.getThread(rootPostId);

console.log(thread.root); // Root post
console.log(thread.replies); // Map of parent ID -> replies
console.log(thread.totalPosts); // Total posts in thread

Reactions

// Add reaction
await postManager.addReaction(postId, '👍');

// Remove reaction
await postManager.removeReaction(postId);

// Get all reactions
const reactions = await postManager.getReactions(postId);

Content Moderation

// Add keyword filter
feed.addModerationRule({
  id: 'spam-filter',
  type: 'keyword',
  pattern: /spam|advertisement/i,
  action: ModerationAction.HIDE,
  reason: 'Spam detected',
});

// Filter by trust score
feed.addModerationRule({
  id: 'low-trust',
  type: 'trust',
  minTrust: 0.3,
  action: ModerationAction.WARN,
  reason: 'Low trust score',
});

// Custom filter
feed.addModerationRule({
  id: 'custom',
  type: 'custom',
  filter: (post) => post.content.length > 5000,
  action: ModerationAction.WARN,
  reason: 'Very long post',
});

Search

// Search posts
const results = await feed.searchPosts('decentralization', {
  followedOnly: true,
  limit: 10,
});

Feed Types

• Following Feed: Posts from peers you follow
• Global Feed: Posts from all peers in the network
• Recommended Feed: Posts filtered by Web of Trust scores
• Profile Feed: Posts from a specific author
• Tag Feed: Posts with a specific hashtag
• Thread: All replies in a conversation

Social Graph Integration

The feed integrates with @toolkit-p2p/social to filter content based on:

• Follow Relationships: Only show posts from followed peers
• Trust Scores: Filter by Web of Trust scores (0-1)
• Degrees of Separation: Include peers within N degrees
• Blocked Peers: Automatically exclude blocked peers

Architecture

┌─────────────────┐
│      Feed       │  Timeline aggregation & filtering
└────────┬────────┘
         │
    ┌────┴────┬──────────┐
    │         │          │
┌───▼────┐ ┌──▼──────┐ ┌▼──────────┐
│  Post  │ │ Social  │ │ Bulletin  │
│Manager │ │  Graph  │ │   Board   │
└────────┘ └─────────┘ └───────────┘

• PostManager: CRDT-based post and reaction management
• Feed: Timeline aggregation with social filtering
• BulletinBoard: Distributed message storage (@toolkit-p2p/bulletin)
• SocialGraph: Follow/trust relationships (@toolkit-p2p/social)

License

MIT