@splendidlabz/third-party 1.3.9 → 1.3.10

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @splendidlabz/third-party
 
+## 1.3.10
+
+### Patch Changes
+
+- Updated dependencies
+  - @splendidlabz/utils@1.10.4
+
 ## 1.3.9
 
 ### Patch Changes

package/lib/logger.js

@@ -3,7 +3,10 @@ import pino from 'pino'
 // Potentially can put into logtail for production
 // Potentially can use pino-http for logging requests
 
-const isDev = import.meta.env.DEV
+const isDev =
+  process.env.NODE_ENV === 'development' ||
+  import.meta.env?.DEV === true ||
+  import.meta.env?.MODE === 'development'
 
 export function createLogger({ verbose = false, level = 'info' } = {}) {
   return pino({

package/lib/social/README.md

@@ -0,0 +1,107 @@
+# Social Media Content Automation
+
+Automate posting content across Twitter, Threads, and Instagram with platform-specific formatting.
+
+## Features
+
+- **Content formatting**: Automatically formats content for each platform's requirements
+- **Thread support**: Splits long content into Twitter/Threads threads
+- **Cross-platform**: Post to multiple platforms from one content object
+- **Dry run mode**: Preview content before posting
+
+## Usage
+
+### Basic Example
+
+```js
+import { formatContent, postToPlatforms, createTwitter, createInstagram } from '@splendidlabz/third-party/social'
+
+// Define your content once
+const content = {
+  title: 'CSS trick that saved me 2 hours',
+  points: [
+    'Use `:has()` selector for conditional styling',
+    'No JavaScript needed',
+    'Works in all modern browsers',
+  ],
+  hashtags: ['webdev', 'css', 'frontend'],
+  link: 'https://example.com/tutorial',
+  videoUrl: 'https://example.com/video.mp4', // For Instagram
+}
+
+// Format for all platforms
+const formatted = formatContent(content)
+console.log(formatted.twitter)  // Thread format
+console.log(formatted.instagram) // Caption + first comment
+```
+
+### Posting to Platforms
+
+```js
+// Set up clients
+const twitter = createTwitter({
+  bearerToken: process.env.TWITTER_BEARER_TOKEN,
+})
+
+const instagram = createInstagram({
+  accessToken: process.env.INSTAGRAM_ACCESS_TOKEN,
+  instagramAccountId: process.env.INSTAGRAM_ACCOUNT_ID,
+})
+
+// Post to all platforms
+const results = await postToPlatforms(
+  content,
+  { twitter, instagram },
+  { dryRun: true } // Preview first
+)
+```
+
+### Platform-Specific Formatting
+
+**Twitter/Threads:**
+- Auto-splits into threads if content is too long
+- Adds hashtags at the end
+- Includes link if provided
+
+**Instagram:**
+- Formats as caption with numbered points
+- Adds hashtags (10-20 recommended)
+- Generates first comment for engagement
+- Requires video URL for Reels
+
+## API Setup
+
+### Twitter/X API
+
+1. Create a Twitter Developer account
+2. Create an app and get Bearer Token
+3. For OAuth 1.0a, get API Key, Secret, Access Token, and Access Token Secret
+
+### Instagram Graph API
+
+1. Create a Facebook App
+2. Get Instagram Business Account ID
+3. Generate Access Token with `instagram_basic`, `instagram_content_publish`, `pages_read_engagement` permissions
+4. Note: Video URLs must be publicly accessible
+
+## Content Object Structure
+
+```js
+{
+  title: string,        // Main hook/title (required)
+  points: string[],     // Key points (optional)
+  hashtags: string[],   // Hashtags without # (optional)
+  link: string,         // Link to full content (optional)
+  videoUrl: string,     // Video URL for Instagram (optional)
+}
+```
+
+## Notes
+
+- Twitter API v2 requires authentication
+- Instagram Reels require video to be publicly accessible
+- Threads can use the same client as Twitter (Meta API)
+- Use `dryRun: true` to preview before posting
+- Rate limits apply - the system includes delays for threads
+
+

package/lib/social/content-formatter.js

@@ -0,0 +1,161 @@
+/**
+ * Formats content for different social media platforms
+ * @param {Object} content - Base content object
+ * @param {string} content.title - Main title/hook
+ * @param {string[]} content.points - Array of key points
+ * @param {string} [content.videoUrl] - Video URL for Instagram
+ * @param {string[]} [content.hashtags] - Hashtags to include
+ * @param {string} [content.link] - Link to full content
+ * @param {Object} [options] - Formatting options
+ * @return {Object} Platform-specific formatted content
+ */
+export function formatContent(content, options = {}) {
+  const { title, points = [], videoUrl, hashtags = [], link } = content
+  const { maxThreadLength = 280, maxInstagramLength = 2200 } = options
+
+  return {
+    twitter: formatTwitter({
+      title,
+      points,
+      hashtags,
+      link,
+      maxLength: maxThreadLength,
+    }),
+    threads: formatThreads({
+      title,
+      points,
+      hashtags,
+      link,
+      maxLength: maxThreadLength,
+    }),
+    instagram: formatInstagram({
+      title,
+      points,
+      videoUrl,
+      hashtags,
+      link,
+      maxLength: maxInstagramLength,
+    }),
+  }
+}
+
+/**
+ * Formats content for Twitter/X
+ * @param {Object} params
+ * @return {Object} Formatted Twitter content
+ */
+function formatTwitter({ title, points, hashtags, link, maxLength }) {
+  const hashtagStr =
+    hashtags.length > 0 ? '\n\n' + hashtags.map(h => `#${h}`).join(' ') : ''
+  const linkStr = link ? `\n\n${link}` : ''
+
+  // Single tweet if short enough
+  const singleTweet = title + hashtagStr + linkStr
+  if (singleTweet.length <= maxLength) {
+    return {
+      type: 'single',
+      content: [singleTweet],
+    }
+  }
+
+  // Thread format
+  const thread = [title]
+
+  points.forEach((point, i) => {
+    const num = `${i + 1}/${points.length}`
+    const tweet = `${num} ${point}`
+    thread.push(tweet)
+  })
+
+  if (link) thread.push(`🔗 Full post: ${link}`)
+  if (hashtags.length > 0) {
+    const hashtagTweet = hashtags.map(h => `#${h}`).join(' ')
+    thread.push(hashtagTweet)
+  }
+
+  return {
+    type: 'thread',
+    content: thread,
+  }
+}
+
+/**
+ * Formats content for Threads (similar to Twitter but slightly different)
+ * @param {Object} params
+ * @return {Object} Formatted Threads content
+ */
+function formatThreads({ title, points, hashtags, link, maxLength }) {
+  // Threads allows longer posts, but similar format
+  return formatTwitter({
+    title,
+    points,
+    hashtags,
+    link,
+    maxLength: maxLength * 2,
+  })
+}
+
+/**
+ * Formats content for Instagram
+ * @param {Object} params
+ * @return {Object} Formatted Instagram content
+ */
+function formatInstagram({
+  title,
+  points,
+  videoUrl,
+  hashtags,
+  link,
+  maxLength,
+}) {
+  let caption = title + '\n\n'
+
+  if (points.length > 0) {
+    caption += points.map((p, i) => `${i + 1}. ${p}`).join('\n\n') + '\n\n'
+  }
+
+  if (link) caption += `🔗 Link in bio: ${link}\n\n`
+
+  // Instagram hashtags (10-20 recommended)
+  const instagramHashtags = hashtags.slice(0, 20)
+  if (instagramHashtags.length > 0) {
+    caption += instagramHashtags.map(h => `#${h}`).join(' ')
+  }
+
+  // Instagram comment (first comment strategy)
+  const firstComment = link
+    ? `Full tutorial: ${link}\n\nWhat would you like to see next? 👇`
+    : `What would you like to see next? 👇`
+
+  return {
+    caption: caption.trim(),
+    firstComment,
+    videoUrl,
+  }
+}
+
+/**
+ * Splits long text into thread chunks
+ * @param {string} text - Text to split
+ * @param {number} maxLength - Maximum length per chunk
+ * @return {string[]} Array of text chunks
+ */
+export function splitIntoThread(text, maxLength = 280) {
+  const sentences = text.split(/[.!?]\s+/)
+  const chunks = []
+  let currentChunk = ''
+
+  sentences.forEach(sentence => {
+    const testChunk = currentChunk ? `${currentChunk}. ${sentence}` : sentence
+
+    if (testChunk.length <= maxLength) {
+      currentChunk = testChunk
+    } else {
+      if (currentChunk) chunks.push(currentChunk)
+      currentChunk = sentence
+    }
+  })
+
+  if (currentChunk) chunks.push(currentChunk)
+  return chunks
+}

package/lib/social/example.js

@@ -0,0 +1,49 @@
+/**
+ * Example usage of social media automation
+ * 
+ * This shows how to format and post content across platforms
+ */
+
+import { formatContent, postToPlatforms, createTwitter, createInstagram } from './index.js'
+
+// Example: Create your content once
+const content = {
+  title: 'CSS trick that saved me 2 hours yesterday',
+  points: [
+    'Use `:has()` selector to style parent based on child',
+    'No JavaScript needed for conditional styling',
+    'Works in all modern browsers now',
+  ],
+  hashtags: ['webdev', 'css', 'frontend', 'coding'],
+  link: 'https://example.com/full-tutorial',
+  videoUrl: 'https://example.com/video.mp4', // For Instagram
+}
+
+// Format for all platforms
+const formatted = formatContent(content)
+console.log('Twitter:', formatted.twitter)
+console.log('Instagram:', formatted.instagram)
+
+// Example: Set up clients
+const twitter = createTwitter({
+  bearerToken: process.env.TWITTER_BEARER_TOKEN,
+})
+
+const instagram = createInstagram({
+  accessToken: process.env.INSTAGRAM_ACCESS_TOKEN,
+  instagramAccountId: process.env.INSTAGRAM_ACCOUNT_ID,
+})
+
+// Post to all platforms (dry run first)
+const results = await postToPlatforms(
+  content,
+  { twitter, instagram },
+  { dryRun: true }
+)
+
+console.log('Preview results:', results)
+
+// When ready, post for real
+// const realResults = await postToPlatforms(content, { twitter, instagram })
+
+

package/lib/social/index.js

@@ -0,0 +1,73 @@
+/**
+ * Social media content automation
+ * Formats and posts content across multiple platforms
+ */
+
+export { formatContent, splitIntoThread } from './content-formatter.js'
+export { createTwitter } from './twitter.js'
+export { createThreads } from './threads.js'
+export { createInstagram } from './instagram.js'
+
+/**
+ * Orchestrates posting to multiple platforms
+ * @param {Object} content - Base content (see content-formatter.js)
+ * @param {Object} clients - Platform clients
+ * @param {Object} [clients.twitter] - Twitter client instance
+ * @param {Object} [clients.threads] - Threads client (can use Twitter client)
+ * @param {Object} [clients.instagram] - Instagram client instance
+ * @param {Object} [options] - Posting options
+ * @param {boolean} [options.dryRun] - Preview without posting
+ * @return {Promise<Object>} Results from each platform
+ */
+export async function postToPlatforms(content, clients, options = {}) {
+  const { dryRun = false } = options
+  const formatted = formatContent(content)
+  const results = {}
+
+  // Post to Twitter
+  if (clients.twitter && formatted.twitter) {
+    if (dryRun) {
+      results.twitter = { preview: formatted.twitter }
+    } else {
+      // Twitter client handles both single tweets and arrays
+      results.twitter = await clients.twitter.post(formatted.twitter.content)
+    }
+  }
+
+  // Post to Threads
+  if (clients.threads && formatted.threads) {
+    if (dryRun) {
+      results.threads = { preview: formatted.threads }
+    } else {
+      const threadsClient = clients.threads
+      // Threads content is same format as Twitter
+      // For single post, join content; for thread, use array
+      const threadsContent = formatted.threads.type === 'single'
+        ? formatted.threads.content[0]
+        : formatted.threads.content
+      results.threads = await threadsClient.post(threadsContent)
+    }
+  }
+
+  // Post to Instagram
+  if (clients.instagram && formatted.instagram) {
+    if (dryRun) {
+      results.instagram = { preview: formatted.instagram }
+    } else {
+      const { caption, videoUrl, firstComment } = formatted.instagram
+      
+      // Post the reel
+      const reel = await clients.instagram.postReel(videoUrl, caption)
+      
+      // Add first comment if provided
+      if (firstComment && reel.id) {
+        await clients.instagram.addComment(reel.id, firstComment)
+      }
+      
+      results.instagram = reel
+    }
+  }
+
+  return results
+}
+

package/lib/social/instagram.js

@@ -0,0 +1,105 @@
+import { createZlFetch } from 'zl-fetch'
+
+/**
+ * Creates an Instagram Graph API client
+ * Note: Instagram API requires Facebook App setup and access tokens
+ * @param {Object} config - Configuration
+ * @param {string} config.accessToken - Instagram Graph API Access Token
+ * @param {string} config.instagramAccountId - Instagram Business Account ID
+ * @return {Object} Instagram client
+ */
+export function createInstagram({ accessToken, instagramAccountId }) {
+  const BASE_URL = 'https://graph.facebook.com/v19.0'
+  
+  const instagram = createZlFetch(BASE_URL, {
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    returnError: true,
+  })
+
+  return {
+    /**
+     * Create a media container (step 1 of posting)
+     * @param {string} videoUrl - URL to video file
+     * @param {string} caption - Post caption
+     * @return {Promise<Object>} Container creation response
+     */
+    async createVideoContainer(videoUrl, caption) {
+      const { response, error } = await instagram.post(
+        `/${instagramAccountId}/media`,
+        {
+          query: {
+            access_token: accessToken,
+            media_type: 'REELS',
+            video_url: videoUrl,
+            caption,
+          },
+        }
+      )
+
+      if (response) return response.body
+      if (error) throw error
+    },
+
+    /**
+     * Publish a media container (step 2 of posting)
+     * @param {string} creationId - Container creation ID from step 1
+     * @return {Promise<Object>} Publishing response
+     */
+    async publishContainer(creationId) {
+      const { response, error } = await instagram.post(
+        `/${instagramAccountId}/media_publish`,
+        {
+          query: {
+            access_token: accessToken,
+            creation_id: creationId,
+          },
+        }
+      )
+
+      if (response) return response.body
+      if (error) throw error
+    },
+
+    /**
+     * Post a Reel (two-step process)
+     * @param {string} videoUrl - URL to video file (must be publicly accessible)
+     * @param {string} caption - Post caption
+     * @return {Promise<Object>} Post response
+     */
+    async postReel(videoUrl, caption) {
+      // Step 1: Create container
+      const container = await this.createVideoContainer(videoUrl, caption)
+      
+      // Step 2: Publish (may need to wait for processing)
+      // In production, you'd want to poll status or use webhooks
+      const published = await this.publishContainer(container.id)
+      
+      return published
+    },
+
+    /**
+     * Add a comment to a post
+     * @param {string} mediaId - Instagram media ID
+     * @param {string} text - Comment text
+     * @return {Promise<Object>} Comment response
+     */
+    async addComment(mediaId, text) {
+      const { response, error } = await instagram.post(
+        `/${mediaId}/comments`,
+        {
+          query: {
+            access_token: accessToken,
+            message: text,
+          },
+        }
+      )
+
+      if (response) return response.body
+      if (error) throw error
+    },
+  }
+}
+
+

package/lib/social/threads.js

@@ -0,0 +1,110 @@
+import { createZlFetch } from 'zl-fetch'
+
+/**
+ * Creates a Threads API client
+ * Note: Threads API is part of Meta's Graph API
+ * @param {Object} config - Configuration
+ * @param {string} config.accessToken - Meta Access Token
+ * @param {string} config.threadsUserId - Threads User ID (your account ID)
+ * @return {Object} Threads client
+ */
+export function createThreads({ accessToken, threadsUserId }) {
+  const BASE_URL = 'https://graph.threads.net/v1.0'
+  
+  const threads = createZlFetch(BASE_URL, {
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    returnError: true,
+  })
+
+  return {
+    /**
+     * Create a media container (step 1 of posting)
+     * @param {string} text - Thread text
+     * @param {string} [mediaType] - 'TEXT' or 'IMAGE' (default: 'TEXT')
+     * @return {Promise<Object>} Container creation response
+     */
+    async createContainer(text, mediaType = 'TEXT') {
+      const { response, error } = await threads.post(
+        `/${threadsUserId}/threads`,
+        {
+          query: {
+            access_token: accessToken,
+            media_type: mediaType,
+            text,
+          },
+        }
+      )
+
+      if (response) return response.body
+      if (error) throw error
+    },
+
+    /**
+     * Publish a media container (step 2 of posting)
+     * @param {string} creationId - Container creation ID from step 1
+     * @return {Promise<Object>} Publishing response
+     */
+    async publishContainer(creationId) {
+      const { response, error } = await threads.post(
+        `/${threadsUserId}/threads_publish`,
+        {
+          query: {
+            access_token: accessToken,
+            creation_id: creationId,
+          },
+        }
+      )
+
+      if (response) return response.body
+      if (error) throw error
+    },
+
+    /**
+     * Post a thread (two-step process)
+     * @param {string} text - Thread text
+     * @return {Promise<Object>} Post response
+     */
+    async postThread(text) {
+      // Step 1: Create container
+      const container = await this.createContainer(text)
+      
+      // Step 2: Publish
+      const published = await this.publishContainer(container.id)
+      
+      return published
+    },
+
+    /**
+     * Post content (can be string or array for thread replies)
+     * @param {string|string[]} content - Single post or array for replies
+     * @return {Promise<Object|Object[]>} Post response(s)
+     */
+    async post(content) {
+      if (Array.isArray(content)) {
+        // For threads, you'd need to reply to previous post
+        // This is a simplified version - full implementation would track reply IDs
+        const results = []
+        let parentId = null
+        
+        for (const text of content) {
+          // Note: Threads API reply structure may differ
+          // This is a placeholder for the actual implementation
+          const result = await this.postThread(text)
+          results.push(result)
+          // Add delay between posts
+          if (content.length > 1) {
+            await new Promise(resolve => setTimeout(resolve, 1000))
+          }
+        }
+        
+        return results
+      }
+      
+      return this.postThread(content)
+    },
+  }
+}
+
+

package/lib/social/twitter.js

@@ -0,0 +1,90 @@
+import { createZlFetch } from 'zl-fetch'
+
+/**
+ * Creates a Twitter/X API client
+ * @param {Object} config - Configuration
+ * @param {string} config.bearerToken - Twitter Bearer Token
+ * @param {string} [config.apiKey] - API Key (for OAuth 1.0a)
+ * @param {string} [config.apiSecret] - API Secret (for OAuth 1.0a)
+ * @param {string} [config.accessToken] - Access Token (for OAuth 1.0a)
+ * @param {string} [config.accessTokenSecret] - Access Token Secret (for OAuth 1.0a)
+ * @return {Object} Twitter client
+ */
+export function createTwitter({
+  bearerToken,
+  apiKey,
+  apiSecret,
+  accessToken,
+  accessTokenSecret,
+}) {
+  const BASE_URL = 'https://api.twitter.com/2'
+
+  // Use OAuth 1.0a if credentials provided, otherwise Bearer token
+  const useOAuth = apiKey && apiSecret && accessToken && accessTokenSecret
+
+  const twitter = createZlFetch(BASE_URL, {
+    headers: {
+      'Content-Type': 'application/json',
+      ...(bearerToken && !useOAuth
+        ? { Authorization: `Bearer ${bearerToken}` }
+        : {}),
+    },
+    returnError: true,
+  })
+
+  return {
+    /**
+     * Post a single tweet
+     * @param {string} text - Tweet text
+     * @param {Object} [options] - Additional options
+     * @return {Promise<Object>} Tweet response
+     */
+    async postTweet(text, options = {}) {
+      const { response, error } = await twitter.post('/tweets', {
+        body: {
+          text,
+          ...options,
+        },
+      })
+
+      if (response) return response.body
+      if (error) throw error
+    },
+
+    /**
+     * Post a thread (reply chain)
+     * @param {string[]} tweets - Array of tweet texts
+     * @return {Promise<Object[]>} Array of tweet responses
+     */
+    async postThread(tweets) {
+      const results = []
+      let replyToId = null
+
+      for (const tweet of tweets) {
+        const options = replyToId
+          ? { reply: { in_reply_to_tweet_id: replyToId } }
+          : {}
+        const result = await this.postTweet(tweet, options)
+        replyToId = result.data?.id
+        results.push(result)
+
+        // Small delay between tweets to avoid rate limits
+        if (tweets.length > 1) {
+          await new Promise(resolve => setTimeout(resolve, 1000))
+        }
+      }
+
+      return results
+    },
+
+    /**
+     * Post content (auto-detects single vs thread)
+     * @param {string|string[]} content - Single tweet or array for thread
+     * @return {Promise<Object|Object[]>} Tweet response(s)
+     */
+    async post(content) {
+      if (Array.isArray(content)) return this.postThread(content)
+      return this.postTweet(content)
+    },
+  }
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@splendidlabz/third-party",
   "prettier": "@splendidlabz/prettier-config",
-  "version": "1.3.9",
+  "version": "1.3.10",
   "description": "",
   "type": "module",
   "main": "index.js",
   "sideEffects": false,
   "exports": {
-    "./*": "./lib/*.js"
+    "./*": "./lib/*.js",
+    "./social": "./lib/social/index.js"
   },
   "scripts": {
     "lint": "eslint . --fix",
@@ -16,7 +17,7 @@
   },
   "author": "Zell Liew <zellwk@gmail.com>",
   "dependencies": {
-    "@splendidlabz/utils": "1.10.3",
+    "@splendidlabz/utils": "1.10.4",
     "googleapis": "^148.0.0",
     "http-errors": "^2.0.0",
     "pino": "^9.7.0",