@bernierllc/social-media-content-type-facebook

Facebook-specific content type definition and validation for the BernierLLC ecosystem.

Installation

npm install @bernierllc/social-media-content-type-facebook

Overview

This package provides Facebook-specific content type definitions, validation rules, and transformation utilities. It is designed as a pure core package that focuses solely on content structure and validation, with no API calls or authentication logic.

Key Features:

• Facebook-specific content constraints (63,206 character limit)
• Album support (up to 50 images)
• Video posting with captions and cross-posting to Instagram
• Story creation (20 second limit)
• Event creation and management
• Poll creation (2-10 options)
• Photo tagging with coordinates
• 5 privacy levels
• Content transformation from generic/blog/event formats
• Fluent builder API for easy content creation

Usage

Basic Status Post

import { FacebookContentBuilder, FacebookContentValidator } from '@bernierllc/social-media-content-type-facebook';

const builder = new FacebookContentBuilder();
const post = builder
  .setText('Hello Facebook!')
  .setPostType('status')
  .build();

const validator = new FacebookContentValidator();
const result = validator.validate(post);

if (result.valid) {
  console.log('Post is ready to publish!');
}

Creating a Photo Album

import { FacebookContentBuilder } from '@bernierllc/social-media-content-type-facebook';

const albumPost = new FacebookContentBuilder()
  .setText('Summer vacation photos')
  .setAlbum({
    title: 'Hawaii 2025',
    description: 'Amazing trip!',
    images: [
      { type: 'image', url: 'https://example.com/1.jpg', description: 'Beach sunset' },
      { type: 'image', url: 'https://example.com/2.jpg', description: 'Snorkeling' },
      { type: 'image', url: 'https://example.com/3.jpg', description: 'Luau dinner' }
    ],
    privacy: 'friends'
  })
  .build();

Video Post with Captions

import { FacebookContentBuilder } from '@bernierllc/social-media-content-type-facebook';

const videoPost = new FacebookContentBuilder()
  .setText('Check out my tutorial!')
  .setVideo({
    url: 'https://example.com/tutorial.mp4',
    title: 'How to Build Packages',
    description: 'Step-by-step guide',
    thumbnailUrl: 'https://example.com/thumb.jpg',
    captions: [
      { language: 'en', url: 'https://example.com/en.srt' },
      { language: 'es', url: 'https://example.com/es.srt' }
    ],
    crosspostToInstagram: true
  })
  .build();

Creating a Story

import { FacebookContentBuilder, FACEBOOK_CONSTRAINTS } from '@bernierllc/social-media-content-type-facebook';

const story = new FacebookContentBuilder()
  .setText('Quick update!')
  .setStory({
    media: {
      type: 'image',
      url: 'https://example.com/story.jpg'
    },
    duration: FACEBOOK_CONSTRAINTS.maxStoryDuration, // 20 seconds
    link: {
      url: 'https://example.com/article'
    },
    stickers: [
      { type: 'poll', config: { question: 'Like?', options: ['Yes', 'No'] } }
    ]
  })
  .build();

Creating an Event

import { FacebookContentBuilder } from '@bernierllc/social-media-content-type-facebook';

const event = new FacebookContentBuilder()
  .setText('Join us for our tech conference!')
  .setEvent({
    name: 'Tech Conference 2025',
    startTime: new Date('2025-12-01T09:00:00'),
    endTime: new Date('2025-12-01T17:00:00'),
    location: {
      name: 'Convention Center',
      city: 'San Francisco',
      state: 'CA'
    },
    description: 'Full day of talks and workshops',
    coverImage: 'https://example.com/cover.jpg',
    isOnline: false
  })
  .build();

Content Transformation

import { FacebookContentTransformer, GenericSocialContent } from '@bernierllc/social-media-content-type-facebook';

const transformer = new FacebookContentTransformer();

// From generic social content
const generic: GenericSocialContent = {
  text: 'Check out my blog!',
  images: ['https://example.com/1.jpg', 'https://example.com/2.jpg'],
  links: ['https://blog.example.com/post']
};

const facebookContent = transformer.fromGeneric(generic);

// From blog post
const blogPost = {
  title: 'My Latest Article',
  excerpt: 'This is an interesting read...',
  url: 'https://blog.example.com/article',
  featuredImage: 'https://blog.example.com/featured.jpg'
};

const linkPost = transformer.fromBlogPost(blogPost);

// Convert to story
const photoPost = {
  text: 'Beautiful sunset',
  postType: 'photo' as const,
  media: [{ type: 'image' as const, url: 'https://example.com/sunset.jpg' }]
};

const story = transformer.convertToStory(photoPost);

Creating a Poll

import { FacebookContentBuilder } from '@bernierllc/social-media-content-type-facebook';

const pollPost = new FacebookContentBuilder()
  .setText('What is your favorite programming language?')
  .addPoll({
    question: 'Pick your favorite',
    options: ['TypeScript', 'JavaScript', 'Python', 'Go', 'Rust'],
    allowMultipleAnswers: false
  })
  .build();

API Reference

FacebookContentBuilder

Fluent API for building Facebook content:

• setText(text: string) - Set post text (max 63,206 chars)
• setPostType(type) - Set post type (status, photo, video, link, album, story, event)
• addMedia(media) - Add media item (image or video)
• addMediaArray(media[]) - Add multiple media items
• setVideo(video) - Set video content
• setAlbum(album) - Set album content
• setLink(link) - Set link preview
• setStory(story) - Set story content
• setEvent(event) - Set event details
• addPoll(poll) - Add poll to post
• build() - Build and return FacebookContent
• validate() - Validate without building
• reset() - Reset builder to initial state
• clone() - Clone the current builder

FacebookContentValidator

Validates Facebook content:

• validate(content) - Validate complete content, returns ValidationResult
• validateText(text) - Validate text length
• validateMedia(media[]) - Validate media array
• validateVideo(video) - Validate video content
• validateAlbum(album) - Validate album
• validateStory(story) - Validate story
• validateEvent(event) - Validate event
• validatePoll(poll) - Validate poll

FacebookContentTransformer

Transforms content between formats:

• fromGeneric(content) - Transform from generic social content
• fromBlogPost(post) - Transform from blog post
• toGeneric(content) - Convert to generic format
• optimizeForFacebook(content) - Optimize content for Facebook
• convertToStory(content) - Convert to story format
• createAlbum(images[], title, description?) - Create album from URLs

Facebook Constraints

FACEBOOK_CONSTRAINTS = {
  maxTextLength: 63206,        // Unique to Facebook
  maxAlbumImages: 50,          // Much higher than other platforms
  maxPollOptions: 10,
  minPollOptions: 2,
  maxStoryDuration: 20,        // Seconds
  supportedMediaTypes: ['image/png', 'image/jpeg', 'image/gif', 'video/mp4', 'video/mov'],
  maxImageSize: 10 * 1024 * 1024,  // 10MB
  maxVideoSize: 4 * 1024 * 1024 * 1024  // 4GB
}

Facebook Platform Features

Post Types

• Status - Text-only posts
• Photo - Single or multiple images
• Video - Video with optional captions
• Link - Link preview with image
• Album - Up to 50 images with captions
• Story - 20-second max, auto-archives after 24 hours
• Event - Event creation with location/time

Privacy Levels

• public - Visible to everyone
• friends - Only friends can see
• friends_of_friends - Friends and their friends
• only_me - Private, only you
• custom - Custom audience

Album Features

• Up to 50 images (more than Twitter, LinkedIn, etc.)
• Individual image captions
• Photo tagging with coordinates
• Album-level privacy settings

Story Features

• 20-second maximum duration
• Vertical format recommended (9:16)
• Interactive stickers (poll, question, countdown, location, mention)
• Link attachment
• Background music
• Auto-archives after 24 hours

Event Features

• In-person, online, or hybrid events
• Location with coordinates
• Start/end time
• Cover image
• Event description
• Online event URL

Video Features

• Up to 4GB file size
• 240 minutes maximum (for pages)
• Multiple caption files (SRT format)
• Cross-posting to Instagram
• Thumbnail customization
• Recommended: H.264 codec, AAC audio, 1280x720 resolution

Content Type Transformations

This package supports transformations from:

• Generic Social Content → Facebook posts, albums, or link posts
• Blog Post Content → Facebook link posts with preview or albums
• Event Content → Facebook events

And to:

• Generic Social Content ← Facebook content (for cross-platform use)
• Story Format ← Facebook photo/video/album posts

Integration Points

Used By

• @bernierllc/social-media-facebook - Facebook publishing service
• @bernierllc/social-media-manager - Multi-platform manager
• @bernierllc/content-management-suite - Content management system

Dependencies

• @bernierllc/crypto-utils - Media hash generation (optional, for deduplication)
• validator - URL validation

Integration Status

Logger Integration

Status: Not applicable

Justification: This is a pure content type definition package with no runtime operations, side effects, or error conditions that require logging. The FacebookContentValidator, FacebookContentBuilder, and FacebookContentTransformer classes are stateless utility classes that perform validation, building, and transformation operations. All errors are thrown as exceptions that calling code can handle, and there are no background operations, network calls, or state changes that would benefit from structured logging.

Pattern: Pure functional utility - no logger integration needed. Logging is handled by consuming packages that use this content type.

NeverHub Integration

Status: Optional

Justification: This package can optionally register itself with NeverHub for service discovery. Content type packages can register themselves with NeverHub so that services can discover available content types at runtime. This enables dynamic content type discovery and allows services to adapt to available content types without hard-coded dependencies. However, the package is designed to work without NeverHub for simpler use cases.

Pattern: Optional service discovery integration - package can register content type with NeverHub for runtime discovery.

Example Integration:

import { registerFacebookContentType } from '@bernierllc/social-media-content-type-facebook/neverhub-registration';

// Register with NeverHub (if available)
if (typeof detectNeverHub === 'function') {
  registerFacebookContentType();
}

Docs-Suite Integration

Status: Ready

Format: TypeDoc-compatible JSDoc comments are included throughout the source code. All public APIs are documented with examples and type information.

Best Practices

Album Creation

• Group related images together
• Use descriptive titles and descriptions
• Keep albums focused on a single topic/event
• Optimize image order for narrative flow
• Albums get higher engagement than single images

Video Optimization

• Keep videos under 2 minutes for best performance
• Use square videos (1:1) for mobile
• Add captions/subtitles (85% watch muted)
• Enable cross-posting to Instagram for wider reach
• Use native uploads instead of links

Story Best Practices

• Use vertical format (9:16 ratio)
• High contrast text overlays
• Call-to-action in first 3 seconds
• Interactive stickers increase engagement
• Stories auto-archive after 24 hours

Event Creation

• Post during peak hours (1-4 PM local time)
• Use high-quality cover images
• Provide complete location details
• Set up both in-person and online options for hybrid events

Examples

See the /examples directory for complete working examples:

• basic-post.ts - Simple status posts
• album-creation.ts - Creating photo albums
• video-posting.ts - Video posts with captions
• story-creation.ts - Facebook Stories
• event-creation.ts - Event creation

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build package
npm run build

# Lint code
npm run lint

License

Copyright (c) 2025 Bernier LLC. All rights reserved.

This file is licensed to the client under a limited-use license. The client may use and modify this code only within the scope of the project it was delivered for. Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.

See Also

• @bernierllc/social-media-content-type-twitter
• @bernierllc/social-media-content-type-linkedin
• @bernierllc/social-media-content-type-instagram
• @bernierllc/social-media-facebook (Service layer)