@memberjunction/actions-bizapps-social 2.61.0

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @memberjunction/actions-bizapps-social@2.61.0 build
+> tsc
+

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# @memberjunction/actions-bizapps-social
+
+## 2.61.0
+
+### Minor Changes
+
+- 51b2b47: Improvements to AI Agents and Added Social Actions
+
+### Patch Changes
+
+- Updated dependencies [51b2b47]
+  - @memberjunction/actions@2.61.0
+  - @memberjunction/actions-base@2.61.0
+  - @memberjunction/core@2.61.0
+  - @memberjunction/core-entities@2.61.0
+  - @memberjunction/global@2.61.0

package/README.md

@@ -0,0 +1,375 @@
+# Social Media Actions for MemberJunction
+
+## Overview
+
+This package provides comprehensive social media automation capabilities for MemberJunction, enabling agents and applications to interact with major social media platforms programmatically. The implementation follows MJ's established patterns for BizApps actions while providing platform-specific functionality.
+
+## Architecture
+
+### Class Hierarchy
+
+```
+BaseAction (from @memberjunction/actions)
+    └── BaseOAuthAction (from @memberjunction/actions/Engine/src/generic)
+        └── BaseSocialMediaAction (base for all social actions)
+            ├── BaseHootSuiteAction
+            ├── BaseBufferAction
+            ├── BaseLinkedInAction
+            ├── BaseTwitterAction
+            ├── BaseFacebookAction
+            ├── BaseInstagramAction
+            ├── BaseTikTokAction
+            └── BaseYouTubeAction
+```
+
+### Authentication
+
+All social media platforms use OAuth 2.0 authentication. Credentials are stored in the MemberJunction CompanyIntegration table with the following structure:
+
+- **Integration Entity**: Defines the platform (e.g., "Twitter", "LinkedIn")
+- **CompanyIntegration Entity**: Stores company-specific credentials
+  - `AccessToken`: OAuth access token
+  - `RefreshToken`: OAuth refresh token (where applicable)
+  - `ExpirationDate`: Token expiration timestamp
+  - `CustomAttribute1-5`: Platform-specific data (e.g., account IDs)
+
+The `BaseOAuthAction` class provides:
+- Token retrieval from CompanyIntegration
+- Automatic token refresh when expired
+- OAuth flow helpers
+- Standard error handling for auth failures
+
+## Package Structure
+
+```
+packages/Actions/BizApps/Social/
+├── README.md (this file)
+├── package.json
+├── tsconfig.json
+├── src/
+│   ├── index.ts
+│   ├── base/
+│   │   └── base-social.action.ts
+│   └── providers/
+│       ├── hootsuite/
+│       │   ├── hootsuite-base.action.ts
+│       │   └── actions/
+│       │       ├── get-scheduled-posts.action.ts
+│       │       ├── create-scheduled-post.action.ts
+│       │       ├── get-analytics.action.ts
+│       │       ├── get-social-profiles.action.ts
+│       │       ├── update-scheduled-post.action.ts
+│       │       ├── delete-scheduled-post.action.ts
+│       │       ├── bulk-schedule-posts.action.ts
+│       │       └── search-posts.action.ts
+│       ├── buffer/
+│       │   ├── buffer-base.action.ts
+│       │   └── actions/
+│       │       ├── get-profiles.action.ts
+│       │       ├── create-post.action.ts
+│       │       ├── get-pending-posts.action.ts
+│       │       ├── get-sent-posts.action.ts
+│       │       ├── get-analytics.action.ts
+│       │       ├── reorder-queue.action.ts
+│       │       ├── delete-post.action.ts
+│       │       └── search-posts.action.ts
+│       ├── linkedin/
+│       │   ├── linkedin-base.action.ts
+│       │   └── actions/
+│       │       ├── create-post.action.ts
+│       │       ├── get-organization-posts.action.ts
+│       │       ├── get-personal-posts.action.ts
+│       │       ├── get-post-analytics.action.ts
+│       │       ├── schedule-post.action.ts
+│       │       ├── get-followers.action.ts
+│       │       ├── create-article.action.ts
+│       │       └── search-posts.action.ts
+│       ├── twitter/
+│       │   ├── twitter-base.action.ts
+│       │   └── actions/
+│       │       ├── create-tweet.action.ts
+│       │       ├── create-thread.action.ts
+│       │       ├── get-timeline.action.ts
+│       │       ├── get-mentions.action.ts
+│       │       ├── get-analytics.action.ts
+│       │       ├── schedule-tweet.action.ts
+│       │       ├── delete-tweet.action.ts
+│       │       └── search-tweets.action.ts
+│       ├── facebook/
+│       │   ├── facebook-base.action.ts
+│       │   └── actions/
+│       │       ├── create-post.action.ts
+│       │       ├── get-page-posts.action.ts
+│       │       ├── get-post-insights.action.ts
+│       │       ├── schedule-post.action.ts
+│       │       ├── create-album.action.ts
+│       │       ├── get-page-insights.action.ts
+│       │       ├── respond-to-comments.action.ts
+│       │       ├── boost-post.action.ts
+│       │       └── search-posts.action.ts
+│       ├── instagram/
+│       │   ├── instagram-base.action.ts
+│       │   └── actions/
+│       │       ├── create-post.action.ts
+│       │       ├── get-business-posts.action.ts
+│       │       ├── get-post-insights.action.ts
+│       │       ├── get-account-insights.action.ts
+│       │       ├── schedule-post.action.ts
+│       │       ├── get-comments.action.ts
+│       │       ├── create-story.action.ts
+│       │       └── search-posts.action.ts
+│       ├── tiktok/
+│       │   ├── tiktok-base.action.ts
+│       │   └── actions/
+│       │       ├── get-user-videos.action.ts
+│       │       ├── get-video-analytics.action.ts
+│       │       ├── get-account-analytics.action.ts
+│       │       ├── create-video-post.action.ts
+│       │       ├── get-comments.action.ts
+│       │       ├── get-trending-hashtags.action.ts
+│       │       └── search-videos.action.ts
+│       └── youtube/
+│           ├── youtube-base.action.ts
+│           └── actions/
+│               ├── upload-video.action.ts
+│               ├── get-channel-videos.action.ts
+│               ├── get-video-analytics.action.ts
+│               ├── update-video-metadata.action.ts
+│               ├── create-playlist.action.ts
+│               ├── schedule-video.action.ts
+│               ├── get-comments.action.ts
+│               ├── get-channel-analytics.action.ts
+│               └── search-videos.action.ts
+```
+
+## Common Features
+
+### BaseSocialMediaAction
+
+Provides common functionality for all social platforms:
+
+```typescript
+export abstract class BaseSocialMediaAction extends BaseOAuthAction {
+    // Common parameters for all social actions
+    protected get commonParams(): ActionParam[] {
+        return [
+            { Name: 'CompanyIntegrationID', Type: 'guid', Required: true, Description: 'Company integration identifier' },
+            { Name: 'ProfileID', Type: 'string', Required: false, Description: 'Social profile/account ID' }
+        ];
+    }
+
+    // Analytics normalization
+    protected normalizeAnalytics(platformData: any): SocialAnalytics {
+        // Convert platform-specific metrics to common format
+    }
+
+    // Media handling
+    protected async uploadMedia(files: MediaFile[]): Promise<string[]> {
+        // Handle media uploads with size/format validation
+    }
+
+    // Rate limiting
+    protected async handleRateLimit(retryAfter: number): Promise<void> {
+        // Intelligent rate limit handling
+    }
+
+    // Historical post search
+    protected abstract searchPosts(params: SearchParams): Promise<SocialPost[]>;
+}
+```
+
+### Common Interfaces
+
+```typescript
+interface SocialPost {
+    id: string;
+    platform: string;
+    profileId: string;
+    content: string;
+    mediaUrls: string[];
+    publishedAt: Date;
+    scheduledFor?: Date;
+    analytics?: SocialAnalytics;
+    platformSpecificData: Record<string, any>;
+}
+
+interface SocialAnalytics {
+    impressions: number;
+    engagements: number;
+    clicks: number;
+    shares: number;
+    comments: number;
+    likes: number;
+    reach: number;
+    saves?: number;
+    videoViews?: number;
+    platformMetrics: Record<string, any>;
+}
+
+interface SearchParams {
+    query?: string;
+    hashtags?: string[];
+    startDate?: Date;
+    endDate?: Date;
+    limit?: number;
+    offset?: number;
+}
+
+interface MediaFile {
+    filename: string;
+    mimeType: string;
+    data: Buffer | string; // Base64 or buffer
+    size: number;
+}
+```
+
+## Platform-Specific Implementation Details
+
+### HootSuite
+- **API Version**: v1
+- **Rate Limits**: 250 requests per hour
+- **Special Features**: Multi-platform posting, team collaboration
+- **Search Capabilities**: Full text search across connected accounts
+
+### Buffer
+- **API Version**: v1
+- **Rate Limits**: 600 requests per hour  
+- **Special Features**: Optimal timing suggestions, queue management
+- **Search Capabilities**: Search within scheduled and sent posts
+
+### LinkedIn
+- **API Version**: v2 (LinkedIn Marketing Developer Platform)
+- **Rate Limits**: Application-level and member-level limits
+- **Special Features**: Organization vs personal posts, article publishing
+- **Search Capabilities**: Search organization posts, limited personal post search
+
+### Twitter/X
+- **API Version**: v2
+- **Rate Limits**: Varies by endpoint (15-900 requests per 15 min)
+- **Special Features**: Thread creation, advanced search operators
+- **Search Capabilities**: Full Twitter search API with operators
+
+### Facebook
+- **API Version**: Graph API v18.0
+- **Rate Limits**: 200 calls per hour per user
+- **Special Features**: Page vs profile posts, boost capabilities
+- **Search Capabilities**: Search within page posts, limited by privacy
+
+### Instagram
+- **API Version**: Instagram Basic Display API + Graph API
+- **Rate Limits**: 200 calls per hour per user
+- **Special Features**: Stories, reels, shopping tags
+- **Search Capabilities**: Business account posts only
+
+### TikTok
+- **API Version**: Display API v2
+- **Rate Limits**: 1000 requests per day
+- **Special Features**: Video only, trending discovery
+- **Search Capabilities**: Limited to user's own videos
+
+### YouTube
+- **API Version**: Data API v3
+- **Rate Limits**: 10,000 quota units per day
+- **Special Features**: Video management, playlists, premieres
+- **Search Capabilities**: Full channel video search with filters
+
+## Error Handling
+
+All actions implement comprehensive error handling:
+
+```typescript
+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'
+}
+```
+
+## Usage Examples
+
+### Creating a Post
+```typescript
+const action = new CreatePostAction();
+await action.RunAction({
+    CompanyIntegrationID: 'abc-123',
+    ProfileID: 'page-456',
+    Content: 'Check out our new product!',
+    MediaFiles: [{
+        filename: 'product.jpg',
+        mimeType: 'image/jpeg',
+        data: base64Data,
+        size: 1024000
+    }],
+    ScheduledTime: '2024-01-15T10:00:00Z'
+});
+```
+
+### Searching Historical Posts
+```typescript
+const action = new SearchPostsAction();
+const result = await action.RunAction({
+    CompanyIntegrationID: 'abc-123',
+    Query: 'product launch',
+    StartDate: '2023-01-01',
+    EndDate: '2023-12-31',
+    Limit: 100
+});
+
+// Analyze content patterns
+const posts = result.Result as SocialPost[];
+const contentPatterns = analyzePostContent(posts);
+```
+
+### Getting Analytics
+```typescript
+const action = new GetPostAnalyticsAction();
+const result = await action.RunAction({
+    CompanyIntegrationID: 'abc-123',
+    PostID: 'post-789',
+    MetricTypes: ['impressions', 'engagements', 'clicks']
+});
+```
+
+## Development Guidelines
+
+1. **Credential Storage**: Always use CompanyIntegration for OAuth tokens
+2. **Rate Limiting**: Implement exponential backoff for rate limit errors
+3. **Media Handling**: Validate media size/format before upload
+4. **Error Messages**: Provide clear, actionable error messages
+5. **Logging**: Log all API requests for debugging
+6. **Testing**: Mock API responses for unit tests
+
+## Testing
+
+Each platform should have:
+- Unit tests for action logic
+- Integration tests with mock API responses
+- Manual testing checklist for OAuth flow
+- Performance tests for bulk operations
+
+## Future Enhancements
+
+1. **Webhook Support**: Real-time notifications for comments/mentions
+2. **Batch Operations**: Bulk post creation/scheduling
+3. **AI Integration**: Content suggestions based on historical performance
+4. **Cross-Platform Analytics**: Unified dashboard across all platforms
+5. **Content Calendar**: Visual planning interface
+
+## Contributing
+
+When adding new actions:
+1. Extend the appropriate base class
+2. Implement all required parameters
+3. Add comprehensive error handling
+4. Include search functionality where available
+5. Update metadata files
+6. Add unit tests
+7. Document any platform-specific quirks
+
+## License
+
+See MemberJunction main license.

package/dist/base/base-social.action.d.ts

@@ -0,0 +1,137 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { BaseOAuthAction } from '@memberjunction/actions';
+import { ActionParam } from '@memberjunction/actions-base';
+/**
+ * Common interfaces for social media actions
+ */
+export interface SocialPost {
+    id: string;
+    platform: string;
+    profileId: string;
+    content: string;
+    mediaUrls: string[];
+    publishedAt: Date;
+    scheduledFor?: Date;
+    analytics?: SocialAnalytics;
+    platformSpecificData: Record<string, any>;
+}
+export interface SocialAnalytics {
+    impressions: number;
+    engagements: number;
+    clicks: number;
+    shares: number;
+    comments: number;
+    likes: number;
+    reach: number;
+    saves?: number;
+    videoViews?: number;
+    platformMetrics: Record<string, any>;
+}
+export interface SearchParams {
+    query?: string;
+    hashtags?: string[];
+    startDate?: Date;
+    endDate?: Date;
+    limit?: number;
+    offset?: number;
+}
+export interface MediaFile {
+    filename: string;
+    mimeType: string;
+    data: Buffer | string;
+    size: number;
+}
+export declare 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"
+}
+/**
+ * Base class for all social media actions.
+ * Provides common functionality for authentication, media handling,
+ * analytics normalization, and rate limiting.
+ */
+export declare abstract class BaseSocialMediaAction extends BaseOAuthAction {
+    /**
+     * Common parameters for all social media actions
+     */
+    protected get commonSocialParams(): ActionParam[];
+    /**
+     * Get the platform name (e.g., 'Twitter', 'LinkedIn')
+     */
+    protected abstract get platformName(): string;
+    /**
+     * Get the API base URL for the platform
+     */
+    protected abstract get apiBaseUrl(): string;
+    /**
+     * Normalize platform-specific analytics to common format
+     */
+    protected normalizeAnalytics(platformData: any): SocialAnalytics;
+    /**
+     * Upload media files to the platform
+     */
+    protected uploadMedia(files: MediaFile[]): Promise<string[]>;
+    /**
+     * Platform-specific media upload implementation
+     */
+    protected abstract uploadSingleMedia(file: MediaFile): Promise<string>;
+    /**
+     * Validate media file meets platform requirements
+     */
+    protected validateMediaFile(file: MediaFile): void;
+    /**
+     * Handle rate limiting with exponential backoff
+     */
+    protected handleRateLimit(retryAfter?: number): Promise<void>;
+    /**
+     * Search for posts on the platform
+     */
+    protected abstract searchPosts(params: SearchParams): Promise<SocialPost[]>;
+    /**
+     * Convert platform-specific post data to common format
+     */
+    protected abstract normalizePost(platformPost: any): SocialPost;
+    /**
+     * Parse rate limit headers from API response
+     */
+    protected parseRateLimitHeaders(headers: any): {
+        remaining: number;
+        reset: Date;
+        limit: number;
+    } | null;
+    /**
+     * Build common API headers including authentication
+     */
+    protected buildHeaders(additionalHeaders?: Record<string, string>): Record<string, string>;
+    /**
+     * Format date for API requests (ISO 8601)
+     */
+    protected formatDate(date: Date | string): string;
+    /**
+     * Parse date from API response
+     */
+    protected parseDate(dateString: string): Date;
+    /**
+     * Get profile ID from parameters or default from integration
+     */
+    protected getProfileId(params: any): string;
+    /**
+     * Log API request for debugging
+     */
+    protected logApiRequest(method: string, url: string, data?: any): void;
+    /**
+     * Log API response for debugging
+     */
+    protected logApiResponse(response: any): void;
+    /**
+     * Helper to get parameter value from params array
+     */
+    protected getParamValue(params: ActionParam[], paramName: string): any;
+}
+//# sourceMappingURL=base-social.action.d.ts.map

package/dist/base/base-social.action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-social.action.d.ts","sourceRoot":"","sources":["../../src/base/base-social.action.ts"],"names":[],"mappings":"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"}