viruagent-cli 0.8.1 → 0.9.0

package/README.ko.md

@@ -31,6 +31,7 @@
 | **Naver Cafe** | 카페 가입 (모바일 5회 캡차 면제), 글쓰기, 게시판 조회, 이미지 업로드 (슬라이드/콜라주) | [가이드](docs/ko/guide-naver-cafe.md) |
 | **Instagram** | 좋아요, 댓글, 팔로우, 포스팅, 프로필, 피드 | [가이드](docs/ko/guide-instagram.md) |
 | **X (Twitter)** | 트윗, 좋아요, 리트윗, 팔로우, 검색, 타임라인, 미디어 업로드 | [가이드](docs/ko/guide-x.md) |
+| **Threads** | 글쓰기, 답글, 좋아요, 팔로우, 이미지 업로드, 검색, 피드 | [가이드](docs/ko/guide-threads.md) |
 
 ## 동작 방식
 
@@ -119,6 +120,13 @@ npx viruagent-cli login --provider x --auth-token <토큰> --ct0 <ct0>
 >
 > 전체 API 레퍼런스, GraphQL 동기화, rate limit 규칙은 [X 가이드](docs/ko/guide-x.md)를 참고하세요.
 
+### Threads
+
+```bash
+npx viruagent-cli login --provider threads --username <인스타 ID> --password <비밀번호>
+```
+> Instagram 계정으로 로그인합니다. 쓰레드는 별도 계정이 없습니다.
+
 ## 사용법
 
 | 이렇게 말하면 | 에이전트가 알아서 |
@@ -137,6 +145,8 @@ npx viruagent-cli login --provider x --auth-token <토큰> --ct0 <ct0>
 | "내 X 타임라인 보여줘" | getFeed → 최신 트윗 표시 |
 | "이 네이버 카페 가입해줘" | cafe-id → cafe-join (모바일 5회 캡차 면제) |
 | "네이버 카페에 글 써줘" | cafe-list → cafe-write |
+| "쓰레드에 글 올려줘" | login → publish (텍스트 또는 이미지) |
+| "이 쓰레드에 답글 달아줘" | comment (rate limit 자동 적용) |
 
 ## 플랫폼별 가이드
 
@@ -145,6 +155,7 @@ npx viruagent-cli login --provider x --auth-token <토큰> --ct0 <ct0>
 - **[Naver Cafe 가이드](docs/ko/guide-naver-cafe.md)** — 카페 가입 (모바일 5회 캡차 면제), 글쓰기, 슬라이드/콜라주
 - **[Instagram 가이드](docs/ko/guide-instagram.md)** — 18개 API 메서드, rate limit 규칙, AI 댓글
 - **[X (Twitter) 가이드](docs/ko/guide-x.md)** — GraphQL API, queryId 동적 동기화, rate limit 규칙
+- **[Threads 가이드](docs/ko/guide-threads.md)** — Barcelona API, IGT:2 토큰 인증, rate limit 규칙
 
 ## 지원 환경
 
@@ -167,6 +178,7 @@ npx viruagent-cli login --provider x --auth-token <토큰> --ct0 <ct0>
 | 이미지 검색 | DuckDuckGo, Wikimedia Commons |
 | 네이버 에디터 | SE Editor 컴포넌트 모델 + RabbitWrite API |
 | 네이버 카페 API | 순수 HTTP (가입, 글쓰기, 게시판 조회, 사용자 캡차 입력) |
+| Threads API | Barcelona (Instagram Private API), IGT:2 토큰 인증 |
 | 출력 형식 | JSON envelope (`{ ok, data }` / `{ ok, error, hint }`) |
 
 ## Contributing

package/README.md

@@ -32,6 +32,7 @@ Designed not for humans, but for **AI agents**.
 | **Instagram** | Like, Comment, Follow, Post, Profile, Feed, Rate Limit | [Guide](docs/en/guide-instagram.md) |
 | **X (Twitter)** | Tweet, Like, Retweet, Follow, Search, Timeline, Media Upload | [Guide](docs/en/guide-x.md) |
 | **Reddit** | Post, Comment, Upvote, Search, Subscribe, Subreddit | [Guide](docs/en/guide-reddit.md) |
+| **Threads** | Post, Reply, Like, Follow, Image Upload, Search, Feed | [Guide](docs/en/guide-threads.md) |
 
 ## How It Works
 
@@ -120,6 +121,13 @@ npx viruagent-cli login --provider x --auth-token <token> --ct0 <ct0>
 >
 > See the [X Guide](docs/en/guide-x.md) for full API reference, GraphQL sync, and rate limit rules.
 
+### Threads
+
+```bash
+npx viruagent-cli login --provider threads --username <instagram_id> --password <password>
+```
+> Threads uses your Instagram account. No separate login needed.
+
 ## Usage
 
 | Say this | Agent handles |
@@ -138,6 +146,8 @@ npx viruagent-cli login --provider x --auth-token <token> --ct0 <ct0>
 | "Show my X timeline" | getFeed → show latest tweets |
 | "Join this Naver cafe" | cafe-id → cafe-join (captcha-free for 5 joins) |
 | "Write a post on Naver cafe" | cafe-list → cafe-write |
+| "Post on Threads" | login → publish (text or image) |
+| "Reply to a thread" | comment (with rate limit) |
 
 ## Platform Guides
 
@@ -146,6 +156,7 @@ npx viruagent-cli login --provider x --auth-token <token> --ct0 <ct0>
 - **[Naver Cafe Guide](docs/en/guide-naver-cafe.md)** — Cafe join (captcha-free for 5 joins), write post, slide/collage images
 - **[Instagram Guide](docs/en/guide-instagram.md)** — 18 API methods, rate limits, AI commenting
 - **[X (Twitter) Guide](docs/en/guide-x.md)** — GraphQL API, dynamic queryId sync, rate limits
+- **[Threads Guide](docs/en/guide-threads.md)** — Barcelona API, IGT:2 token auth, rate limits
 
 ## Supported Environments
 
@@ -168,6 +179,7 @@ npx viruagent-cli login --provider x --auth-token <token> --ct0 <ct0>
 | Image Search | DuckDuckGo, Wikimedia Commons |
 | Naver Editor | SE Editor component model + RabbitWrite API |
 | Naver Cafe API | Pure HTTP (join, write, board list, manual captcha) |
+| Threads API | Barcelona (Instagram Private API), IGT:2 token auth |
 | Output Format | JSON envelope (`{ ok, data }` / `{ ok, error, hint }`) |
 
 ## Contributing

package/bin/index.js

@@ -18,7 +18,7 @@ program
 
 // Global options
 const addProviderOption = (cmd) =>
-  cmd.option('--provider <name>', 'Provider name (tistory, naver, insta, x, reddit)', 'tistory');
+  cmd.option('--provider <name>', 'Provider name (tistory, naver, insta, x, reddit, threads)', 'tistory');
 
 const addDryRunOption = (cmd) =>
   cmd.option('--dry-run', 'Validate params without executing', false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viruagent-cli",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "AI-agent-optimized CLI for blog/SNS publishing and engagement (Tistory, Naver, Instagram, X/Twitter, Reddit)",
   "private": false,
   "type": "commonjs",

package/skills/va-shared/SKILL.md

@@ -13,6 +13,8 @@ triggers:
   - 좋아요
   - 댓글
   - 팔로우
+  - 쓰레드
+  - threads
 metadata:
   category: "router"
   requires:
@@ -32,6 +34,7 @@ viruagent-cli를 사용하는 블로그/SNS 자동화 에이전트입니다.
 | 네이버, naver | `va-naver/SKILL.md` |
 | 카페, cafe, 카페 가입, 카페 글쓰기 | `va-naver-cafe-join/SKILL.md` 또는 `va-naver-cafe-write/SKILL.md` |
 | 인스타, instagram, 좋아요, 댓글, 팔로우 | `va-insta/SKILL.md` |
+| 쓰레드, threads | `va-threads/SKILL.md` |
 | 블로그 써줘 (플랫폼 미지정) | 사용자에게 플랫폼 질문 |
 | 블로거 역할 | `persona-blogger/SKILL.md` |
 | 인플루언서 관리 | `persona-influencer-manager/SKILL.md` |
@@ -75,6 +78,8 @@ SKILLS_DIR: <viruagent-cli 설치 경로>/skills/
 | va-insta-follow | `va-insta-follow/SKILL.md` | 팔로우/언팔 |
 | va-insta-dm | `va-insta-dm/SKILL.md` | DM |
 | va-insta-feed | `va-insta-feed/SKILL.md` | 피드/프로필/분석 |
+| va-threads | `va-threads/SKILL.md` | Threads 개요 + 레이트리밋 |
+| va-threads-publish | `va-threads-publish/SKILL.md` | Threads 글쓰기 |
 
 ### 페르소나 스킬
 

package/skills/va-threads/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: va-threads
+version: 1.0.0
+description: "Threads 자동화: 명령 개요 및 레이트리밋 규칙"
+metadata:
+  category: "overview"
+  provider: "threads"
+  requires:
+    bins: ["viruagent-cli"]
+---
+
+# va-threads — Threads 자동화 개요
+
+Threads 자동화를 위한 viruagent-cli 가이드. 항상 `--provider threads` 사용.
+
+## 명령 목록
+
+| 명령 | 스킬 | 설명 |
+|------|------|------|
+| login | va-threads | 로그인 (Instagram 계정) |
+| publish | va-threads-publish | 글쓰기 (텍스트/이미지) |
+| like | va-threads | 좋아요 |
+| comment | va-threads | 답글 |
+| follow | va-threads | 팔로우 |
+| search | va-threads | 검색 |
+| get-profile | va-threads | 프로필 조회 |
+| get-feed | va-threads | 피드 조회 |
+
+## Rate Limit Safety (신규 계정 기준)
+
+| 액션 | 딜레이 | 시간당 | 일일 |
+|------|--------|--------|------|
+| Post | 2~5min | 5 | 25 |
+| Like | 20~40s | 15 | 500 |
+| Reply | 5~7min | 5 | 100 |
+| Follow | 1~2min | 15 | 250 |
+
+모든 딜레이는 랜덤화되어 자동 적용. 카운터는 세션별 userId로 영속화.
+
+## 레이트리밋 확인
+
+```bash
+npx viruagent-cli rate-limit-status --provider threads
+```
+
+대량 작업 전 반드시 확인.
+
+## 중요 사항
+
+- Instagram 계정을 공유하므로 Instagram rate limit에 영향을 줄 수 있음
+- Barcelona User-Agent + Bloks API 사용
+- IGT:2 토큰이 주요 인증 수단
+- 세션 + 카운터: `~/.viruagent-cli/sessions/threads-session.json`
+
+## 환경변수
+
+```
+THREADS_USERNAME=
+THREADS_PASSWORD=
+# 또는
+INSTA_USERNAME=
+INSTA_PASSWORD=
+```
+
+## See Also
+
+va-shared, va-threads-publish

package/skills/va-threads-publish/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: va-threads-publish
+version: 1.0.0
+description: "Threads 글쓰기: 텍스트/이미지 포스팅"
+metadata:
+  category: "publish"
+  provider: "threads"
+  requires:
+    bins: ["viruagent-cli"]
+---
+
+# va-threads-publish — Threads 글쓰기
+
+Threads에 텍스트/이미지를 발행하는 가이드.
+
+## 명령어
+
+```bash
+# 텍스트만
+npx viruagent-cli publish --provider threads \
+  --content "<텍스트>"
+
+# 이미지 첨부
+npx viruagent-cli publish --provider threads \
+  --content "<텍스트>" \
+  --image-urls "<이미지URL>"
+```
+
+## 글쓰기 규칙 (Threads 최적화)
+
+### 분량
+- **최적 길이**: 100~300자 (짧고 임팩트 있게)
+- Threads는 짧은 텍스트 중심 — 블로그처럼 길게 쓰지 않음
+
+### 첫 줄이 전부다
+- **숫자**: "3가지만 알면 됩니다"
+- **반전**: "잘못 알고 있었습니다"
+- **질문**: "이거 해보셨나요?"
+- **공감**: "저만 이런 거 아니죠?"
+
+### 해시태그
+- Threads는 해시태그 효과가 Instagram보다 약함
+- 최대 5개, 본문 하단에 배치
+- 검색 기능이 제한적이므로 키워드를 본문에 자연스럽게 녹이기
+
+### 이미지
+- 이미지 1장 첨부 가능
+- `--image-urls`에 직접 URL 지정
+- 고해상도 (1080x1080 이상) 권장
+
+## 발행 예시
+
+```bash
+# 짧은 의견
+npx viruagent-cli publish --provider threads \
+  --content "AI가 코드 리뷰해주는 시대.
+
+그런데 아직도 혼자 다 보고 있다면
+도구를 바꿀 때입니다."
+
+# 이미지 포함
+npx viruagent-cli publish --provider threads \
+  --content "오늘의 작업 환경. 카페에서 코딩하는 게 제일 잘 됨." \
+  --image-urls "https://example.com/workspace.jpg"
+```
+
+## 주의사항
+
+- 글 최대 500자 (초과 시 잘림)
+- 발행 간격: 최소 2~5분 (rate limit)
+- 로그인 안 된 경우: `login --provider threads` 먼저 실행
+- Instagram 계정 공유이므로 Instagram challenge 발생 가능
+
+## See Also
+
+va-threads, va-shared

package/src/providers/threads/apiClient.js

@@ -0,0 +1,487 @@
+const fs = require('fs');
+const { loadThreadsSession, loadRateLimits, saveRateLimits } = require('./session');
+const { THREADS_APP_ID, THREADS_USER_AGENT, BLOKS_VERSION, BASE_URL } = require('./auth');
+
+const randomDelay = (minSec, maxSec) => {
+  const ms = (minSec + Math.random() * (maxSec - minSec)) * 1000;
+  return new Promise((resolve) => setTimeout(resolve, ms));
+};
+
+// ──────────────────────────────────────────────────────────────
+// Threads Safe Action Rules (conservative, Instagram-based)
+// ──────────────────────────────────────────────────────────────
+
+const DELAY = {
+  publish:  [120, 300],  // 2~5min
+  like:     [20, 40],    // 20~40s
+  comment:  [120, 300],  // 2~5min
+  follow:   [60, 120],   // 1~2min
+  unfollow: [60, 120],   // 1~2min
+};
+
+const HOURLY_LIMIT = {
+  publish: 10,
+  like: 15,
+  comment: 5,
+  follow: 15,
+  unfollow: 10,
+};
+
+const DAILY_LIMIT = {
+  publish: 50,
+  like: 500,
+  comment: 100,
+  follow: 250,
+  unfollow: 200,
+};
+
+let lastActionTime = 0;
+
+const createThreadsApiClient = ({ sessionPath }) => {
+  let cachedSession = null;
+  let countersCache = null;
+
+  // ── Session helpers ──
+
+  const getSession = () => {
+    if (cachedSession) return cachedSession;
+    const session = loadThreadsSession(sessionPath);
+    if (!session) {
+      throw new Error('No session file found. Please log in first.');
+    }
+    if (!session.token) {
+      throw new Error('No valid token in session. Please log in again.');
+    }
+    cachedSession = session;
+    return session;
+  };
+
+  const getToken = () => getSession().token;
+  const getUserIdFromSession = () => getSession().userId;
+  const getDeviceId = () => getSession().deviceId;
+
+  // ── Rate Limit counters ──
+
+  const loadCounters = () => {
+    if (countersCache) return countersCache;
+    try {
+      const userId = getUserIdFromSession();
+      if (!userId) { countersCache = {}; return countersCache; }
+      const saved = loadRateLimits(sessionPath, userId);
+      countersCache = saved || {};
+    } catch {
+      countersCache = {};
+    }
+    return countersCache;
+  };
+
+  const persistCounters = () => {
+    try {
+      const userId = getUserIdFromSession();
+      if (!userId || !countersCache) return;
+      saveRateLimits(sessionPath, userId, countersCache);
+    } catch {
+      // Save failure does not affect operation
+    }
+  };
+
+  const getCounter = (type) => {
+    const counters = loadCounters();
+    if (!counters[type]) {
+      counters[type] = { hourly: 0, daily: 0, hourStart: Date.now(), dayStart: Date.now() };
+    }
+    const c = counters[type];
+    const now = Date.now();
+    if (now - c.hourStart > 3600000) { c.hourly = 0; c.hourStart = now; }
+    if (now - c.dayStart > 86400000) { c.daily = 0; c.dayStart = now; }
+    return c;
+  };
+
+  const checkLimit = (type) => {
+    const c = getCounter(type);
+    const hourlyMax = HOURLY_LIMIT[type];
+    const dailyMax = DAILY_LIMIT[type];
+    if (hourlyMax && c.hourly >= hourlyMax) {
+      const waitMin = Math.ceil((3600000 - (Date.now() - c.hourStart)) / 60000);
+      throw new Error(`hourly_limit: ${type} exceeded hourly limit of ${hourlyMax}. Retry in ${waitMin} minutes.`);
+    }
+    if (dailyMax && c.daily >= dailyMax) {
+      throw new Error(`daily_limit: ${type} exceeded daily limit of ${dailyMax}. Try again tomorrow.`);
+    }
+  };
+
+  const incrementCounter = (type) => {
+    const c = getCounter(type);
+    c.hourly++;
+    c.daily++;
+    persistCounters();
+  };
+
+  const withDelay = async (type, fn) => {
+    checkLimit(type);
+
+    const [min, max] = DELAY[type] || [20, 40];
+    const elapsed = (Date.now() - lastActionTime) / 1000;
+    if (lastActionTime > 0 && elapsed < min) {
+      await randomDelay(min - elapsed, max - elapsed);
+    }
+
+    const result = await fn();
+    lastActionTime = Date.now();
+    incrementCounter(type);
+    return result;
+  };
+
+  // ── HTTP request helper ──
+
+  const getHeaders = () => ({
+    'User-Agent': `${THREADS_USER_AGENT} (30/11; 420dpi; 1080x2400; samsung; SM-A325F; a32; exynos850)`,
+    'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8',
+    'Authorization': `Bearer IGT:2:${getToken()}`,
+    'X-IG-App-ID': THREADS_APP_ID,
+    'X-Bloks-Version-Id': BLOKS_VERSION,
+    'Sec-Fetch-Site': 'same-origin',
+    'Sec-Fetch-Mode': 'cors',
+    'Sec-Fetch-Dest': 'empty',
+  });
+
+  const request = async (url, options = {}) => {
+    const headers = { ...getHeaders(), ...options.headers };
+
+    const res = await fetch(url, {
+      ...options,
+      headers,
+      redirect: options.followRedirect ? 'follow' : 'manual',
+    });
+
+    if (res.status === 302 || res.status === 301) {
+      const location = res.headers.get('location') || '';
+      if (location.includes('/accounts/login') || location.includes('login')) {
+        throw new Error('Session expired. Please log in again.');
+      }
+      throw new Error(`Redirect occurred: ${res.status} -> ${location}`);
+    }
+
+    if (res.status === 401 || res.status === 403) {
+      throw new Error(`Authentication error (${res.status}). Please log in again.`);
+    }
+
+    if (!res.ok && !options.allowError) {
+      throw new Error(`Threads API error: ${res.status} ${res.statusText}`);
+    }
+
+    return res;
+  };
+
+  // ── API methods ──
+
+  const getUserId = async (username) => {
+    const res = await request(
+      `${BASE_URL}/api/v1/users/search/?q=${encodeURIComponent(username)}`,
+    );
+    const data = await res.json();
+    const user = data?.users?.find(
+      (u) => u.username?.toLowerCase() === username.toLowerCase(),
+    );
+    if (!user) throw new Error(`User not found: ${username}`);
+    return user.pk_id || user.pk || String(user.pk);
+  };
+
+  const getUserProfile = async (userId) => {
+    const res = await request(`${BASE_URL}/api/v1/users/${userId}/info/`);
+    const data = await res.json();
+    const user = data?.user;
+    if (!user) throw new Error(`Profile not found for userId: ${userId}`);
+    return {
+      id: user.pk || userId,
+      username: user.username,
+      fullName: user.full_name,
+      biography: user.biography,
+      followerCount: user.follower_count || 0,
+      followingCount: user.following_count || 0,
+      isPrivate: user.is_private,
+      isVerified: user.is_verified,
+      profilePicUrl: user.hd_profile_pic_url_info?.url || user.profile_pic_url,
+    };
+  };
+
+  const getTimeline = async () => {
+    const res = await request(`${BASE_URL}/api/v1/feed/text_post_app_timeline/`, {
+      method: 'POST',
+      body: '',
+    });
+    const data = await res.json();
+    const items = data?.items || [];
+    return items
+      .filter((item) => item.post || item.thread_items)
+      .slice(0, 20)
+      .map((item) => {
+        const threadItems = item.thread_items || [item];
+        const first = threadItems[0]?.post || threadItems[0];
+        return {
+          id: first?.pk || first?.id,
+          code: first?.code,
+          username: first?.user?.username,
+          caption: first?.caption?.text || '',
+          likeCount: first?.like_count || 0,
+          replyCount: first?.text_post_app_info?.direct_reply_count || 0,
+          timestamp: first?.taken_at,
+        };
+      });
+  };
+
+  const getUserThreads = async (userId, limit = 20) => {
+    const res = await request(`${BASE_URL}/api/v1/text_feed/${userId}/profile/`);
+    const data = await res.json();
+    const threads = data?.threads || [];
+    return threads.slice(0, limit).map((thread) => {
+      const items = thread.thread_items || [];
+      const first = items[0]?.post;
+      return {
+        id: first?.pk || first?.id,
+        code: first?.code,
+        caption: first?.caption?.text || '',
+        likeCount: first?.like_count || 0,
+        replyCount: first?.text_post_app_info?.direct_reply_count || 0,
+        timestamp: first?.taken_at,
+      };
+    });
+  };
+
+  const getThreadReplies = async (postId) => {
+    const res = await request(`${BASE_URL}/api/v1/text_feed/${postId}/replies/`);
+    const data = await res.json();
+    const items = data?.thread_items || [];
+    return items.map((item) => {
+      const post = item.post;
+      return {
+        id: post?.pk || post?.id,
+        username: post?.user?.username,
+        text: post?.caption?.text || '',
+        likeCount: post?.like_count || 0,
+        timestamp: post?.taken_at,
+      };
+    });
+  };
+
+  const publishTextThread = (text, replyToId) => withDelay('publish', async () => {
+    const userId = getUserIdFromSession();
+    const uploadId = Date.now().toString();
+    const deviceId = getDeviceId();
+
+    const payload = {
+      publish_mode: 'text_post',
+      text_post_app_info: JSON.stringify({ reply_control: 0 }),
+      timezone_offset: '32400',
+      source_type: '4',
+      caption: text,
+      upload_id: uploadId,
+      device_id: deviceId,
+      _uid: userId,
+    };
+
+    if (replyToId) {
+      payload.text_post_app_info = JSON.stringify({
+        reply_control: 0,
+        reply_id: replyToId,
+      });
+    }
+
+    const body = `signed_body=SIGNATURE.${encodeURIComponent(JSON.stringify(payload))}`;
+
+    const res = await request(`${BASE_URL}/api/v1/media/configure_text_only_post/`, {
+      method: 'POST',
+      body,
+    });
+
+    const data = await res.json();
+    if (data.status !== 'ok') {
+      throw new Error(`Thread publish failed: ${data.message || JSON.stringify(data)}`);
+    }
+
+    return {
+      id: data.media?.pk || data.media?.id,
+      code: data.media?.code,
+      caption: data.media?.caption?.text || text,
+      status: data.status,
+    };
+  });
+
+  const uploadImage = async (imageBuffer) => {
+    const uploadId = Date.now().toString();
+    const uploadName = `${uploadId}_0_${Math.floor(Math.random() * 9000000000 + 1000000000)}`;
+
+    const res = await request(
+      `https://www.instagram.com/rupload_igphoto/${uploadName}`,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'image/jpeg',
+          'X-Entity-Name': uploadName,
+          'X-Entity-Length': imageBuffer.length.toString(),
+          'X-Instagram-Rupload-Params': JSON.stringify({
+            media_type: 1,
+            upload_id: uploadId,
+            upload_media_height: 1080,
+            upload_media_width: 1080,
+          }),
+          Offset: '0',
+        },
+        body: imageBuffer,
+        followRedirect: true,
+      },
+    );
+    const data = await res.json();
+    if (data.status !== 'ok') {
+      throw new Error(`Image upload failed: ${data.message || 'unknown'}`);
+    }
+    return uploadId;
+  };
+
+  const publishImageThread = (uploadId, text) => withDelay('publish', async () => {
+    const userId = getUserIdFromSession();
+    const deviceId = getDeviceId();
+
+    const payload = {
+      publish_mode: 'text_post',
+      text_post_app_info: JSON.stringify({ reply_control: 0 }),
+      timezone_offset: '32400',
+      source_type: '4',
+      caption: text || '',
+      upload_id: uploadId,
+      device_id: deviceId,
+      _uid: userId,
+      scene_capture_type: '',
+    };
+
+    const body = `signed_body=SIGNATURE.${encodeURIComponent(JSON.stringify(payload))}`;
+
+    // Single image uses configure_text_only_post (same as text, with upload_id)
+    const res = await request(`${BASE_URL}/api/v1/media/configure_text_only_post/`, {
+      method: 'POST',
+      body,
+      allowError: true,
+    });
+
+    const data = await res.json();
+    if (data.status !== 'ok') {
+      throw new Error(`Image thread publish failed: ${data.message || JSON.stringify(data)}`);
+    }
+
+    return {
+      id: data.media?.pk || data.media?.id,
+      code: data.media?.code,
+      caption: data.media?.caption?.text || text,
+      status: data.status,
+    };
+  });
+
+  const likeThread = (postId) => withDelay('like', async () => {
+    const userId = getUserIdFromSession();
+    const res = await request(
+      `${BASE_URL}/api/v1/media/${postId}_${userId}/like/`,
+      { method: 'POST', body: '', allowError: true },
+    );
+    const data = await res.json();
+    return { status: data.status || 'ok' };
+  });
+
+  const unlikeThread = (postId) => withDelay('like', async () => {
+    const userId = getUserIdFromSession();
+    const res = await request(
+      `${BASE_URL}/api/v1/media/${postId}_${userId}/unlike/`,
+      { method: 'POST', body: '', allowError: true },
+    );
+    const data = await res.json();
+    return { status: data.status || 'ok' };
+  });
+
+  const followUser = (userId) => withDelay('follow', async () => {
+    const res = await request(
+      `${BASE_URL}/api/v1/friendships/create/${userId}/`,
+      { method: 'POST', body: '', allowError: true },
+    );
+    const data = await res.json();
+    return {
+      status: data.status || (data.friendship_status ? 'ok' : 'fail'),
+      following: data.friendship_status?.following || false,
+      outgoingRequest: data.friendship_status?.outgoing_request || false,
+    };
+  });
+
+  const unfollowUser = (userId) => withDelay('unfollow', async () => {
+    const res = await request(
+      `${BASE_URL}/api/v1/friendships/destroy/${userId}/`,
+      { method: 'POST', body: '', allowError: true },
+    );
+    const data = await res.json();
+    return {
+      status: data.status || (data.friendship_status ? 'ok' : 'fail'),
+      following: data.friendship_status?.following || false,
+    };
+  });
+
+  const searchUsers = async (query, limit = 20) => {
+    const res = await request(
+      `${BASE_URL}/api/v1/users/search/?q=${encodeURIComponent(query)}`,
+    );
+    const data = await res.json();
+    const users = data?.users || [];
+    return users.slice(0, limit).map((u) => ({
+      id: u.pk || u.pk_id,
+      username: u.username,
+      fullName: u.full_name,
+      isVerified: u.is_verified,
+      profilePicUrl: u.profile_pic_url,
+    }));
+  };
+
+  const deleteThread = async (postId) => {
+    const res = await request(
+      `${BASE_URL}/api/v1/media/${postId}/delete/?media_type=TEXT_POST`,
+      { method: 'POST' },
+    );
+    return res.json();
+  };
+
+  const resetState = () => {
+    cachedSession = null;
+    countersCache = null;
+  };
+
+  return {
+    getSession,
+    getToken,
+    getUserIdFromSession,
+    request,
+    getUserId,
+    getUserProfile,
+    getTimeline,
+    getUserThreads,
+    getThreadReplies,
+    publishTextThread,
+    uploadImage,
+    publishImageThread,
+    likeThread,
+    unlikeThread,
+    followUser,
+    unfollowUser,
+    searchUsers,
+    deleteThread,
+    resetState,
+    getRateLimitStatus: () => {
+      const status = {};
+      for (const type of Object.keys(HOURLY_LIMIT)) {
+        const c = getCounter(type);
+        status[type] = {
+          hourly: `${c.hourly}/${HOURLY_LIMIT[type]}`,
+          daily: `${c.daily}/${DAILY_LIMIT[type]}`,
+          delay: `${DELAY[type]?.[0]}~${DELAY[type]?.[1]}s`,
+        };
+      }
+      return status;
+    },
+  };
+};
+
+module.exports = createThreadsApiClient;

package/src/providers/threads/auth.js

@@ -0,0 +1,142 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { readThreadsCredentials } = require('./utils');
+const { saveThreadsSession } = require('./session');
+
+const THREADS_APP_ID = '238260118697367';
+const THREADS_USER_AGENT = 'Barcelona 289.0.0.77.109 Android';
+const BLOKS_VERSION = '00ba6fa565c3c707243ad976fa30a071a625f2a3d158d9412091176fe35027d8';
+const BASE_URL = 'https://i.instagram.com';
+
+const generateDeviceId = () => `android-${crypto.randomBytes(8).toString('hex')}`;
+
+const createAskForAuthentication = ({ sessionPath }) => async ({
+  username,
+  password,
+} = {}) => {
+  fs.mkdirSync(path.dirname(sessionPath), { recursive: true });
+
+  const resolvedUsername = username || readThreadsCredentials().username;
+  const resolvedPassword = password || readThreadsCredentials().password;
+
+  if (!resolvedUsername || !resolvedPassword) {
+    throw new Error(
+      'Threads login requires username/password. ' +
+      'Please set the THREADS_USERNAME / THREADS_PASSWORD (or INSTA_USERNAME / INSTA_PASSWORD) environment variables.',
+    );
+  }
+
+  const deviceId = generateDeviceId();
+  const timestamp = Math.floor(Date.now() / 1000);
+
+  const clientInputParams = JSON.stringify({
+    password: `#PWD_INSTAGRAM:0:${timestamp}:${resolvedPassword}`,
+    contact_point: resolvedUsername,
+    device_id: deviceId,
+  });
+
+  const serverParams = JSON.stringify({
+    credential_type: 'password',
+    device_id: deviceId,
+  });
+
+  const body = new URLSearchParams({
+    params: JSON.stringify({
+      client_input_params: JSON.parse(clientInputParams),
+      server_params: JSON.parse(serverParams),
+    }),
+    bk_client_context: JSON.stringify({ bloks_version: BLOKS_VERSION, styles_id: 'instagram' }),
+    bloks_versioning_id: BLOKS_VERSION,
+  });
+
+  const res = await fetch(
+    `${BASE_URL}/api/v1/bloks/apps/com.bloks.www.bloks.caa.login.async.send_login_request/`,
+    {
+      method: 'POST',
+      headers: {
+        'User-Agent': THREADS_USER_AGENT,
+        'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8',
+        'X-Bloks-Version-Id': BLOKS_VERSION,
+        'X-IG-App-ID': THREADS_APP_ID,
+        'Sec-Fetch-Site': 'same-origin',
+        'Sec-Fetch-Mode': 'cors',
+        'Sec-Fetch-Dest': 'empty',
+      },
+      body: body.toString(),
+      redirect: 'manual',
+    },
+  );
+
+  const responseText = await res.text();
+
+  // Extract Bearer token — check header first, then Bloks response body
+  let token = null;
+  const authHeader = res.headers.get('ig-set-authorization');
+  if (authHeader) {
+    const match = authHeader.match(/Bearer IGT:2:(.+)/);
+    if (match) token = match[1];
+  }
+  if (!token) {
+    // Token is embedded in Bloks response body (escaped JSON)
+    const bodyMatch = responseText.match(/Bearer IGT:2:([a-zA-Z0-9_=+/]+)/);
+    if (bodyMatch) token = bodyMatch[1];
+  }
+
+  // Extract userId from token (base64 decode) or response body
+  let userId = null;
+  if (token) {
+    try {
+      const decoded = JSON.parse(Buffer.from(token, 'base64').toString());
+      userId = decoded.ds_user_id || null;
+    } catch { /* ignore decode error */ }
+  }
+  if (!userId) {
+    const userIdMatch = responseText.match(/"pk_string":"(\d+)"/);
+    if (userIdMatch) {
+      userId = userIdMatch[1];
+    } else {
+      const altMatch = responseText.match(/"user_id":(\d+)/);
+      if (altMatch) userId = altMatch[1];
+    }
+  }
+
+  // Check for errors
+  if (!token) {
+    if (responseText.includes('checkpoint_required') || responseText.includes('challenge_required')) {
+      throw new Error(
+        'challenge_required: Identity verification required. Please complete it in the Threads app or Instagram.',
+      );
+    }
+    if (responseText.includes('two_factor_required')) {
+      throw new Error(
+        'Two-factor authentication (2FA) is required. Please complete verification in the app first.',
+      );
+    }
+    if (responseText.includes('invalid_user') || responseText.includes('invalid_password')) {
+      throw new Error('Threads login failed: Invalid username or password.');
+    }
+    throw new Error(
+      `Threads login failed: Could not extract authorization token. Response status: ${res.status}`,
+    );
+  }
+
+  // Save session
+  saveThreadsSession(sessionPath, { token, userId, deviceId });
+
+  return {
+    provider: 'threads',
+    loggedIn: true,
+    userId,
+    username: resolvedUsername,
+    sessionPath,
+  };
+};
+
+module.exports = {
+  createAskForAuthentication,
+  THREADS_APP_ID,
+  THREADS_USER_AGENT,
+  BLOKS_VERSION,
+  BASE_URL,
+};

package/src/providers/threads/index.js

@@ -0,0 +1,248 @@
+const fs = require('fs');
+const { saveProviderMeta, clearProviderMeta, getProviderMeta } = require('../../storage/sessionStore');
+const createThreadsApiClient = require('./apiClient');
+const { readThreadsCredentials } = require('./utils');
+const { createThreadsWithProviderSession } = require('./session');
+const { createAskForAuthentication } = require('./auth');
+
+const createThreadsProvider = ({ sessionPath, account }) => {
+  const api = createThreadsApiClient({ sessionPath });
+
+  const askForAuthentication = createAskForAuthentication({ sessionPath });
+
+  const withProviderSession = createThreadsWithProviderSession(askForAuthentication, account);
+
+  return {
+    id: 'threads',
+    name: 'Threads',
+
+    async authStatus() {
+      return withProviderSession(async () => {
+        try {
+          const session = api.getSession();
+          return {
+            provider: 'threads',
+            loggedIn: true,
+            userId: session.userId,
+            hasSession: Boolean(session.token),
+            sessionPath,
+            metadata: getProviderMeta('threads', account) || {},
+          };
+        } catch (error) {
+          return {
+            provider: 'threads',
+            loggedIn: false,
+            sessionPath,
+            error: error.message,
+            metadata: getProviderMeta('threads', account) || {},
+          };
+        }
+      });
+    },
+
+    async login({ username, password } = {}) {
+      const creds = readThreadsCredentials();
+      const resolved = {
+        username: username || creds.username,
+        password: password || creds.password,
+      };
+
+      if (!resolved.username || !resolved.password) {
+        throw new Error(
+          'Threads login requires username/password. ' +
+          'Please set the THREADS_USERNAME / THREADS_PASSWORD (or INSTA_USERNAME / INSTA_PASSWORD) environment variables.',
+        );
+      }
+
+      const result = await askForAuthentication(resolved);
+      api.resetState();
+
+      saveProviderMeta('threads', {
+        loggedIn: result.loggedIn,
+        userId: result.userId,
+        username: result.username,
+        sessionPath: result.sessionPath,
+      }, account);
+
+      return result;
+    },
+
+    async publish({ content, imageUrls, imageUrl, imagePath, replyTo, caption } = {}) {
+      return withProviderSession(async () => {
+        const text = content || caption || '';
+
+        // Image thread
+        let resolvedImageUrl = imageUrl;
+        if (!resolvedImageUrl && !imagePath && imageUrls?.length > 0) {
+          resolvedImageUrl = imageUrls[0];
+        }
+
+        if (resolvedImageUrl || imagePath) {
+          let imageBuffer;
+          if (imagePath) {
+            imageBuffer = fs.readFileSync(imagePath);
+          } else {
+            const res = await fetch(resolvedImageUrl);
+            if (!res.ok) throw new Error(`Image download failed: ${res.status}`);
+            imageBuffer = Buffer.from(await res.arrayBuffer());
+          }
+          const uploadId = await api.uploadImage(imageBuffer);
+          const result = await api.publishImageThread(uploadId, text);
+          return { provider: 'threads', mode: 'publish', ...result };
+        }
+
+        // Text-only thread
+        if (!text) {
+          throw new Error('content is required for text threads.');
+        }
+        const result = await api.publishTextThread(text, replyTo);
+        return { provider: 'threads', mode: 'publish', ...result };
+      });
+    },
+
+    async comment({ postId, text } = {}) {
+      return withProviderSession(async () => {
+        if (!postId) throw new Error('postId is required.');
+        if (!text) throw new Error('text is required.');
+        const result = await api.publishTextThread(text, postId);
+        return {
+          provider: 'threads',
+          mode: 'comment',
+          replyTo: postId,
+          ...result,
+        };
+      });
+    },
+
+    async like({ postId } = {}) {
+      return withProviderSession(async () => {
+        if (!postId) throw new Error('postId is required.');
+        const result = await api.likeThread(postId);
+        return { provider: 'threads', mode: 'like', postId, status: result.status };
+      });
+    },
+
+    async unlike({ postId } = {}) {
+      return withProviderSession(async () => {
+        if (!postId) throw new Error('postId is required.');
+        const result = await api.unlikeThread(postId);
+        return { provider: 'threads', mode: 'unlike', postId, status: result.status };
+      });
+    },
+
+    async follow({ username } = {}) {
+      return withProviderSession(async () => {
+        if (!username) throw new Error('username is required.');
+        const userId = await api.getUserId(username);
+        const result = await api.followUser(userId);
+        return {
+          provider: 'threads',
+          mode: 'follow',
+          username,
+          userId,
+          following: result.following,
+          outgoingRequest: result.outgoingRequest,
+          status: result.status,
+        };
+      });
+    },
+
+    async unfollow({ username } = {}) {
+      return withProviderSession(async () => {
+        if (!username) throw new Error('username is required.');
+        const userId = await api.getUserId(username);
+        const result = await api.unfollowUser(userId);
+        return {
+          provider: 'threads',
+          mode: 'unfollow',
+          username,
+          userId,
+          following: result.following,
+          status: result.status,
+        };
+      });
+    },
+
+    async getProfile({ username } = {}) {
+      return withProviderSession(async () => {
+        if (!username) throw new Error('username is required.');
+        const userId = await api.getUserId(username);
+        const profile = await api.getUserProfile(userId);
+        return { provider: 'threads', mode: 'profile', ...profile };
+      });
+    },
+
+    async getFeed() {
+      return withProviderSession(async () => {
+        const items = await api.getTimeline();
+        return {
+          provider: 'threads',
+          mode: 'feed',
+          count: items.length,
+          items,
+        };
+      });
+    },
+
+    async listPosts({ username, limit = 20 } = {}) {
+      return withProviderSession(async () => {
+        if (!username) throw new Error('username is required.');
+        const userId = await api.getUserId(username);
+        const posts = await api.getUserThreads(userId, limit);
+        return {
+          provider: 'threads',
+          mode: 'posts',
+          username,
+          totalCount: posts.length,
+          posts,
+        };
+      });
+    },
+
+    async search({ query, limit = 20 } = {}) {
+      return withProviderSession(async () => {
+        if (!query) throw new Error('query is required.');
+        const users = await api.searchUsers(query, limit);
+        return {
+          provider: 'threads',
+          mode: 'search',
+          query,
+          totalCount: users.length,
+          users,
+        };
+      });
+    },
+
+    async deletePost({ postId } = {}) {
+      return withProviderSession(async () => {
+        if (!postId) throw new Error('postId is required.');
+        const result = await api.deleteThread(postId);
+        return {
+          provider: 'threads',
+          mode: 'delete',
+          postId,
+          status: result.status,
+        };
+      });
+    },
+
+    rateLimitStatus() {
+      return {
+        provider: 'threads',
+        mode: 'rateLimitStatus',
+        ...api.getRateLimitStatus(),
+      };
+    },
+
+    async logout() {
+      clearProviderMeta('threads', account);
+      return {
+        provider: 'threads',
+        loggedOut: true,
+        sessionPath,
+      };
+    },
+  };
+};
+
+module.exports = createThreadsProvider;

package/src/providers/threads/session.js

@@ -0,0 +1,109 @@
+const fs = require('fs');
+const path = require('path');
+const { saveProviderMeta } = require('../../storage/sessionStore');
+const { readThreadsCredentials, parseThreadsSessionError, buildLoginErrorMessage } = require('./utils');
+
+const readSessionFile = (sessionPath) => {
+  if (!fs.existsSync(sessionPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(sessionPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+};
+
+const writeSessionFile = (sessionPath, data) => {
+  fs.mkdirSync(path.dirname(sessionPath), { recursive: true });
+  fs.writeFileSync(sessionPath, JSON.stringify(data, null, 2), 'utf-8');
+};
+
+const saveThreadsSession = (sessionPath, { token, userId, deviceId }) => {
+  const existing = readSessionFile(sessionPath) || {};
+  writeSessionFile(sessionPath, {
+    ...existing,
+    token,
+    userId,
+    deviceId,
+    updatedAt: new Date().toISOString(),
+  });
+};
+
+const loadThreadsSession = (sessionPath) => {
+  const raw = readSessionFile(sessionPath);
+  if (!raw?.token) return null;
+  return { token: raw.token, userId: raw.userId, deviceId: raw.deviceId };
+};
+
+const validateThreadsSession = (sessionPath) => {
+  const session = loadThreadsSession(sessionPath);
+  return Boolean(session?.token && session?.userId);
+};
+
+// ── Rate Limit persistence (per userId) ──
+
+const loadRateLimits = (sessionPath, userId) => {
+  const raw = readSessionFile(sessionPath);
+  return raw?.rateLimits?.[userId] || null;
+};
+
+const saveRateLimits = (sessionPath, userId, counters) => {
+  const raw = readSessionFile(sessionPath) || {};
+  if (!raw.rateLimits) raw.rateLimits = {};
+  raw.rateLimits[userId] = {
+    ...counters,
+    savedAt: new Date().toISOString(),
+  };
+  writeSessionFile(sessionPath, raw);
+};
+
+const createThreadsWithProviderSession = (askForAuthentication, account) => async (fn) => {
+  const credentials = readThreadsCredentials();
+  const hasCredentials = Boolean(credentials.username && credentials.password);
+
+  try {
+    const result = await fn();
+    saveProviderMeta('threads', { loggedIn: true, lastValidatedAt: new Date().toISOString() }, account);
+    return result;
+  } catch (error) {
+    if (!parseThreadsSessionError(error) || !hasCredentials) {
+      throw error;
+    }
+
+    try {
+      const loginResult = await askForAuthentication({
+        username: credentials.username,
+        password: credentials.password,
+      });
+
+      saveProviderMeta('threads', {
+        loggedIn: loginResult.loggedIn,
+        userId: loginResult.userId,
+        sessionPath: loginResult.sessionPath,
+        lastRefreshedAt: new Date().toISOString(),
+        lastError: null,
+      }, account);
+
+      if (!loginResult.loggedIn) {
+        throw new Error(loginResult.message || 'Login status could not be confirmed after session refresh.');
+      }
+
+      return fn();
+    } catch (reloginError) {
+      saveProviderMeta('threads', {
+        loggedIn: false,
+        lastError: buildLoginErrorMessage(reloginError),
+        lastValidatedAt: new Date().toISOString(),
+      }, account);
+      throw reloginError;
+    }
+  }
+};
+
+module.exports = {
+  saveThreadsSession,
+  loadThreadsSession,
+  validateThreadsSession,
+  loadRateLimits,
+  saveRateLimits,
+  createThreadsWithProviderSession,
+};

package/src/providers/threads/utils.js

@@ -0,0 +1,33 @@
+const readThreadsCredentials = () => {
+  const username = process.env.THREADS_USERNAME || process.env.INSTA_USERNAME || process.env.INSTAGRAM_USERNAME;
+  const password = process.env.THREADS_PASSWORD || process.env.INSTA_PASSWORD || process.env.INSTAGRAM_PASSWORD;
+  return {
+    username: typeof username === 'string' && username.trim() ? username.trim() : null,
+    password: typeof password === 'string' && password.trim() ? password.trim() : null,
+  };
+};
+
+const parseThreadsSessionError = (error) => {
+  const message = String(error?.message || '').toLowerCase();
+  return [
+    'no session file found',
+    'no valid token in session',
+    'session expired',
+    'login required',
+    'login_required',
+    'checkpoint_required',
+    '401',
+    '403',
+  ].some((token) => message.includes(token.toLowerCase()));
+};
+
+const buildLoginErrorMessage = (error) => String(error?.message || 'Session validation failed.');
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+module.exports = {
+  readThreadsCredentials,
+  parseThreadsSessionError,
+  buildLoginErrorMessage,
+  sleep,
+};

package/src/runner.js

@@ -132,7 +132,7 @@ const runCommand = async (command, opts = {}) => {
 
     case 'publish': {
       const content = readContent(opts);
-      if (!content && providerName !== 'insta' && providerName !== 'x' && providerName !== 'reddit') {
+      if (!content && providerName !== 'insta' && providerName !== 'x' && providerName !== 'reddit' && providerName !== 'threads') {
         throw createError('MISSING_CONTENT', 'publish requires --content or --content-file', 'viruagent-cli publish --spec');
       }
       return withProvider(() =>

package/src/services/providerManager.js

@@ -5,6 +5,7 @@ const createNaverProvider = require('../providers/naver');
 const createInstaProvider = require('../providers/insta');
 const createXProvider = require('../providers/x');
 const createRedditProvider = require('../providers/reddit');
+const createThreadsProvider = require('../providers/threads');
 
 const providerFactory = {
   tistory: createTistoryProvider,
@@ -12,9 +13,10 @@ const providerFactory = {
   insta: createInstaProvider,
   x: createXProvider,
   reddit: createRedditProvider,
+  threads: createThreadsProvider,
 };
 
-const providers = ['tistory', 'naver', 'insta', 'x', 'reddit'];
+const providers = ['tistory', 'naver', 'insta', 'x', 'reddit', 'threads'];
 
 const createProviderManager = () => {
   const cache = new Map();
@@ -40,7 +42,7 @@ const createProviderManager = () => {
     return cache.get(cacheKey);
   };
 
-  const providerNames = { tistory: 'Tistory', naver: 'Naver Blog', insta: 'Instagram', x: 'X (Twitter)', reddit: 'Reddit' };
+  const providerNames = { tistory: 'Tistory', naver: 'Naver Blog', insta: 'Instagram', x: 'X (Twitter)', reddit: 'Reddit', threads: 'Threads' };
   const getAvailableProviders = () => providers.map((provider) => ({
     id: provider,
     name: providerNames[provider] || provider,