universal-social-sdk 1.0.0

package/.env.example

@@ -0,0 +1,61 @@
+# X / Twitter
+X_API_KEY=
+X_API_SECRET=
+X_ACCESS_TOKEN=
+X_ACCESS_SECRET=
+X_BEARER_TOKEN=
+X_CLIENT_ID=
+X_CLIENT_SECRET=
+
+# Facebook Pages + Instagram Graph (Meta)
+META_APP_ID=
+META_APP_SECRET=
+FB_PAGE_ACCESS_TOKEN=
+FB_PAGE_ID=
+IG_ACCESS_TOKEN=
+IG_USER_ID=
+META_GRAPH_VERSION=v21.0
+
+# LinkedIn
+LINKEDIN_ACCESS_TOKEN=
+LINKEDIN_REFRESH_TOKEN=
+LINKEDIN_CLIENT_ID=
+LINKEDIN_CLIENT_SECRET=
+LINKEDIN_ORG_URN=
+LINKEDIN_PERSON_URN=
+LINKEDIN_API_VERSION=202510
+
+# YouTube
+YOUTUBE_ACCESS_TOKEN=
+YOUTUBE_CHANNEL_ID=
+
+# TikTok
+TIKTOK_ACCESS_TOKEN=
+TIKTOK_OPEN_ID=
+TIKTOK_ADVERTISER_ID=
+
+# Pinterest
+PINTEREST_ACCESS_TOKEN=
+PINTEREST_BOARD_ID=
+
+# Bluesky
+BLUESKY_SERVICE_URL=https://bsky.social
+BLUESKY_IDENTIFIER=
+BLUESKY_APP_PASSWORD=
+BLUESKY_ACCESS_JWT=
+BLUESKY_REFRESH_JWT=
+
+# Mastodon
+MASTODON_BASE_URL=
+MASTODON_ACCESS_TOKEN=
+MASTODON_ACCOUNT_ID=
+
+# Threads
+THREADS_ACCESS_TOKEN=
+THREADS_USER_ID=
+
+# SDK behavior
+SOCIAL_SDK_MAX_RETRIES=3
+SOCIAL_SDK_RETRY_BASE_MS=500
+OLLAMA_HOST=http://127.0.0.1:11434
+OLLAMA_MODEL=llama3.2:3b

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabo-Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,329 @@
+# universal-social-sdk
+
+TypeScript-first, ESM-only, zero-bloat Node.js SDK that provides one unified interface for X, Facebook, Instagram, LinkedIn, YouTube, TikTok, Pinterest, Bluesky, Mastodon, and Threads.
+
+[![CI](https://github.com/Gabo-Tech/universal-social-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/Gabo-Tech/universal-social-sdk/actions/workflows/ci.yml)
+[![Release](https://github.com/Gabo-Tech/universal-social-sdk/actions/workflows/release.yml/badge.svg)](https://github.com/Gabo-Tech/universal-social-sdk/actions/workflows/release.yml)
+
+## Documentation
+
+- [Project Structure](./docs/PROJECT_STRUCTURE.md)
+- [NPM Package Guide](./docs/NPM_PACKAGE_GUIDE.md)
+- [Contributing](./docs/CONTRIBUTING.md)
+- [Code of Conduct](./CODE_OF_CONDUCT.md)
+- [Security Policy](./SECURITY.md)
+
+## Install
+
+```bash
+npm install universal-social-sdk
+```
+
+## Quick Start
+
+```ts
+import { Instagram, X, Facebook, LinkedIn } from "universal-social-sdk";
+
+await X.postTweet({ text: "Hello from universal SDK!" });
+await Instagram.uploadReel({
+  videoUrl: "https://example.com/reel.mp4",
+  caption: "Hello world"
+});
+await Facebook.publishToPage({
+  message: "Shipping updates from one SDK"
+});
+await LinkedIn.createTextPost({
+  text: "Cross-platform publishing with one API"
+});
+
+import { YouTube, TikTok, Pinterest, Bluesky, Mastodon, Threads } from "universal-social-sdk";
+
+await YouTube.listMyVideos({ maxResults: 5 });
+await TikTok.listVideos({ maxCount: 10 });
+await Pinterest.listBoards({});
+await Bluesky.postText({ text: "Hello AT Protocol!" });
+await Mastodon.createStatus({ text: "Hello Fediverse!" });
+await Threads.postText({ text: "Hello Threads!" });
+```
+
+## Required Environment Variables
+
+`universal-social-sdk` auto-loads `.env` with `dotenv`.
+
+### X / Twitter
+
+- `X_API_KEY`
+- `X_API_SECRET`
+- `X_ACCESS_TOKEN`
+- `X_ACCESS_SECRET`
+- `X_BEARER_TOKEN` (optional for some read-only operations)
+- `X_CLIENT_ID` (OAuth 2 workflows)
+- `X_CLIENT_SECRET` (OAuth 2 workflows)
+
+### Meta (Facebook Pages + Instagram Graph)
+
+- `META_APP_ID`
+- `META_APP_SECRET`
+- `FB_PAGE_ACCESS_TOKEN`
+- `FB_PAGE_ID`
+- `IG_ACCESS_TOKEN`
+- `IG_USER_ID`
+- `META_GRAPH_VERSION` (default `v21.0`)
+
+### LinkedIn
+
+- `LINKEDIN_ACCESS_TOKEN`
+- `LINKEDIN_REFRESH_TOKEN` (recommended for long-running apps)
+- `LINKEDIN_CLIENT_ID`
+- `LINKEDIN_CLIENT_SECRET`
+- `LINKEDIN_ORG_URN` or `LINKEDIN_PERSON_URN`
+- `LINKEDIN_API_VERSION` (default `202510`)
+
+### YouTube
+
+- `YOUTUBE_ACCESS_TOKEN`
+- `YOUTUBE_CHANNEL_ID`
+
+### TikTok
+
+- `TIKTOK_ACCESS_TOKEN`
+- `TIKTOK_OPEN_ID`
+- `TIKTOK_ADVERTISER_ID`
+
+### Pinterest
+
+- `PINTEREST_ACCESS_TOKEN`
+- `PINTEREST_BOARD_ID`
+
+### Bluesky
+
+- `BLUESKY_SERVICE_URL` (default `https://bsky.social`)
+- `BLUESKY_IDENTIFIER`
+- `BLUESKY_APP_PASSWORD`
+- `BLUESKY_ACCESS_JWT`
+- `BLUESKY_REFRESH_JWT`
+
+### Mastodon
+
+- `MASTODON_BASE_URL`
+- `MASTODON_ACCESS_TOKEN`
+- `MASTODON_ACCOUNT_ID`
+
+### Threads
+
+- `THREADS_ACCESS_TOKEN`
+- `THREADS_USER_ID`
+
+### SDK / Updater
+
+- `SOCIAL_SDK_MAX_RETRIES` (default `3`)
+- `SOCIAL_SDK_RETRY_BASE_MS` (default `500`)
+- `OLLAMA_HOST` (default `http://127.0.0.1:11434`)
+- `OLLAMA_MODEL` (default `llama3.2:3b`)
+
+## CLI
+
+### Bootstrap
+
+```bash
+npx universal-social-sdk init
+```
+
+Creates `.env.example`, copies it to `.env` if missing, and prints OAuth setup links:
+
+- X Developer Portal: <https://developer.x.com/en/portal/dashboard>
+- Meta Developers: <https://developers.facebook.com/apps/>
+- LinkedIn Developers: <https://www.linkedin.com/developers/apps>
+
+### Documentation Updater
+
+```bash
+npx universal-social-sdk update
+```
+
+```bash
+npx universal-social-sdk update --dry-run
+npx universal-social-sdk update --model llama3.2
+npx universal-social-sdk update --yes
+```
+
+Flow:
+
+1. Crawls official docs pages for X, Meta Graph API, Instagram Graph API, and LinkedIn.
+2. Extracts clean text and table-like endpoint data with Cheerio.
+3. Sends doc snapshots to your local model runtime.
+4. Requests generated method updates + full TypeScript file content.
+5. Shows git-style diffs and asks for confirmation.
+6. Applies patches and rebuilds package.
+
+## Supported Methods
+
+Method coverage by platform:
+
+- `X`: posting, threads, replies, quote posts, likes, retweets, DMs, analytics, scheduling
+- `Facebook`: page publishing, stories, comments, reactions, insights, scheduled posts
+- `Instagram`: media/reels/stories, carousels, comments, moderation, insights
+- `LinkedIn`: text/image/video/carousel posts, comments, likes, analytics, media upload
+- `YouTube`: upload sessions, metadata updates, playlists, comments, channel analytics
+- `TikTok`: video publish flow, comments/replies, likes, status checks, analytics
+- `Pinterest`: pin/board management, comments/replies, pin/account analytics
+- `Bluesky`: text posts, links, replies, likes/reposts, feed/search/thread retrieval
+- `Mastodon`: statuses, media posts, favourites/boosts, context, scheduling
+- `Threads`: text/image/video posts, replies, likes, thread/account insights
+
+Complete method list is maintained in `supported-methods.json`.
+
+## OAuth Setup Guide
+
+### X
+
+1. Open <https://developer.x.com/en/portal/dashboard>.
+2. Create a Project and App.
+3. Enable OAuth 1.0a and OAuth 2.0, then generate user tokens.
+4. Add credentials into `.env`.
+5. Screenshot to keep: App keys and user token generation page.
+
+### Meta (Facebook + Instagram Graph)
+
+1. Open <https://developers.facebook.com/apps/>.
+2. Create app, add Facebook Login + Instagram Graph API products.
+3. Get Page access token (`pages_manage_posts`, `pages_read_engagement`, etc.).
+4. Map Page to Instagram professional account and capture `IG_USER_ID`.
+5. Screenshot to keep: App Review permissions and Access Token Debugger output.
+
+### LinkedIn
+
+1. Open <https://www.linkedin.com/developers/apps>.
+2. Create app and add Marketing APIs / Community Management products.
+3. Configure OAuth 2.0 redirect URLs and request required scopes.
+4. Exchange auth code for access token (and refresh token if enabled).
+5. Screenshot to keep: Products enabled page + OAuth scopes configuration.
+
+### YouTube
+
+1. Open <https://console.cloud.google.com/apis/library/youtube.googleapis.com>.
+2. Enable YouTube Data API v3 for your project.
+3. Configure OAuth consent and create OAuth client credentials.
+4. Exchange user authorization for `YOUTUBE_ACCESS_TOKEN`.
+
+### TikTok
+
+1. Open <https://developers.tiktok.com/>.
+2. Create app, configure login scopes and redirect URI.
+3. Complete OAuth flow and store long-lived `TIKTOK_ACCESS_TOKEN`.
+
+### Pinterest
+
+1. Open <https://developers.pinterest.com/>.
+2. Create app and configure OAuth redirect URI/scopes.
+3. Obtain `PINTEREST_ACCESS_TOKEN` and target `PINTEREST_BOARD_ID`.
+
+### Bluesky
+
+1. Open <https://bsky.app/settings/app-passwords>.
+2. Create an app password for your account.
+3. Set `BLUESKY_IDENTIFIER` and `BLUESKY_APP_PASSWORD`.
+
+### Mastodon
+
+1. Register an application on your Mastodon instance.
+2. Generate an access token with write/read scopes.
+3. Set `MASTODON_BASE_URL`, `MASTODON_ACCESS_TOKEN`, and `MASTODON_ACCOUNT_ID`.
+
+### Threads
+
+1. Open <https://developers.facebook.com/docs/threads>.
+2. Create app, request Threads API scopes, and generate user token.
+3. Set `THREADS_ACCESS_TOKEN` and `THREADS_USER_ID`.
+
+## Error Handling
+
+All errors are normalized to `SocialError`.
+
+```ts
+import { SocialError, X } from "universal-social-sdk";
+
+try {
+  await X.postTweet({ text: "hello" });
+} catch (error) {
+  if (error instanceof SocialError) {
+    console.error(error.platform, error.endpoint, error.message, error.statusCode);
+  }
+}
+```
+
+## Rate Limit Handling
+
+- Automatic retries on `429` and `5xx`.
+- Exponential backoff defaults: `500ms`, `1000ms`, `2000ms`.
+- Configure with:
+  - `SOCIAL_SDK_MAX_RETRIES`
+  - `SOCIAL_SDK_RETRY_BASE_MS`
+
+## Legal / Terms Notes
+
+- You must comply with each platform’s Terms of Use, policy docs, and display requirements.
+- Some actions require app review, partner approval, business verification, or specific account types.
+- Messaging APIs (especially DMs) are often restricted to approved use cases.
+
+## Testing
+
+```bash
+npm run test:unit
+npm run test:integration
+```
+
+Integration tests are environment-gated. Create `.env.test` from `.env.test.example` and use sandbox credentials.
+
+### Integration Test Env Matrix
+
+| Platform | Required `.env.test` keys | Required CI secrets |
+| --- | --- | --- |
+| X | `X_API_KEY`, `X_API_SECRET`, `X_ACCESS_TOKEN`, `X_ACCESS_SECRET`, `X_TEST_TWEET_ID` | `X_API_KEY`, `X_API_SECRET`, `X_ACCESS_TOKEN`, `X_ACCESS_SECRET`, `X_TEST_TWEET_ID` |
+| Facebook | `FB_PAGE_ACCESS_TOKEN`, `FB_PAGE_ID` | `FB_PAGE_ACCESS_TOKEN`, `FB_PAGE_ID` |
+| Instagram | `IG_ACCESS_TOKEN`, `IG_USER_ID` | `IG_ACCESS_TOKEN`, `IG_USER_ID` |
+| LinkedIn | `LINKEDIN_ACCESS_TOKEN`, `LINKEDIN_ORG_URN` | `LINKEDIN_ACCESS_TOKEN`, `LINKEDIN_ORG_URN` |
+| YouTube | `YOUTUBE_ACCESS_TOKEN`, `YOUTUBE_CHANNEL_ID` | `YOUTUBE_ACCESS_TOKEN`, `YOUTUBE_CHANNEL_ID` |
+| TikTok | `TIKTOK_ACCESS_TOKEN` | `TIKTOK_ACCESS_TOKEN` |
+| Pinterest | `PINTEREST_ACCESS_TOKEN`, `PINTEREST_BOARD_ID` | `PINTEREST_ACCESS_TOKEN`, `PINTEREST_BOARD_ID` |
+| Bluesky | `BLUESKY_IDENTIFIER`, `BLUESKY_APP_PASSWORD` (`BLUESKY_TEST_ACTOR` optional) | `BLUESKY_IDENTIFIER`, `BLUESKY_APP_PASSWORD`, `BLUESKY_TEST_ACTOR` |
+| Mastodon | `MASTODON_BASE_URL`, `MASTODON_ACCESS_TOKEN`, `MASTODON_ACCOUNT_ID` | `MASTODON_BASE_URL`, `MASTODON_ACCESS_TOKEN`, `MASTODON_ACCOUNT_ID` |
+| Threads | `THREADS_ACCESS_TOKEN`, `THREADS_USER_ID` | `THREADS_ACCESS_TOKEN`, `THREADS_USER_ID` |
+
+## GitHub Actions
+
+This repo includes:
+
+- `.github/workflows/ci.yml` for build + unit tests on every push/PR.
+- `.github/workflows/release.yml` for npm publish on tag (`v*`) or manual dispatch.
+
+Configure these repository secrets to enable integration CI:
+
+- `X_API_KEY`
+- `X_API_SECRET`
+- `X_ACCESS_TOKEN`
+- `X_ACCESS_SECRET`
+- `X_TEST_TWEET_ID`
+- `FB_PAGE_ACCESS_TOKEN`
+- `FB_PAGE_ID`
+- `IG_ACCESS_TOKEN`
+- `IG_USER_ID`
+- `LINKEDIN_ACCESS_TOKEN`
+- `LINKEDIN_ORG_URN`
+- `YOUTUBE_ACCESS_TOKEN`
+- `YOUTUBE_CHANNEL_ID`
+- `TIKTOK_ACCESS_TOKEN`
+- `PINTEREST_ACCESS_TOKEN`
+- `PINTEREST_BOARD_ID`
+- `BLUESKY_IDENTIFIER`
+- `BLUESKY_APP_PASSWORD`
+- `BLUESKY_TEST_ACTOR` (optional; defaults to `BLUESKY_IDENTIFIER` when omitted)
+- `MASTODON_BASE_URL`
+- `MASTODON_ACCESS_TOKEN`
+- `MASTODON_ACCOUNT_ID`
+- `THREADS_ACCESS_TOKEN`
+- `THREADS_USER_ID`
+
+Configure this repository secret for publishing:
+
+- `NPM_TOKEN`

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node