@memberjunction/actions-bizapps-social

Social media automation actions for MemberJunction, providing a unified interface to create posts, retrieve analytics, manage content, and search across eight major platforms: Twitter/X, LinkedIn, Facebook, Instagram, TikTok, YouTube, HootSuite, and Buffer.

Overview

This package implements the BizApps action patterns from the MemberJunction Actions framework, extending the shared BaseOAuthAction class to provide platform-specific social media operations. Each platform has its own base class handling authentication, rate limiting, and API conventions, with individual action classes for discrete operations like creating posts, fetching analytics, and searching content.

All actions are registered via @RegisterClass(BaseAction, ...) for automatic discovery by MJ’s metadata-driven action system, making them available to AI agents, workflow engines, and low-code environments. See the Actions CLAUDE.md for the overall Actions design philosophy.

Architecture

Class Hierarchy

classDiagram
    direction TB
    class BaseAction {
        +InternalRunAction()
    }
    class BaseOAuthAction {
        +initializeOAuth()
        +getAccessToken()
        +getRefreshToken()
        +updateStoredTokens()
    }
    class BaseSocialMediaAction {
        +platformName
        +apiBaseUrl
        +normalizeAnalytics()
        +uploadMedia()
        +handleRateLimit()
        +searchPosts()
        +normalizePost()
        +buildHeaders()
    }
    class TwitterBaseAction
    class LinkedInBaseAction
    class FacebookBaseAction
    class InstagramBaseAction
    class TikTokBaseAction
    class YouTubeBaseAction
    class HootSuiteBaseAction
    class BufferBaseAction

    BaseAction <|-- BaseOAuthAction
    BaseOAuthAction <|-- BaseSocialMediaAction
    BaseSocialMediaAction <|-- TwitterBaseAction
    BaseSocialMediaAction <|-- LinkedInBaseAction
    BaseSocialMediaAction <|-- FacebookBaseAction
    BaseSocialMediaAction <|-- InstagramBaseAction
    BaseSocialMediaAction <|-- TikTokBaseAction
    BaseSocialMediaAction <|-- YouTubeBaseAction
    BaseSocialMediaAction <|-- HootSuiteBaseAction
    BaseSocialMediaAction <|-- BufferBaseAction

    style BaseAction fill:#64748b,stroke:#475569,color:#fff
    style BaseOAuthAction fill:#7c5295,stroke:#563a6b,color:#fff
    style BaseSocialMediaAction fill:#2d6a9f,stroke:#1a4971,color:#fff
    style TwitterBaseAction fill:#2d8659,stroke:#1a5c3a,color:#fff
    style LinkedInBaseAction fill:#2d8659,stroke:#1a5c3a,color:#fff
    style FacebookBaseAction fill:#2d8659,stroke:#1a5c3a,color:#fff
    style InstagramBaseAction fill:#2d8659,stroke:#1a5c3a,color:#fff
    style TikTokBaseAction fill:#2d8659,stroke:#1a5c3a,color:#fff
    style YouTubeBaseAction fill:#2d8659,stroke:#1a5c3a,color:#fff
    style HootSuiteBaseAction fill:#2d8659,stroke:#1a5c3a,color:#fff
    style BufferBaseAction fill:#2d8659,stroke:#1a5c3a,color:#fff

Data Flow

flowchart LR
    subgraph Consumers
        Agent[AI Agent]
        Workflow[Workflow Engine]
        UI[Low-Code Builder]
    end

    subgraph SocialPackage["Social Actions Package"]
        BSM[BaseSocialMediaAction]
        subgraph Providers
            TW[Twitter]
            LI[LinkedIn]
            FB[Facebook]
            IG[Instagram]
            TK[TikTok]
            YT[YouTube]
            HS[HootSuite]
            BF[Buffer]
        end
    end

    subgraph External["External APIs"]
        TWA[Twitter API v2]
        LIA[LinkedIn API v2]
        FBA[Graph API v18.0]
        IGA[Instagram Graph API]
        TKA[TikTok Display API v2]
        YTA[YouTube Data API v3]
        HSA[HootSuite API v1]
        BFA[Buffer API v1]
    end

    subgraph MJ["MJ Infrastructure"]
        CI[CompanyIntegration]
        OAuth[OAuth Tokens]
    end

    Agent --> BSM
    Workflow --> BSM
    UI --> BSM
    BSM --> TW & LI & FB & IG & TK & YT & HS & BF
    TW --> TWA
    LI --> LIA
    FB --> FBA
    IG --> IGA
    TK --> TKA
    YT --> YTA
    HS --> HSA
    BF --> BFA
    BSM --> CI
    CI --> OAuth

    style BSM fill:#2d6a9f,stroke:#1a4971,color:#fff
    style CI fill:#7c5295,stroke:#563a6b,color:#fff
    style OAuth fill:#7c5295,stroke:#563a6b,color:#fff
    style TW fill:#2d8659,stroke:#1a5c3a,color:#fff
    style LI fill:#2d8659,stroke:#1a5c3a,color:#fff
    style FB fill:#2d8659,stroke:#1a5c3a,color:#fff
    style IG fill:#2d8659,stroke:#1a5c3a,color:#fff
    style TK fill:#2d8659,stroke:#1a5c3a,color:#fff
    style YT fill:#2d8659,stroke:#1a5c3a,color:#fff
    style HS fill:#2d8659,stroke:#1a5c3a,color:#fff
    style BF fill:#2d8659,stroke:#1a5c3a,color:#fff

Installation

npm install @memberjunction/actions-bizapps-social

This package is part of the MemberJunction monorepo. When working within the monorepo, add the dependency to your package’s package.json and run npm install from the repository root.

Authentication

All platforms authenticate via OAuth 2.0 credentials stored in the MemberJunction CompanyIntegration entity. The BaseOAuthAction base class (from @memberjunction/actions) provides:

Token retrieval from CompanyIntegration records
Automatic token refresh when expired
OAuth flow helpers
Standard error handling for auth failures

CompanyIntegration Field Mapping

Field	Purpose
`AccessToken`	OAuth access token
`RefreshToken`	OAuth refresh token (where applicable)
`ExpirationDate`	Token expiration timestamp
`CustomAttribute1`	Platform account/profile ID
`CustomAttribute2`	OAuth Client ID / App ID
`CustomAttribute3`	OAuth Client Secret / App Secret
`CustomAttribute4`	Additional platform-specific data

Platform Reference

Twitter/X

API: Twitter API v2 | Rate Limits: 15-900 requests per 15 min (varies by endpoint)

Action	Class	Description
Create Tweet	`TwitterCreateTweetAction`	Post tweets with media, polls, replies, or quote tweets
Create Thread	`TwitterCreateThreadAction`	Post multi-tweet threads
Get Timeline	`TwitterGetTimelineAction`	Retrieve authenticated user’s timeline
Get Mentions	`TwitterGetMentionsAction`	Retrieve mentions of the authenticated user
Get Analytics	`TwitterGetAnalyticsAction`	Retrieve tweet and account analytics
Schedule Tweet	`TwitterScheduleTweetAction`	Schedule a tweet for future publication
Delete Tweet	`TwitterDeleteTweetAction`	Delete an existing tweet
Search Tweets	`TwitterSearchTweetsAction`	Search tweets with full Twitter search operators

Media: JPEG, PNG, GIF (15MB), WebP images (5MB); MP4 video (512MB). Chunked upload with processing status polling for videos.

API: LinkedIn Marketing Developer Platform v2 | Rate Limits: Application-level and member-level limits

Action	Class	Description
Create Post	`LinkedInCreatePostAction`	Post to personal profiles or organization pages
Create Article	`LinkedInCreateArticleAction`	Publish long-form articles
Get Organization Posts	`LinkedInGetOrganizationPostsAction`	Retrieve posts from an organization page
Get Personal Posts	`LinkedInGetPersonalPostsAction`	Retrieve personal profile posts
Get Post Analytics	`LinkedInGetPostAnalyticsAction`	Retrieve analytics for specific posts
Get Followers	`LinkedInGetFollowersAction`	Retrieve follower information
Schedule Post	`LinkedInSchedulePostAction`	Schedule a post for future publication
Search Posts	`LinkedInSearchPostsAction`	Search organization posts

Media: JPEG, PNG, GIF, WebP images (10MB). Two-step upload via asset registration.

Facebook

API: Graph API v18.0 | Rate Limits: 200 calls per hour per user

Action	Class	Description
Create Post	`FacebookCreatePostAction`	Create page or profile posts with media
Get Page Posts	`FacebookGetPagePostsAction`	Retrieve posts from a managed page
Get Post Insights	`FacebookGetPostInsightsAction`	Retrieve detailed post metrics
Get Page Insights	`FacebookGetPageInsightsAction`	Retrieve page-level analytics
Schedule Post	`FacebookSchedulePostAction`	Schedule posts for future publication
Create Album	`FacebookCreateAlbumAction`	Create photo albums on pages
Respond to Comments	`FacebookRespondToCommentsAction`	Reply to comments on posts
Boost Post	`FacebookBoostPostAction`	Promote posts with paid advertising
Search Posts	`FacebookSearchPostsAction`	Search within page posts

Media: JPEG, PNG, GIF, BMP, TIFF images (4MB); MP4, MOV, MKV, WebM video (10GB). Page-specific access tokens for page operations.

Instagram

API: Instagram Graph API + Basic Display API | Rate Limits: 200 calls per hour per user

Action	Class	Description
Create Post	`InstagramCreatePostAction`	Create feed posts (image/video/carousel)
Create Story	`InstagramCreateStoryAction`	Create Instagram stories
Get Business Posts	`InstagramGetBusinessPostsAction`	Retrieve business account posts
Get Post Insights	`InstagramGetPostInsightsAction`	Retrieve post-level metrics
Get Account Insights	`InstagramGetAccountInsightsAction`	Retrieve account-level analytics
Get Comments	`InstagramGetCommentsAction`	Retrieve comments on posts
Schedule Post	`InstagramSchedulePostAction`	Schedule posts for future publication
Search Posts	`InstagramSearchPostsAction`	Search business account posts by caption

Media: Requires publicly accessible URLs (CDN hosting). Container-based publishing workflow with status polling.

TikTok

API: Display API v2 | Rate Limits: 1,000 requests per day

Action	Class	Description
Create Video Post	`TikTokCreateVideoPostAction`	Create video posts (requires API approval)
Get User Videos	`TikTokGetUserVideosAction`	Retrieve authenticated user’s videos
Get Video Analytics	`TikTokGetVideoAnalyticsAction`	Retrieve analytics for specific videos
Get Account Analytics	`TikTokGetAccountAnalyticsAction`	Retrieve account-level metrics
Get Comments	`TikTokGetCommentsAction`	Retrieve comments on videos
Get Trending Hashtags	`TikTokGetTrendingHashtagsAction`	Discover trending hashtags
Search Videos	`TikTokSearchVideosAction`	Search within user’s own videos

Media: Video only (MP4, MOV, WebM; max 287.6MB). Video upload requires special TikTok API approval.

YouTube

API: Data API v3 | Rate Limits: 10,000 quota units per day

Action	Class	Description
Upload Video	`YouTubeUploadVideoAction`	Upload videos with metadata and thumbnails
Get Channel Videos	`YouTubeGetChannelVideosAction`	Retrieve videos from a channel
Get Video Analytics	`YouTubeGetVideoAnalyticsAction`	Retrieve per-video analytics
Get Channel Analytics	`YouTubeGetChannelAnalyticsAction`	Retrieve channel-level metrics
Get Comments	`YouTubeGetCommentsAction`	Retrieve video comments
Update Video Metadata	`YouTubeUpdateVideoMetadataAction`	Update title, description, tags
Create Playlist	`YouTubeCreatePlaylistAction`	Create and manage playlists
Schedule Video	`YouTubeScheduleVideoAction`	Schedule video publication
Search Videos	`YouTubeSearchVideosAction`	Search channel videos with filters

Media: MP4, AVI, MOV, WMV, FLV, WebM video (128GB). Resumable upload with chunked transfer. Quota-aware operations with cost tracking.

HootSuite

API: Platform API v1 | Rate Limits: 250 requests per hour

Action	Class	Description
Create Scheduled Post	`HootSuiteCreateScheduledPostAction`	Create and schedule multi-platform posts
Get Scheduled Posts	`HootSuiteGetScheduledPostsAction`	Retrieve scheduled post queue
Update Scheduled Post	`HootSuiteUpdateScheduledPostAction`	Modify a scheduled post
Delete Scheduled Post	`HootSuiteDeleteScheduledPostAction`	Remove a scheduled post
Bulk Schedule Posts	`HootSuiteBulkSchedulePostsAction`	Schedule multiple posts at once
Get Social Profiles	`HootSuiteGetSocialProfilesAction`	List connected social profiles
Get Analytics	`HootSuiteGetAnalyticsAction`	Retrieve cross-platform analytics
Search Posts	`HootSuiteSearchPostsAction`	Full text search across connected accounts

Media: Two-step upload (request URL, then PUT file data) with processing status polling.

Buffer

API: Buffer API v1 | Rate Limits: 600 requests per hour

Action	Class	Description
Create Post	`BufferCreatePostAction`	Create posts across connected profiles
Get Profiles	`BufferGetProfilesAction`	List connected social profiles
Get Pending Posts	`BufferGetPendingPostsAction`	Retrieve queued/scheduled posts
Get Sent Posts	`BufferGetSentPostsAction`	Retrieve published posts
Get Analytics	`BufferGetAnalyticsAction`	Retrieve engagement analytics
Reorder Queue	`BufferReorderQueueAction`	Reorder posts in the publishing queue
Delete Post	`BufferDeletePostAction`	Remove a post from the queue
Search Posts	`BufferSearchPostsAction`	Client-side search across sent posts

Media: Form-data upload returning media URLs for attachment to updates.

Common Interfaces

All platform actions normalize data to shared interfaces defined in BaseSocialMediaAction:

SocialPost

The standard format for posts across all platforms:

interface SocialPost {
    id: string;
    platform: string;
    profileId: string;
    content: string;
    mediaUrls: string[];
    publishedAt: Date;
    scheduledFor?: Date;
    analytics?: SocialAnalytics;
    platformSpecificData: Record<string, unknown>;
}

SocialAnalytics

Normalized engagement metrics:

interface SocialAnalytics {
    impressions: number;
    engagements: number;
    clicks: number;
    shares: number;
    comments: number;
    likes: number;
    reach: number;
    saves?: number;
    videoViews?: number;
    platformMetrics: Record<string, unknown>;
}

SearchParams

Unified search parameters:

interface SearchParams {
    query?: string;
    hashtags?: string[];
    startDate?: Date;
    endDate?: Date;
    limit?: number;
    offset?: number;
}

MediaFile

Standard media file representation:

interface MediaFile {
    filename: string;
    mimeType: string;
    data: Buffer | string;  // Buffer or base64 string
    size: number;
}

Usage Examples

Creating a Tweet with Media

import { ActionEngineServer } from '@memberjunction/actions';

const engine = ActionEngineServer.Instance;
const result = await engine.RunAction('TwitterCreateTweetAction', [
    { Name: 'CompanyIntegrationID', Value: 'integration-uuid' },
    { Name: 'Content', Value: 'Check out our latest product launch!' },
    { Name: 'MediaFiles', Value: [{
        filename: 'product.jpg',
        mimeType: 'image/jpeg',
        data: base64ImageData,
        size: 1024000
    }] }
], contextUser);

if (result.Success) {
    const tweetId = result.Params.find(p => p.Name === 'TweetID')?.Value;
    const tweetUrl = result.Params.find(p => p.Name === 'TweetURL')?.Value;
}

Creating a LinkedIn Organization Post

const result = await engine.RunAction('LinkedInCreatePostAction', [
    { Name: 'CompanyIntegrationID', Value: 'integration-uuid' },
    { Name: 'Content', Value: 'Excited to announce our new partnership!' },
    { Name: 'AuthorType', Value: 'organization' },
    { Name: 'OrganizationID', Value: 'org-12345' },
    { Name: 'Visibility', Value: 'PUBLIC' }
], contextUser);

Uploading a YouTube Video

const result = await engine.RunAction('YouTubeUploadVideoAction', [
    { Name: 'CompanyIntegrationID', Value: 'integration-uuid' },
    { Name: 'Title', Value: 'Product Demo - Q1 2025' },
    { Name: 'Description', Value: 'Full walkthrough of our latest features.' },
    { Name: 'Tags', Value: ['demo', 'product', 'tutorial'] },
    { Name: 'PrivacyStatus', Value: 'public' },
    { Name: 'VideoFile', Value: videoFileObject },
    { Name: 'NotifySubscribers', Value: true }
], contextUser);

if (result.Success) {
    const videoUrl = result.Params.find(p => p.Name === 'VideoURL')?.Value;
}

Searching Historical Posts

const result = await engine.RunAction('TwitterSearchTweetsAction', [
    { Name: 'CompanyIntegrationID', Value: 'integration-uuid' },
    { Name: 'Query', Value: 'product launch' },
    { Name: 'StartDate', Value: '2025-01-01' },
    { Name: 'EndDate', Value: '2025-06-30' },
    { Name: 'Limit', Value: 100 }
], contextUser);

Multi-Platform Posting via Buffer

const result = await engine.RunAction('BufferCreatePostAction', [
    { Name: 'CompanyIntegrationID', Value: 'integration-uuid' },
    { Name: 'ProfileIDs', Value: ['twitter-profile-id', 'linkedin-profile-id'] },
    { Name: 'Content', Value: 'Big announcement coming soon!' },
    { Name: 'ScheduledAt', Value: new Date('2025-03-15T10:00:00Z') }
], contextUser);

Error Handling

All actions use a standardized error code enum for consistent error classification:

enum SocialMediaErrorCode {
    RATE_LIMIT_EXCEEDED = 'RATE_LIMIT',
    INVALID_TOKEN = 'INVALID_TOKEN',
    TOKEN_EXPIRED = 'TOKEN_EXPIRED',
    PLATFORM_ERROR = 'PLATFORM_ERROR',
    INVALID_MEDIA = 'INVALID_MEDIA',
    POST_NOT_FOUND = 'POST_NOT_FOUND',
    INSUFFICIENT_PERMISSIONS = 'INSUFFICIENT_PERMISSIONS'
}

Each platform base class provides a dedicated error handler (e.g., handleTwitterError, handleFacebookError) that maps platform-specific HTTP status codes and error payloads to these standardized codes. Rate limiting is handled automatically with exponential backoff and request retry via Axios interceptors.

Package Structure

src/
  index.ts                          # Package entry point
  base/
    base-social.action.ts           # BaseSocialMediaAction, interfaces, error codes
  providers/
    twitter/
      twitter-base.action.ts        # TwitterBaseAction (API v2, OAuth 2.0)
      actions/                      # 8 Twitter actions
    linkedin/
      linkedin-base.action.ts       # LinkedInBaseAction (Marketing API v2)
      actions/                      # 8 LinkedIn actions
    facebook/
      facebook-base.action.ts       # FacebookBaseAction (Graph API v18.0)
      actions/                      # 9 Facebook actions
    instagram/
      instagram-base.action.ts      # InstagramBaseAction (Graph API)
      actions/                      # 8 Instagram actions
    tiktok/
      tiktok-base.action.ts         # TikTokBaseAction (Display API v2)
      actions/                      # 7 TikTok actions
    youtube/
      youtube-base.action.ts        # YouTubeBaseAction (Data API v3)
      actions/                      # 9 YouTube actions
    hootsuite/
      hootsuite-base.action.ts      # HootSuiteBaseAction (Platform API v1)
      actions/                      # 8 HootSuite actions
    buffer/
      buffer-base.action.ts         # BufferBaseAction (Buffer API v1)
      actions/                      # 8 Buffer actions

Total: 65 action classes across 8 platform providers.

Dependencies

Package	Purpose
`@memberjunction/core`	Logging (`LogStatus`, `LogError`)
`@memberjunction/global`	`@RegisterClass` decorator for action discovery
`@memberjunction/actions-base`	`ActionParam`, `ActionResultSimple`, `RunActionParams`
`@memberjunction/actions`	`BaseAction`, `BaseOAuthAction` base classes
`@memberjunction/core-entities`	MJ entity type definitions
`axios`	HTTP client for platform API requests
`form-data`	Multipart form data for media uploads

@memberjunction/actions - Actions execution engine providing BaseAction and BaseOAuthAction
@memberjunction/actions-base - Base interfaces and type definitions
@memberjunction/core-actions - Core pre-built actions (HTTP, email, AI)
@memberjunction/actions-bizapps-accounting - Accounting system integrations (same BizApps pattern)
@memberjunction/actions-bizapps-lms - Learning management system integrations

Building

# From the package directory
cd packages/Actions/BizApps/Social
npm run build

# Watch mode
npm run watch