opencli-plugin-socialdatax 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SocialDataX
+
+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,62 @@
+# SocialDataX OpenCLI Plugin | 社媒数据助手 OpenCLI 插件
+
+SocialDataX / 社媒数据助手 provides hosted, read-only social data tools for 小红书 / Xiaohongshu / XHS / RedNote and 抖音 / Douyin workflows.
+
+Use this OpenCLI plugin when you want API Key based data access without relying on a logged-in browser session. It is a complement to OpenCLI's built-in browser-backed `xiaohongshu` adapter, not a replacement for that adapter.
+
+- Product: `SocialDataX` / `社媒数据助手`
+- Website: <https://socialdatax.com>
+- Platforms: 小红书 / Xiaohongshu / XHS / RedNote, 抖音 / Douyin
+- Runtime package: `socialdatax-skills@latest`
+- API key environment variable: `SOCIALDATAX_API_KEY`
+
+## Local Install
+
+```bash
+opencli plugin install /Users/devin/work/cx/code/social-service/public-listings/socialdatax-opencli
+```
+
+Set your API Key before data calls:
+
+```bash
+export SOCIALDATAX_API_KEY="<SOCIALDATAX_API_KEY>"
+```
+
+## Commands
+
+```bash
+opencli socialdatax xhs-search --keyword "露营桌" -f json
+opencli socialdatax xhs-detail --note-id "<note_id>" -f json
+opencli socialdatax xhs-comments --note-id "<note_id>" -f table
+opencli socialdatax xhs-sub-comments --note-id "<note_id>" --comment-id "<comment_id>" -f table
+opencli socialdatax xhs-user-info --user-id "<user_id>" -f json
+opencli socialdatax xhs-user-posts --user-id "<user_id>" -f table
+
+opencli socialdatax douyin-search --keyword "露营桌" -f json
+opencli socialdatax douyin-detail --aweme-id "<aweme_id>" -f json
+opencli socialdatax douyin-comments --aweme-id "<aweme_id>" -f table
+opencli socialdatax douyin-user-info --sec-user-id "<sec_user_id>" -f json
+opencli socialdatax douyin-user-posts --sec-user-id "<sec_user_id>" -f table
+```
+
+Each command forwards to `npx -y socialdatax-skills@latest ...` and flattens returned JSON so OpenCLI can render table, JSON, YAML, or CSV output.
+
+## Read-Only Boundary
+
+This plugin only reads public content data through hosted SocialDataX services. It does not log in to user accounts, read browser data, publish posts, like, comment, follow, edit, delete, or perform account actions.
+
+## Search Aliases
+
+Users and agents may search for this plugin with:
+
+- `SocialDataX`
+- `社媒数据助手`
+- `小红书`
+- `Xiaohongshu`
+- `XHS`
+- `RedNote`
+- `抖音`
+- `Douyin`
+- `social media data`
+- `creator analytics`
+- `comment analysis`

package/lib/socialdatax-core.mjs

@@ -0,0 +1,303 @@
+import { spawn } from "node:child_process";
+
+export const PRODUCT_NAME = "SocialDataX / 社媒数据助手";
+export const PRIMARY_API_KEY_ENV = "SOCIALDATAX_API_KEY";
+export const DEFAULT_PACKAGE_SPEC = "socialdatax-skills@latest";
+
+const TOOL_COMMANDS = {
+  "xhs-search": {
+    platform: "xhs",
+    action: "search",
+    listPath: ["data", "items"],
+    pageMeta: ["next_page", "total_count"],
+    options: {
+      keyword: "--keyword",
+      page: "--page",
+      sortType: "--sort-type",
+      noteType: "--note-type",
+      publishTimeRange: "--publish-time-range",
+    },
+  },
+  "xhs-detail": {
+    platform: "xhs",
+    action: "detail",
+    options: {
+      noteId: "--note-id",
+      url: "--url",
+    },
+  },
+  "xhs-comments": {
+    platform: "xhs",
+    action: "comments",
+    listPath: ["data", "items"],
+    pageMeta: ["next_page_token", "comment_count", "top_level_comment_count"],
+    options: {
+      noteId: "--note-id",
+      url: "--url",
+      pageToken: "--page-token",
+    },
+  },
+  "xhs-sub-comments": {
+    platform: "xhs",
+    action: "sub-comments",
+    listPath: ["data", "items"],
+    pageMeta: ["next_page_token"],
+    options: {
+      noteId: "--note-id",
+      commentId: "--comment-id",
+      pageToken: "--page-token",
+    },
+  },
+  "xhs-user-info": {
+    platform: "xhs",
+    action: "user-info",
+    options: {
+      userId: "--user-id",
+      profileUrl: "--profile-url",
+    },
+  },
+  "xhs-user-posts": {
+    platform: "xhs",
+    action: "user-posts",
+    listPath: ["data", "items"],
+    pageMeta: ["next_page_token"],
+    options: {
+      userId: "--user-id",
+      profileUrl: "--profile-url",
+      pageToken: "--page-token",
+    },
+  },
+  "douyin-search": {
+    platform: "douyin",
+    action: "search",
+    listPath: ["data", "items"],
+    pageMeta: ["next_page_token"],
+    options: {
+      keyword: "--keyword",
+      pageToken: "--page-token",
+      sortType: "--sort-type",
+      publishTimeRange: "--publish-time-range",
+      durationRange: "--duration-range",
+      contentType: "--content-type",
+    },
+  },
+  "douyin-detail": {
+    platform: "douyin",
+    action: "detail",
+    options: {
+      awemeId: "--aweme-id",
+      url: "--url",
+    },
+  },
+  "douyin-comments": {
+    platform: "douyin",
+    action: "comments",
+    listPath: ["data", "items"],
+    pageMeta: ["next_page_token", "comment_count"],
+    options: {
+      awemeId: "--aweme-id",
+      url: "--url",
+      pageToken: "--page-token",
+    },
+  },
+  "douyin-user-info": {
+    platform: "douyin",
+    action: "user-info",
+    options: {
+      secUserId: "--sec-user-id",
+      profileUrl: "--profile-url",
+    },
+  },
+  "douyin-user-posts": {
+    platform: "douyin",
+    action: "user-posts",
+    listPath: ["data", "items"],
+    pageMeta: ["next_page_token"],
+    options: {
+      secUserId: "--sec-user-id",
+      profileUrl: "--profile-url",
+      pageToken: "--page-token",
+    },
+  },
+};
+
+const OPTION_ALIASES = {
+  "aweme-id": "awemeId",
+  "comment-id": "commentId",
+  "content-type": "contentType",
+  "duration-range": "durationRange",
+  keyword: "keyword",
+  "note-id": "noteId",
+  "note-type": "noteType",
+  page: "page",
+  "page-token": "pageToken",
+  "profile-url": "profileUrl",
+  "publish-time-range": "publishTimeRange",
+  "sec-user-id": "secUserId",
+  "sort-type": "sortType",
+  url: "url",
+  "user-id": "userId",
+};
+
+export function listSocialDataXCommands() {
+  return Object.keys(TOOL_COMMANDS);
+}
+
+export function normalizeCommandName(commandName) {
+  return commandName.replace(/^socialdatax[-:]/, "");
+}
+
+export function normalizeOptions(input = {}) {
+  const normalized = {};
+  for (const [key, value] of Object.entries(input)) {
+    const canonical = OPTION_ALIASES[key] || key;
+    normalized[canonical] = value;
+  }
+  return normalized;
+}
+
+export function buildSocialDataXArgs(commandName, inputOptions = {}) {
+  const normalizedCommand = normalizeCommandName(commandName);
+  const command = TOOL_COMMANDS[normalizedCommand];
+  if (!command) {
+    throw new Error(
+      `Unsupported SocialDataX command "${commandName}". Use one of: ${listSocialDataXCommands().join(", ")}.`
+    );
+  }
+
+  const options = normalizeOptions(inputOptions);
+  const args = [command.platform, command.action];
+  for (const [optionKey, cliFlag] of Object.entries(command.options)) {
+    const value = options[optionKey];
+    if (value === undefined || value === null || value === false || value === "") {
+      continue;
+    }
+    args.push(cliFlag, String(value));
+  }
+  return args;
+}
+
+export function buildSocialDataXProcess(commandName, inputOptions = {}, env = process.env) {
+  const apiKey = env[PRIMARY_API_KEY_ENV];
+  if (!apiKey) {
+    throw new Error(`Missing API Key. Set ${PRIMARY_API_KEY_ENV} before running SocialDataX OpenCLI commands.`);
+  }
+
+  const mockBin = env.SOCIALDATAX_OPENCLI_SKILLS_BIN;
+  if (mockBin) {
+    return {
+      file: mockBin,
+      args: buildSocialDataXArgs(commandName, inputOptions),
+    };
+  }
+
+  return {
+    file: "npx",
+    args: ["-y", env.SOCIALDATAX_OPENCLI_PACKAGE_SPEC || DEFAULT_PACKAGE_SPEC, ...buildSocialDataXArgs(commandName, inputOptions)],
+  };
+}
+
+export async function runSocialDataXCommand(commandName, inputOptions = {}, runtime = {}) {
+  const env = runtime.env || process.env;
+  const spawn = runtime.spawn || spawnJsonCommand;
+  const processSpec = buildSocialDataXProcess(commandName, inputOptions, env);
+  const envelope = await spawn(processSpec.file, processSpec.args, {
+    env: { ...env },
+  });
+  return flattenSocialDataXEnvelope(commandName, envelope);
+}
+
+export async function spawnJsonCommand(file, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(file, args, {
+      env: options.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (status) => {
+      if (status !== 0) {
+        reject(new Error(trimError(stderr) || `socialdatax-skills exited with status ${status}.`));
+        return;
+      }
+      try {
+        resolve(JSON.parse(stdout));
+      } catch (error) {
+        reject(new Error(`Failed to parse socialdatax-skills JSON output: ${error.message}`));
+      }
+    });
+  });
+}
+
+export function flattenSocialDataXEnvelope(commandName, envelope) {
+  const normalizedCommand = normalizeCommandName(commandName);
+  const command = TOOL_COMMANDS[normalizedCommand];
+  if (!command) {
+    throw new Error(`Unsupported SocialDataX command "${commandName}".`);
+  }
+  if (!command.listPath) {
+    return [flattenObject(envelope?.data ?? envelope)];
+  }
+
+  const items = getPath(envelope, command.listPath);
+  if (!Array.isArray(items)) {
+    return [];
+  }
+
+  const meta = {};
+  for (const key of command.pageMeta || []) {
+    if (envelope?.data && Object.prototype.hasOwnProperty.call(envelope.data, key)) {
+      meta[key] = envelope.data[key];
+    }
+  }
+  return items.map((item) => flattenObject({ ...meta, ...item }));
+}
+
+export function flattenObject(value, prefix = "", output = {}) {
+  if (value === null || value === undefined) {
+    if (prefix) {
+      output[prefix] = value ?? "";
+    }
+    return output;
+  }
+  if (Array.isArray(value)) {
+    if (prefix) {
+      output[prefix] = JSON.stringify(value);
+    }
+    return output;
+  }
+  if (typeof value !== "object") {
+    if (prefix) {
+      output[prefix] = value;
+    }
+    return output;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    const childKey = prefix ? `${prefix}_${key}` : key;
+    if (child && typeof child === "object" && !Array.isArray(child)) {
+      flattenObject(child, childKey, output);
+    } else if (Array.isArray(child)) {
+      output[childKey] = JSON.stringify(child);
+    } else {
+      output[childKey] = child ?? "";
+    }
+  }
+  return output;
+}
+
+function getPath(value, path) {
+  return path.reduce((current, key) => current?.[key], value);
+}
+
+function trimError(text) {
+  return String(text || "").trim();
+}

package/opencli-plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "socialdatax",
+  "displayName": "SocialDataX / 社媒数据助手",
+  "description": "SocialDataX / 社媒数据助手 provides hosted read-only social data tools for 小红书 / Xiaohongshu / XHS / RedNote and 抖音 / Douyin: search content, read details, analyze comments, creator profiles, and creator posts.",
+  "version": "0.1.0",
+  "opencli": ">=1.0.0",
+  "homepage": "https://socialdatax.com",
+  "keywords": [
+    "SocialDataX",
+    "社媒数据助手",
+    "小红书",
+    "Xiaohongshu",
+    "XHS",
+    "RedNote",
+    "抖音",
+    "Douyin",
+    "social media data",
+    "content insights",
+    "creator analytics",
+    "comments"
+  ],
+  "commands": [
+    "socialdatax"
+  ]
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "opencli-plugin-socialdatax",
+  "version": "0.1.0",
+  "description": "SocialDataX / 社媒数据助手 OpenCLI plugin for 小红书, Xiaohongshu, XHS, RedNote, 抖音, and Douyin read-only social data workflows.",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "README.md",
+    "LICENSE",
+    "opencli-plugin.json",
+    "socialdatax.ts",
+    "lib/**",
+    "skills/**"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "socialdatax",
+    "社媒数据助手",
+    "opencli",
+    "opencli-plugin",
+    "xiaohongshu",
+    "小红书",
+    "xhs",
+    "rednote",
+    "douyin",
+    "抖音",
+    "social-media",
+    "social-data",
+    "content-analysis",
+    "creator-analytics"
+  ],
+  "homepage": "https://socialdatax.com",
+  "bugs": {
+    "url": "https://socialdatax.com"
+  },
+  "engines": {
+    "node": ">=21.0.0"
+  },
+  "peerDependencies": {
+    "@jackwener/opencli": ">=1.0.0"
+  }
+}

package/skills/socialdatax-opencli/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: socialdatax-opencli
+description: Use SocialDataX / 社媒数据助手 through OpenCLI for read-only 小红书 / Xiaohongshu / XHS / RedNote and 抖音 / Douyin social data workflows including search, details, comments, creator profiles, and creator posts.
+metadata:
+  opencli:
+    requires:
+      env:
+        - SOCIALDATAX_API_KEY
+      bins:
+        - opencli
+        - node
+        - npm
+    primaryEnv: SOCIALDATAX_API_KEY
+    homepage: https://socialdatax.com
+---
+
+# SocialDataX OpenCLI
+
+Use this skill when the user asks to use OpenCLI for SocialDataX / 社媒数据助手, 小红书 / Xiaohongshu / XHS / RedNote, or 抖音 / Douyin read-only data workflows.
+
+Prefer the OpenCLI plugin commands when installed:
+
+```bash
+opencli socialdatax xhs-search --keyword "<keyword>" -f json
+opencli socialdatax xhs-detail --note-id "<note_id>" -f json
+opencli socialdatax xhs-comments --note-id "<note_id>" -f table
+opencli socialdatax xhs-sub-comments --note-id "<note_id>" --comment-id "<comment_id>" -f table
+opencli socialdatax xhs-user-info --user-id "<user_id>" -f json
+opencli socialdatax xhs-user-posts --user-id "<user_id>" -f table
+opencli socialdatax douyin-search --keyword "<keyword>" -f json
+opencli socialdatax douyin-detail --aweme-id "<aweme_id>" -f json
+opencli socialdatax douyin-comments --aweme-id "<aweme_id>" -f table
+opencli socialdatax douyin-user-info --sec-user-id "<sec_user_id>" -f json
+opencli socialdatax douyin-user-posts --sec-user-id "<sec_user_id>" -f table
+```
+
+If the OpenCLI plugin is not installed, fall back to the direct CLI:
+
+```bash
+npx -y socialdatax-skills@latest xhs search --keyword "<keyword>" --pretty
+npx -y socialdatax-skills@latest douyin search --keyword "<keyword>" --pretty
+```
+
+Set `SOCIALDATAX_API_KEY` before data calls. This skill is read-only: do not use it for login, posting, liking, commenting, following, editing, deleting, or other account actions.
+
+OpenCLI's built-in `xiaohongshu` adapter is browser-session based. `opencli socialdatax ...` is API Key based hosted data access and covers both 小红书 / Xiaohongshu / XHS / RedNote and 抖音 / Douyin.

package/socialdatax.ts

@@ -0,0 +1,145 @@
+import { cli, Strategy } from "@jackwener/opencli/registry";
+import { runSocialDataXCommand } from "./lib/socialdatax-core.mjs";
+
+const COMMON_COLUMNS = [
+  "note_id",
+  "note_url",
+  "aweme_id",
+  "sec_user_id",
+  "comment_id",
+  "title",
+  "desc",
+  "content",
+  "nickname",
+  "author_nickname",
+  "profile_nickname",
+  "like_count",
+  "comment_count",
+  "top_level_comment_count",
+  "next_page",
+  "next_page_token",
+];
+
+const pageTokenOption = {
+  name: "page-token",
+  type: "string",
+  help: "Opaque pagination token returned by the previous page.",
+};
+
+function localCommand(name, description, options = {}) {
+  return cli({
+    site: "socialdatax",
+    name,
+    description,
+    access: "read",
+    example: `opencli socialdatax ${name} -f json`,
+    strategy: Strategy.LOCAL,
+    browser: false,
+    args: options,
+    columns: COMMON_COLUMNS,
+    async func(argv) {
+      return runSocialDataXCommand(name, argv);
+    },
+  });
+}
+
+localCommand(
+  "xhs-search",
+  "Search 小红书 / Xiaohongshu / XHS / RedNote notes with SocialDataX / 社媒数据助手.",
+  [
+    { name: "keyword", type: "string", required: true, help: "Search keyword." },
+    { name: "page", type: "int", help: "1-based page number." },
+    { name: "sort-type", type: "string", help: "general, time_descending, like_count_descending, comment_count_descending, or collect_count_descending." },
+    { name: "note-type", type: "string", help: "all, image, or video." },
+    { name: "publish-time-range", type: "string", help: "all, day, week, or half_year." },
+  ]
+);
+localCommand(
+  "xhs-detail",
+  "Read one 小红书 / Xiaohongshu / XHS / RedNote note detail.",
+  [
+    { name: "note-id", type: "string", help: "Known XHS note ID." },
+    { name: "url", type: "string", help: "XHS note URL, short link, share text, or note ID." },
+  ]
+);
+localCommand(
+  "xhs-comments",
+  "Fetch 小红书 / Xiaohongshu / XHS / RedNote first-level comments.",
+  [
+    { name: "note-id", type: "string", help: "Known XHS note ID." },
+    { name: "url", type: "string", help: "XHS note URL, short link, or share text." },
+    pageTokenOption,
+  ]
+);
+localCommand(
+  "xhs-sub-comments",
+  "Fetch 小红书 / Xiaohongshu / XHS / RedNote replies under one comment.",
+  [
+    { name: "note-id", type: "string", required: true, help: "Known XHS note ID." },
+    { name: "comment-id", type: "string", required: true, help: "First-level comment ID." },
+    pageTokenOption,
+  ]
+);
+localCommand(
+  "xhs-user-info",
+  "Read 小红书 / Xiaohongshu / XHS / RedNote creator profile data.",
+  [
+    { name: "user-id", type: "string", help: "Known XHS user ID." },
+    { name: "profile-url", type: "string", help: "XHS profile URL, short link, or share text." },
+  ]
+);
+localCommand(
+  "xhs-user-posts",
+  "Fetch 小红书 / Xiaohongshu / XHS / RedNote creator notes.",
+  [
+    { name: "user-id", type: "string", help: "Known XHS user ID." },
+    { name: "profile-url", type: "string", help: "XHS profile URL, short link, or share text." },
+    pageTokenOption,
+  ]
+);
+localCommand(
+  "douyin-search",
+  "Search 抖音 / Douyin works with SocialDataX / 社媒数据助手.",
+  [
+    { name: "keyword", type: "string", required: true, help: "Search keyword." },
+    pageTokenOption,
+    { name: "sort-type", type: "string", help: "general, time_descending, or like_count_descending." },
+    { name: "publish-time-range", type: "string", help: "all, day, week, or half_year." },
+    { name: "duration-range", type: "string", help: "all, under_1_minute, one_to_five_minutes, or over_5_minutes." },
+    { name: "content-type", type: "string", help: "all, video, or image." },
+  ]
+);
+localCommand(
+  "douyin-detail",
+  "Read one 抖音 / Douyin work detail.",
+  [
+    { name: "aweme-id", type: "string", help: "Known Douyin aweme_id." },
+    { name: "url", type: "string", help: "Douyin content URL, short link, or share text." },
+  ]
+);
+localCommand(
+  "douyin-comments",
+  "Fetch 抖音 / Douyin first-level comments.",
+  [
+    { name: "aweme-id", type: "string", help: "Known Douyin aweme_id." },
+    { name: "url", type: "string", help: "Douyin content URL, short link, or share text." },
+    pageTokenOption,
+  ]
+);
+localCommand(
+  "douyin-user-info",
+  "Read 抖音 / Douyin creator profile data.",
+  [
+    { name: "sec-user-id", type: "string", help: "Known Douyin sec_user_id." },
+    { name: "profile-url", type: "string", help: "Douyin profile URL, short link, or share text." },
+  ]
+);
+localCommand(
+  "douyin-user-posts",
+  "Fetch 抖音 / Douyin creator works.",
+  [
+    { name: "sec-user-id", type: "string", help: "Known Douyin sec_user_id." },
+    { name: "profile-url", type: "string", help: "Douyin profile URL, short link, or share text." },
+    pageTokenOption,
+  ]
+);