@northmoon-labs/social-cli 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 Northmoon Labs
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,478 @@
+# Northmoon Social CLI
+
+`nmsocial` 是给 Agent 使用的 Northmoon Social 命令行工具，让 Agent 可以通过稳定的命令完成社媒账号授权、素材管理、内容发布、评论处理、数据统计和自动回复配置。
+
+你可以使用 `nmsocial` 完成：
+
+- 获取社媒账号授权链接
+- 查询已授权账号
+- 上传视频和图片素材
+- 创建视频 / 图文发布任务
+- 查询发布任务和发布记录
+- 查询评论并回复评论
+- 配置 webhook 转发地址
+- 查询账号、作品、平台统计数据
+- 管理自动回复策略
+
+## 安装
+
+```bash
+npm install -g @northmoon-labs/social-cli
+```
+
+检查是否安装成功：
+
+```bash
+nmsocial --help
+```
+
+也可以直接用 `npx` 运行：
+
+```bash
+npx @northmoon-labs/social-cli --help
+```
+
+## 登录
+
+推荐使用 `--api-key-stdin` 登录，避免 API Key 出现在 shell history 中：
+
+```bash
+nmsocial login --api-key-stdin
+```
+
+如果是 Agent 或自动化客户端调用，也可以直接传入 API Key：
+
+```bash
+nmsocial login --api-key YOUR_KEY
+```
+
+使用 `--api-key` 更方便自动化，但要注意不要把包含 API Key 的命令输出到公开日志中。
+
+查看当前登录状态：
+
+```bash
+nmsocial status
+```
+
+退出登录：
+
+```bash
+nmsocial logout
+```
+
+## 更新 CLI
+
+检查是否有新版本：
+
+```bash
+nmsocial update check
+```
+
+更新到 npm 上的最新版本：
+
+```bash
+nmsocial update
+```
+
+只查看将要执行的安装命令，不实际更新：
+
+```bash
+nmsocial update --dry-run
+```
+
+默认会根据当前运行环境选择包管理器，无法判断时使用 `npm`。你也可以手动指定：
+
+```bash
+nmsocial update --manager npm
+nmsocial update --manager pnpm
+nmsocial update --manager bun
+```
+
+## 给 Agent 使用
+
+npm 包内包含一份给 Agent 阅读的 CLI 使用说明：
+
+```text
+skills/nmsocial-cli/SKILL.md
+```
+
+如果你的 Agent 支持读取 skill、工具说明或外部上下文，可以把这个文件提供给它。该文件只说明如何调用 `nmsocial`，不包含内部开发文档。
+
+## 全局参数
+
+| 参数 | 说明 |
+| --- | --- |
+| `--json` | 输出稳定 JSON，适合脚本解析 |
+| `--timeout MS` | 设置请求超时时间，单位毫秒 |
+| `--dry-run` | 只预览请求内容，不发送请求 |
+| `--help` | 查看帮助 |
+| `--version` | 查看版本 |
+
+## 输出格式
+
+默认输出为简洁文本或表格，适合在终端里快速查看，也能减少 Agent 阅读结果时的无关内容。
+
+如果要让脚本或 Agent 稳定解析返回结果，请加上 `--json`：
+
+```bash
+nmsocial accounts list --platform tiktok --json
+```
+
+## 平台参数
+
+涉及平台的命令支持平台名称或平台数字：
+
+| 平台名称 | 平台数字 |
+| --- | --- |
+| `tiktok` | `1` |
+| `youtube` | `2` |
+| `instagram` | `3` |
+| `facebook` | `4` |
+
+示例：
+
+```bash
+nmsocial auth-url --platform tiktok
+nmsocial auth-url --platform 1
+```
+
+## 账号授权
+
+获取授权链接：
+
+```bash
+nmsocial auth-url --platform tiktok
+```
+
+查询已授权账号：
+
+```bash
+nmsocial accounts list --platform tiktok --status 1 --page 1 --page-size 20
+```
+
+按条件筛选账号：
+
+```bash
+nmsocial accounts list \
+  --platform youtube \
+  --username demo \
+  --is-verified 1 \
+  --page-size 50
+```
+
+## YouTube 剧集
+
+查询剧集列表：
+
+```bash
+nmsocial youtube series list --open-id CHANNEL_ID
+```
+
+创建剧集：
+
+```bash
+nmsocial youtube series create \
+  --open-id CHANNEL_ID \
+  --title "Demo Series" \
+  --description "Demo description"
+```
+
+创建前预览请求内容：
+
+```bash
+nmsocial youtube series create \
+  --open-id CHANNEL_ID \
+  --title "Demo Series" \
+  --dry-run \
+  --json
+```
+
+## 素材
+
+查询素材列表：
+
+```bash
+nmsocial materials list --type 1 --title demo --page 1 --page-size 20
+```
+
+上传素材：
+
+```bash
+nmsocial materials upload ./demo.mp4
+```
+
+支持的文件类型：
+
+- 视频：`mp4`、`mov`、`avi`、`mkv`、`webm`、`flv`、`wmv`、`m4v`、`3gp`
+- 图片：`jpg`、`jpeg`、`png`、`gif`、`bmp`、`webp`、`heic`、`heif`、`tif`、`tiff`
+
+上传后的素材默认保留七天。
+
+## 发布任务
+
+创建视频发布任务：
+
+```bash
+nmsocial publish video \
+  --account OPEN_ID_1 \
+  --account OPEN_ID_2 \
+  --content https://example.com/video1.mp4 \
+  --caption "hello"
+```
+
+创建图文发布任务：
+
+```bash
+nmsocial publish image \
+  --account OPEN_ID \
+  --content https://example.com/image1.png \
+  --content https://example.com/image2.png \
+  --title "title" \
+  --caption "caption"
+```
+
+定时发布：
+
+```bash
+nmsocial publish video \
+  --account OPEN_ID \
+  --content https://example.com/video.mp4 \
+  --at 2026-07-18T10:00:00+08:00
+```
+
+创建前预览请求内容：
+
+```bash
+nmsocial publish video \
+  --account OPEN_ID \
+  --content https://example.com/video.mp4 \
+  --video-assign-type 1 \
+  --privacy public \
+  --dry-run \
+  --json
+```
+
+`--account`、`--content`、`--playlist-id` 等参数可以重复传入。
+
+## 任务查询
+
+查询发布任务：
+
+```bash
+nmsocial tasks list --platform tiktok --page 1 --page-size 20
+```
+
+按发布方式或时间筛选：
+
+```bash
+nmsocial tasks list \
+  --platform tiktok \
+  --video-assign-type 1 \
+  --create-time-begin 1783990000000 \
+  --create-time-end 1784000000000
+```
+
+## 发布记录
+
+查询发布记录：
+
+```bash
+nmsocial posts list --platform tiktok --open-id OPEN_ID
+```
+
+查询已发布作品统计：
+
+```bash
+nmsocial posts stats --platform tiktok --main-task-id TASK_ID
+```
+
+## 评论
+
+查询评论：
+
+```bash
+nmsocial comments list --platform tiktok --open-id OPEN_ID
+```
+
+回复评论：
+
+```bash
+nmsocial comments reply \
+  --platform tiktok \
+  --open-id OPEN_ID \
+  --video-id VIDEO_ID \
+  --comment-id COMMENT_ID \
+  --text "Thanks"
+```
+
+回复前预览请求内容：
+
+```bash
+nmsocial comments reply \
+  --platform tiktok \
+  --open-id OPEN_ID \
+  --video-id VIDEO_ID \
+  --comment-id COMMENT_ID \
+  --text "Thanks" \
+  --dry-run \
+  --json
+```
+
+## Webhook
+
+设置 webhook 转发地址：
+
+```bash
+nmsocial webhook set --url https://partner.example.com/spost/webhook
+```
+
+关闭 webhook 转发：
+
+```bash
+nmsocial webhook disable
+```
+
+## 数据统计
+
+查询统计概览：
+
+```bash
+nmsocial stats overview --platform tiktok --start-date 2026-07-11 --end-date 2026-07-17
+```
+
+查询账号趋势：
+
+```bash
+nmsocial stats account trend --platform tiktok --metric followers
+```
+
+查询账号排行：
+
+```bash
+nmsocial stats account rank --metric followerIncrease --order desc --page 1 --page-size 20
+```
+
+查询作品趋势：
+
+```bash
+nmsocial stats post trend --platform tiktok --metric viewCount
+```
+
+查询作品排行：
+
+```bash
+nmsocial stats post rank --metric viewIncrease --order desc --page 1 --page-size 20
+```
+
+查询单个作品趋势：
+
+```bash
+nmsocial stats post detail-trend \
+  --post-id POST_ID \
+  --metric viewCount \
+  --metric likeCount \
+  --metric commentCount
+```
+
+查询平台汇总：
+
+```bash
+nmsocial stats platform summary --start-date 2026-07-11 --end-date 2026-07-17
+```
+
+日期参数格式为 `yyyy-MM-dd`。
+
+## 自动回复
+
+查询自动回复策略：
+
+```bash
+nmsocial auto-replies list --platform tiktok --page 1 --page-size 20
+```
+
+查看策略详情：
+
+```bash
+nmsocial auto-replies detail --id STRATEGY_ID
+```
+
+创建策略：
+
+```bash
+nmsocial auto-replies create \
+  --name "Demo auto reply" \
+  --platform tiktok \
+  --account-id ACCOUNT_RECORD_ID \
+  --trigger-rule keyword \
+  --keyword price \
+  --keyword coupon \
+  --send-rule sequence \
+  --content "Thanks for your comment" \
+  --content-delay 0 \
+  --once-per-user false \
+  --repeat-interval-hours 24 \
+  --stop-on-user-reply true \
+  --enabled true
+```
+
+通过 JSON 文件创建：
+
+```bash
+nmsocial auto-replies create --from-file ./auto-reply.json --dry-run --json
+```
+
+通过 JSON 文件更新：
+
+```bash
+nmsocial auto-replies update --id STRATEGY_ID --from-file ./auto-reply.json
+```
+
+启用、停用或删除策略：
+
+```bash
+nmsocial auto-replies enable --id STRATEGY_ID
+nmsocial auto-replies disable --id STRATEGY_ID
+nmsocial auto-replies delete --id STRATEGY_ID
+```
+
+## JSON 输出
+
+需要在脚本中解析输出时，建议使用 `--json`。
+
+成功响应：
+
+```json
+{
+  "ok": true,
+  "data": {},
+  "error": null,
+  "meta": {
+    "providerCode": 200,
+    "providerMessage": "ok",
+    "providerTimestamp": "2026-07-14T15:34:08.576+08:00",
+    "requestId": "11"
+  }
+}
+```
+
+错误响应：
+
+```json
+{
+  "ok": false,
+  "data": null,
+  "error": {
+    "code": "SOCIAL_API_ERROR",
+    "message": "invalid api key",
+    "status": 403,
+    "payload": {}
+  },
+  "meta": null
+}
+```
+
+## 使用建议
+
+- 创建或更新发布任务、评论回复、webhook、自动回复策略前，可以先使用 `--dry-run --json` 预览请求内容。
+- `nmsocial status` 会隐藏完整 API Key。
+- 不要把 API Key 直接写在 shell 命令中。

package/dist/bin/nmsocial.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { parseArgv } from '../cli/args.js';
+import { printError, printSuccess } from '../cli/output.js';
+import { runCommand } from '../cli/router.js';
+const parsed = parseArgv(process.argv.slice(2));
+const json = Boolean(parsed.options.json);
+try {
+    const result = await runCommand(parsed);
+    printSuccess(result.data, result.provider, json);
+}
+catch (error) {
+    printError(error, json);
+    process.exitCode = 1;
+}

package/dist/cli/args.js

@@ -0,0 +1,103 @@
+import { CliError } from './output.js';
+const BOOLEAN_FLAGS = new Set([
+    'json',
+    'verbose',
+    'help',
+    'version',
+    'dry-run',
+    'api-key-stdin'
+]);
+export function parseArgv(argv) {
+    const positionals = [];
+    const options = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === '--') {
+            positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        if (!token.startsWith('--')) {
+            positionals.push(token);
+            continue;
+        }
+        const raw = token.slice(2);
+        const eq = raw.indexOf('=');
+        const key = eq >= 0 ? raw.slice(0, eq) : raw;
+        let parsedValue;
+        if (eq >= 0) {
+            parsedValue = raw.slice(eq + 1);
+        }
+        else if (BOOLEAN_FLAGS.has(key)) {
+            parsedValue = true;
+        }
+        else {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith('--')) {
+                throw new CliError('VALIDATION_REQUIRED_OPTION', `--${key} requires a value`);
+            }
+            parsedValue = next;
+            i += 1;
+        }
+        if (options[key] === undefined) {
+            options[key] = parsedValue;
+        }
+        else if (Array.isArray(options[key])) {
+            options[key].push(parsedValue);
+        }
+        else {
+            options[key] = [options[key], parsedValue];
+        }
+    }
+    return { positionals, options };
+}
+export function values(options, key) {
+    const value = options[key];
+    if (value === undefined)
+        return [];
+    return (Array.isArray(value) ? value : [value]).map((item) => String(item));
+}
+export function value(options, key) {
+    const raw = options[key];
+    if (raw === undefined)
+        return undefined;
+    const list = Array.isArray(raw) ? raw : [raw];
+    const latest = list[list.length - 1];
+    if (latest === true)
+        return 'true';
+    if (latest === false)
+        return 'false';
+    return latest;
+}
+export function has(options, key) {
+    return options[key] !== undefined;
+}
+export function requireOption(options, key) {
+    const result = value(options, key);
+    if (result === undefined || result === '') {
+        throw new CliError('VALIDATION_REQUIRED_OPTION', `missing required option --${key}`);
+    }
+    return result;
+}
+export function intOption(options, key, allowed) {
+    const raw = value(options, key);
+    if (raw === undefined)
+        return undefined;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed)) {
+        throw new CliError('VALIDATION_INVALID_OPTION', `--${key} must be an integer`);
+    }
+    if (allowed && !allowed.includes(parsed)) {
+        throw new CliError('VALIDATION_INVALID_OPTION', `--${key} must be one of ${allowed.join(', ')}`);
+    }
+    return parsed;
+}
+export function positiveIntOption(options, key, defaultValue) {
+    const raw = value(options, key);
+    if (raw === undefined)
+        return defaultValue;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new CliError('VALIDATION_INVALID_OPTION', `--${key} must be a positive integer`);
+    }
+    return parsed;
+}

package/dist/cli/config.js

@@ -0,0 +1,69 @@
+import { chmod, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { CliError } from './output.js';
+const CONFIG_PATH = join(homedir(), '.nmsocial', 'config.json');
+const DEFAULT_API_URL = 'https://cloud.spost.ai';
+export function getConfigPath() {
+    return CONFIG_PATH;
+}
+export function defaultApiUrl() {
+    return DEFAULT_API_URL;
+}
+export async function readLocalConfig() {
+    try {
+        const text = await readFile(CONFIG_PATH, 'utf8');
+        return JSON.parse(text);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT')
+            return {};
+        if (error instanceof SyntaxError) {
+            throw new CliError('CONFIG_INVALID_FILE', `invalid config JSON at ${CONFIG_PATH}`);
+        }
+        throw error;
+    }
+}
+export async function writeLocalConfig(config) {
+    await mkdir(dirname(CONFIG_PATH), { recursive: true, mode: 0o700 });
+    await writeFile(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    await chmod(dirname(CONFIG_PATH), 0o700).catch(() => { });
+    await chmod(CONFIG_PATH, 0o600).catch(() => { });
+}
+export async function deleteLocalConfig() {
+    await rm(CONFIG_PATH, { force: true });
+}
+export async function configFileMode() {
+    try {
+        const info = await stat(CONFIG_PATH);
+        return (info.mode & 0o777).toString(8).padStart(3, '0');
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+export async function resolveConfig(options, { requireApiKey = true } = {}) {
+    const local = await readLocalConfig();
+    const apiUrl = options['api-url'] || process.env.NMSOCIAL_API_URL || local.apiUrl || DEFAULT_API_URL;
+    const apiKey = process.env.NMSOCIAL_API_KEY || local.apiKey;
+    validateApiUrl(String(apiUrl));
+    if (requireApiKey && !apiKey) {
+        throw new CliError('CONFIG_MISSING_API_KEY', 'missing api key; run `nmsocial login --api-key-stdin`');
+    }
+    return { apiUrl: String(apiUrl), apiKey };
+}
+export function validateApiUrl(apiUrl) {
+    try {
+        const url = new URL(apiUrl);
+        if (!['http:', 'https:'].includes(url.protocol))
+            throw new Error('invalid protocol');
+    }
+    catch {
+        throw new CliError('CONFIG_INVALID_API_URL', `invalid API URL: ${apiUrl}`);
+    }
+}
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}

package/dist/cli/help.js

@@ -0,0 +1,21 @@
+export const HELP = `Northmoon Social CLI
+
+Usage:
+  nmsocial login --api-key-stdin [--api-url URL]
+  nmsocial login --api-key YOUR_KEY
+  nmsocial status
+  nmsocial update check
+  nmsocial update [--manager npm|pnpm|bun]
+  nmsocial auth-url --platform tiktok
+  nmsocial accounts list [--platform tiktok] [--page 1] [--page-size 20]
+  nmsocial materials upload ./demo.mp4
+  nmsocial publish video --account OPEN_ID --content URL
+  nmsocial webhook set --url https://example.com/webhook
+  nmsocial stats overview [--platform tiktok]
+
+Global:
+  --json
+  --api-url URL
+  --timeout MS
+  --dry-run
+`;