n8n-nodes-bluesky-enhanced

This is a fork of @muench-dev/n8n-nodes-bluesky with enhanced functionality for the Bluesky social network.

Key Features

• User Management: Follow/follower operations with pagination, profile management, muting/blocking
• Advanced Posting: Create posts with media attachments (images/video), replies, quotes, and website cards
• Media Support: Image uploads (fully functional) and video uploads (limited - see Video Uploads section)
• Feed Operations: Retrieve author feeds with filtering, timelines, and thread contexts
• Search Capabilities: Search users and posts with filtering options
• Analytics & Notifications: Enhanced notification management with filtering and interaction tracking
• Thread Management: Reply to posts, quote posts, and mute conversation threads

Installation

npm install n8n-nodes-bluesky-enhanced

In n8n community edition, you can install the nodes in the settings page by searching for n8n-nodes-bluesky-enhanced.

Supported Operations

User Operations

• Block User - Block users to prevent interaction
• Get Profile - Get detailed profile information for any user
• List All Followers - Fetch all followers with automatic pagination
• List All Follows - Fetch all follows with automatic pagination
• Mute User - Mute users to hide their content from feeds
• Un-mute User - Remove mute status from users

Post Operations

• Create Post - Create text posts with optional media attachments (images/video) or website cards
• Like/Unlike - Like and unlike posts
• Repost/Delete Repost - Repost content and manage reposts
• Reply to Post - Reply to existing posts with proper thread structure
• Quote Post - Quote existing posts in new posts
• Delete Post - Remove your own posts

Media Support:

• Images: Fully functional (up to 4 images per post)
• Video: Limited functionality (uploads succeed but videos don't display - see Video Uploads section)

Feed Operations

• Get Author Feed - Retrieve posts from specific users with filtering options
• Get Timeline - Get your personalized timeline
• Get Post Thread - Retrieve full conversation threads with context

Search Operations

• Search Users - Find users by keywords with configurable limits
• Search Posts - Search posts with optional author filtering

Analytics Operations

• List Notifications - Get notifications with enhanced filtering options
• Get Unread Count - Monitor unread notification counts
• Update Seen Notifications - Mark notifications as read
• Get Post Interactions - Analyze post engagement (likes, reposts, replies)

List Operations

• Add User to List - Add users to custom lists for categorization
• Create List - Create new custom lists with descriptions and purposes
• Delete List - Remove lists that are no longer needed
• Get List Feed - Retrieve posts from specific lists with pagination
• Get Lists - Get all lists for a user with automatic pagination
• Remove User From List - Remove users from existing lists
• Update List - Modify list names, descriptions, and purposes

Graph Operations

• Mute Thread - Mute conversation threads to stop notifications

Configuration Examples

Enhanced Notification Management

The Analytics resource provides comprehensive notification management with advanced filtering:

List Notifications

• Limit: Max number of results to return
• Unread Only: Whether to return only unread notifications (default: true)
• Mark Retrieved as Read: Whether to automatically mark retrieved notifications as read (default: true)

This enhanced operation includes automatic pagination and intelligent filtering - when "Unread Only" is enabled, it automatically handles pagination to find unread notifications across multiple API pages.

Get Post Interactions Analyze engagement metrics for any post:

• Post URI: AT URI of the post to analyze
• Interaction Types: Select likes, reposts, and/or replies
• Interaction Limit: Number of each interaction type to retrieve (1-100)

Returns structured data with individual interactions plus automatic analytics summaries.

Advanced Feed Filtering

Get Author Feed now supports content-type filtering:

• Posts with Replies: All posts including replies (default)
• Posts without Replies: Only top-level posts
• Posts with Media: Only posts with media attachments
• Posts and Author Threads: Posts and threads by the author
• Posts with Video: Only posts containing video

Filters are applied at the API level for optimal performance.

User Management with Pagination

List All Followers/Follows

• Handle: Bluesky handle (e.g., username.bsky.social)
• Max Results: Maximum number to fetch (default: 1000)
• Page Size: Results per API request (default: 100, max: 100)

Automatic pagination handles large follower/following lists efficiently.

List Management

Create List

• List Name: Display name for the list
• Purpose: Either "Curate List" for content curation or "Mod List" for moderation
• Description: Optional description explaining the list's purpose

Get Lists

• Actor: Handle or DID of the user whose lists to retrieve
• Limit: Maximum number of lists to return (1-100, default: 50)

Returns all lists created by the specified user with automatic pagination handling.

Get List Feed

• List URI: AT URI of the list to retrieve posts from
• Limit: Maximum number of posts to return (1-100, default: 50)

Retrieves posts from users who are members of the specified list.

Add/Remove Users

• List URI: AT URI of the target list
• User DID: Decentralized identifier of the user to add/remove
• List Item URI: (Remove only) AT URI of the specific list membership record

List operations support automatic pagination and handle large lists efficiently.

Media Posting

Create Post with Images

• Include Media: Enable media attachment mode
• Media Items: Collection of up to 4 images
  • Binary Property: Name of n8n binary property containing image data
  • Alt Text: Accessibility description for images

When media is included, website card options are automatically disabled.

Video Uploads

⚠️ Current Status: Limited Functionality

Video uploads are technically supported but have significant limitations due to Bluesky's infrastructure:

Create Post with Video

• Include Media: Enable media attachment mode and select video files
• Video Items: Single video file (up to 100MB)
  • Binary Property: Name of n8n binary property containing video data
  • Alt Text: Accessibility description for the video

Important Limitations (as of May 25, 2025):

• ✅ Video uploads succeed - Files upload without errors
• ❌ Videos don't display - Show "Video not found" on Bluesky platform
• ❌ No video processing - No thumbnails, playlists, or streaming support
• ❌ Server APIs not deployed - Bluesky's video processing pipeline inactive

Root Cause: Bluesky's video infrastructure requires server-side processing to generate streaming playlists and thumbnails. While the complete infrastructure exists in Bluesky's codebase, the video processing APIs are not yet deployed on their servers (all return XRPCNotSupported).

Recommendations:

• Monitor Bluesky announcements for video feature availability updates
• Test periodically as the feature could be activated without notice

Technical Details:

• Videos upload as binary blobs successfully
• Missing: playlist generation, thumbnail creation, proper embed structure
• Infrastructure ready: Complete video processing pipeline exists in Bluesky's code
• Timeline: Unknown - awaiting server-side deployment by Bluesky team

For detailed technical analysis, see VIDEO_STATUS_REPORT.md.

Use Cases

This enhanced Bluesky node is perfect for:

• Social Media Management: Automated posting, content scheduling, engagement tracking
• Community Building: Follower management, notification handling, interaction monitoring
• List Management: Organize users into custom lists for content curation and moderation purposes
• Content Curation: Create and manage curated lists of users for specialized feeds
• Moderation: Build and maintain moderation lists for content filtering and community management
• Content Analytics: Post performance tracking, engagement analysis, audience insights
• Brand Monitoring: Search functionality for mentions and relevant content
• Automated Responses: Reply and quote operations for customer service or engagement
• Data Collection: Comprehensive user and content data extraction with pagination
• Visual Content: Image posting (fully functional), video posting (limited until Bluesky enables video processing)

Changelog

See CHANGELOG.md for a detailed list of changes for each version.

Repository

This enhanced version is maintained at: https://github.com/brianmoney/n8n-nodes-bluesky

License

MIT

Acknowledgments

This project is based on @muench-dev/n8n-nodes-bluesky by Christian Münch.

Changelog

All notable changes to the n8n-nodes-bluesky-enhanced package will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

• List Operations: Complete list management functionality for organizing users and content
  • Add User to List: Add users to custom lists for categorization and curation
  • Create List: Create new custom lists with configurable names, descriptions, and purposes (curate list or mod list)
  • Delete List: Remove lists that are no longer needed with proper cleanup
  • Get List Feed: Retrieve posts from specific lists with automatic pagination support
  • Get Lists: Get all lists for a user with configurable limits and pagination
  • Remove User From List: Remove users from existing lists with proper validation
  • Update List: Modify existing list properties including names, descriptions, and purposes
  • Full AT Protocol integration using proper com.atproto.repo methods for record management
  • Automatic pagination handling for large lists and feeds
  • Comprehensive input validation and error handling
  • Support for both curate lists (content curation) and mod lists (moderation purposes)

Technical

• API Integration: Implemented proper AT Protocol methods for list operations
  • Uses com.atproto.repo.createRecord, putRecord, deleteRecord, and getRecord for list management
  • Uses app.bsky.graph.getLists and app.bsky.feed.getListFeed for data retrieval
  • Proper URI handling with @atproto/syntax for AT Protocol URIs
• Type Safety: Added comprehensive TypeScript support with proper type casting and validation
• Code Quality: Alphabetized operation options to meet ESLint requirements
• Test Infrastructure: Excluded test files from build process to prevent compilation errors

[1.4.0] - 2025-05-24

Added

• Enhanced Analytics Notifications: Major improvements to notification management in Analytics resource
  • Added unreadOnly boolean flag (defaults to true) for filtering unread notifications
  • Added markRetrievedAsRead boolean flag (defaults to true) for automatic read status updates
  • Implemented intelligent pagination that automatically handles multiple API pages when filtering for unread notifications
  • Added seenAt parameter support for updateSeenNotifications operation with timestamp control

Removed

• Redundant Notification Resource: Removed standalone "Notification" resource from UI to eliminate confusion
  • All notification functionality now consolidated under "Analytics" resource
  • Prevents duplicate functionality and improves user experience
  • Maintains backwards compatibility by preserving all notification operations under Analytics

Fixed

• Test Suite Completion: Achieved 100% test pass rate (57/57 tests passing)
  • Fixed all failing tests that referenced removed "notifications" resource
  • Updated test expectations to use "analytics" resource with correct operation names
  • Enhanced test coverage for new notification features
• API Response Handling: Added defensive coding to handle undefined API responses
  • Protected against null/undefined responses in notification operations
  • Improved error handling for edge cases in API communication
• Code Quality: Resolved all ESLint violations
  • Fixed parameter validation issues in analytics operations
  • Standardized boolean parameter descriptions
  • Removed inappropriate type constraints

Changed

• Operation Consolidation: Streamlined notification operations under Analytics resource
  • getUnreadCount and markAsSeen operations now use Analytics resource
  • Updated internal routing and parameter handling
  • Improved consistency across notification-related operations
• Enhanced Message Formatting: Updated analytics response messages to include timestamps
  • Better tracking of when notifications were marked as seen
  • Improved debugging and audit trail capabilities

Technical

• Import Cleanup: Removed unused notification-related imports from main node file
• Properties Optimization: Streamlined node properties configuration by removing redundant notification properties
• Test Infrastructure: Enhanced mock implementations for better test reliability and coverage

[1.3.1] - 2025-05-24

Changed

• Chat UI Removed: Disabled all chat operations from the user interface to avoid confusion since chat APIs are not available on the main Bluesky instance
  • Chat functionality remains in codebase but is hidden from UI
  • Chat operations now throw "operation not supported" errors if accessed
  • Updated tests to verify chat operations are properly disabled
  • Chat features can be re-enabled in future when Bluesky supports them on main instance

Improved

• Error Handling: Enhanced error handling for chat operations with specific XRPCNotSupported detection
  • Added centralized handleChatError helper function
  • Improved error messages explaining chat API limitations
  • All chat operations now provide clear feedback about experimental nature

[Unreleased]

Added

• Enhanced Feed Filtering: Added comprehensive filtering options for "Get Author Feed" operation
  • Posts with Replies: All posts, including replies (default behavior)
  • Posts without Replies: Only top-level posts, excludes replies
  • Posts with Media: Only posts containing media attachments
  • Posts and Author Threads: Posts and threads authored by the user
  • Posts with Video: Only posts containing video content
• API-Level Filtering: Filters are applied at the Bluesky API level for optimal performance
• Enhanced User Experience: Intuitive dropdown selection for content type filtering

Changed

• Updated getAuthorFeed operation to accept optional filter parameter
• Enhanced test coverage to include filter parameter validation
• Improved documentation with detailed filter descriptions and use cases

Fixed

• Test Suite Stability: Resolved all failing tests to achieve 100% test pass rate (55/55 tests passing)
• Chat API Mock Structure: Fixed Jest mock setup for chat operations to properly handle nested API structure
• Media Upload Testing: Enhanced mock implementation for binary data upload operations
• Mock Cleanup Strategy: Improved test isolation while preserving mock object structure integrity

[1.3.1] - 2025-05-24

Fixed

• Chat Error Handling: Enhanced error messages for chat operations with better feedback when chat functionality is not available on the current Bluesky instance (XRPCNotSupported errors)

Changed

• Documentation: Updated README.md and CHANGELOG.md to clearly mark chat operations as experimental features requiring special Bluesky instance support

[1.3.0] - 2025-05-23

Added

• Analytics Resource: New analytics capabilities for post performance tracking and engagement automation
• Notification Management: List notifications with filtering options (priority, pagination, date ranges)
• Unread Count Tracking: Get real-time count of unread notifications for the authenticated user
• Mark as Seen: Update notification read status with timestamp control
• Post Interaction Analytics: Comprehensive analysis of post engagement including:
  • Likes tracking with actor details and timestamps
  • Reposts tracking with user information
  • Replies analysis with thread context
  • Configurable interaction types and limits
  • Automatic analytics summary with aggregated counts
• Enhanced Notification Operations: Improved notification handling with cursor-based pagination, priority filtering, and date-based queries
• Type-Safe Implementation: Full TypeScript support with proper error handling throughout analytics operations

Changed

• Updated notification operations to use correct Bluesky API endpoints and response structures
• Improved error handling and user feedback for analytics operations
• Enhanced code organization with dedicated analytics operations module

Technical

• Fixed TypeScript compilation issues in analytics operations
• Resolved all ESLint warnings and maintained code quality standards
• Added comprehensive test coverage for analytics features
• Integrated analytics seamlessly into existing BlueskyV2 node architecture

[1.2.0] - 2025-05-23

Added

• New "Reply to a Post" operation that allows replying to existing posts with proper thread structure
• New "Quote a Post" operation that allows quoting existing posts in new posts
• Complete thread awareness for replies, finding the correct root and parent references

[1.1.7] - 2025-05-23

Changed

• Cleaned up verbose debug logging statements while preserving essential error logging
• Improved code readability by removing temporary debugging statements used during development

[1.1.4] - 2025-05-23

Fixed

• Fixed "mediaItems is not iterable" error that prevented media from being uploaded in some cases
• Added defensive programming to ensure that mediaItems is always a valid array

[1.1.3] - 2025-05-23

Fixed

• Fixed binary data handling for media uploads, allowing images to be properly attached to posts.
• Added detailed error logging for media uploads to help diagnose any issues.

[1.1.2] - 2025-05-23

Fixed

• Fixed issue where the 'Graph' resource wasn't selectable in the UI due to missing resource definition.

[1.1.1] - 2025-05-23

Fixed

• Fixed an issue with the API method path for thread muting.

[1.1.0] - 2025-05-23

Added

• Post with Media: Added ability to create posts with attached images.
  • New includeMedia boolean parameter for the 'Create Post' operation.
  • New mediaItems collection parameter to specify binary image data and alt text for each image.
  • Website card (websiteCard parameter) is automatically hidden and not processed if includeMedia is true.
• Get Post Thread: Added new 'Get Post Thread' operation under the 'Feed' resource.
  • Fetches the full context of a conversation thread (post, parents, replies).
  • Parameters: uri (of the root post), depth (of parent replies), parentHeight (of child replies).
• Mute Thread: Added new 'Mute Thread' operation under the new 'Graph' resource.
  • Mutes a conversation thread, preventing notifications for it.
  • Parameter: uri (of the root post of the thread to mute).

Changed

• The 'Create Post' operation now correctly includes $type: 'app.bsky.feed.post' and createdAt in the post record.

[1.0.3] - 2025-05-23

Fixed

• Fixed resource handling for search operations - now search operations will properly appear in the UI
• Improved error handling to use n8n's NodeOperationError

[1.0.2] - 2025-05-23

Added

• Added CHANGELOG.md to track version history
• Updated README.md to reference the changelog
• Added new Search resource with two operations:
  • Search Users: Find users by keywords using app.bsky.actor.searchActors
  • Search Posts: Find posts by keywords using app.bsky.feed.searchPosts
• Added optional author filtering for post search

[1.0.1] - 2025-05-23

Fixed

• Fixed package.json configuration to properly register the Bluesky node with n8n
• Removed duplicate node registration that was causing installation errors in n8n

[1.0.0] - 2025-05-23

Added

• List All Followers Operation: Added ability to fetch all followers for a Bluesky user with pagination

  • Configurable maximum results and page size
  • Automatic paging through all results using cursor-based pagination
  • Proper error handling and result formatting

• List All Follows Operation: Added ability to fetch all accounts a user is following with pagination

  • Configurable maximum results and page size
  • Automatic paging through all results using cursor-based pagination
  • Proper error handling and result formatting

Changed

• Updated package configuration for better integration with n8n
• Enhanced documentation with detailed examples and use cases
• Optimized handling of API responses

Fixed

• Several TypeScript type issues in the original codebase
• Icon reference in BlueskyApi.credentials.ts

[0.1.0] - 2023-09-14

Added

• Initial fork from @muench-dev/n8n-nodes-bluesky
• Core functionality including:
  • User operations: Block, Get Profile, Mute, Unmute
  • Feed operations: Get Author Feed, Get Timeline
  • Post operations: Create, Like, Unlike, Repost, Delete Repost