@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
Copy

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
Copy

Installation

npm install @memberjunction/actions-bizapps-social
Copy

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

Platform Reference

Twitter/X

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

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

LinkedIn

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

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

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

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

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

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

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

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>;
}
Copy

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>;
}
Copy

SearchParams

Unified search parameters:

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

MediaFile

Standard media file representation:

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

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;
}
Copy

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);
Copy

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;
}
Copy

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);
Copy

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);
Copy

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'
}
Copy

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
Copy

Total: 65 action classes across 8 platform providers.

Dependencies

Related Packages

• @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
Copy