beervid-app-cli 0.2.5 → 0.2.7

package/dist/index.d.ts

@@ -0,0 +1,255 @@
+interface OpenApiResponse<T> {
+    code: number;
+    message: string;
+    data: T;
+    error: boolean;
+    success: boolean;
+}
+/** API-level account type (uppercase) */
+type AccountType = 'TT' | 'TTS';
+/** CLI --type param for OAuth (lowercase) */
+type OAuthAccountType = 'tt' | 'tts';
+type PublishType = 'normal' | 'shoppable';
+type UploadType = 'normal' | 'tts';
+type ProductType = 'shop' | 'showcase' | 'all';
+type VideoStatus = 'PROCESSING_DOWNLOAD' | 'PUBLISH_COMPLETE' | 'FAILED' | string;
+type TtOAuthUrlData = string;
+interface TtsOAuthUrlData {
+    crossBorderUrl: string;
+}
+interface UploadTokenData {
+    uploadToken: string;
+    expiresIn: number;
+}
+interface NormalUploadResult {
+    fileUrl: string;
+    [key: string]: unknown;
+}
+interface TtsUploadResult {
+    videoFileId: string;
+    [key: string]: unknown;
+}
+interface NormalPublishResult {
+    shareId: string;
+    [key: string]: unknown;
+}
+interface NormalPublishOptions {
+    caption?: string;
+    isBrandOrganic?: boolean;
+    isBrandedContent?: boolean;
+    disableComment?: boolean;
+    disableDuet?: boolean;
+    disableStitch?: boolean;
+    thumbnailOffset?: number;
+}
+interface ShoppablePublishResult {
+    videoId: string;
+    [key: string]: unknown;
+}
+interface VideoStatusData {
+    status?: VideoStatus;
+    Status?: VideoStatus;
+    reason?: string;
+    post_ids?: string[];
+    [key: string]: unknown;
+}
+interface RawVideoItem {
+    itemId?: string;
+    item_id?: string;
+    videoViews?: number;
+    video_views?: number;
+    likes?: number;
+    comments?: number;
+    shares?: number;
+    thumbnailUrl?: string;
+    thumbnail_url?: string;
+    shareUrl?: string;
+    share_url?: string;
+    [key: string]: unknown;
+}
+interface NormalizedVideoItem {
+    itemId: string | undefined;
+    videoViews: number;
+    likes: number;
+    comments: number;
+    shares: number;
+    thumbnailUrl: string;
+    shareUrl: string;
+}
+interface QueryVideoData {
+    videoList?: RawVideoItem[];
+    videos?: RawVideoItem[];
+    [key: string]: unknown;
+}
+interface RawProductItem {
+    id: string;
+    title: string;
+    price?: unknown;
+    images?: string[];
+    salesCount?: number;
+    brandName?: string;
+    shopName?: string;
+    source?: string;
+    reviewStatus?: string;
+    inventoryStatus?: string;
+    [key: string]: unknown;
+}
+interface NormalizedProductItem {
+    id: string;
+    title: string;
+    price: unknown;
+    images: string[];
+    salesCount: number;
+    brandName: string;
+    shopName: string;
+    source: string;
+    reviewStatus: string | undefined;
+    inventoryStatus: string | undefined;
+}
+interface ProductPageData {
+    nextPageToken?: string | null;
+    products?: RawProductItem[];
+    [key: string]: unknown;
+}
+interface ProductCursor {
+    shopToken: string | null;
+    showcaseToken: string | null;
+}
+interface WorkflowWarning {
+    code: string;
+    message: string;
+}
+interface NormalizedVideoQueryResult {
+    videos: NormalizedVideoItem[];
+    raw: QueryVideoData;
+}
+interface TTFlowStatusResult {
+    pollCount: number;
+    finalStatus: string;
+    reason: string | null;
+    postIds: string[];
+    raw: VideoStatusData | null;
+}
+interface TTFlowQueryResult extends NormalizedVideoQueryResult {
+    attempts: number;
+}
+interface TTWorkflowResult {
+    flowType: 'tt';
+    upload: NormalUploadResult;
+    publish: NormalPublishResult;
+    status: TTFlowStatusResult;
+    videoId: string | null;
+    query: TTFlowQueryResult | null;
+    warnings: WorkflowWarning[];
+}
+interface ProductQuerySummary {
+    productType: ProductType;
+    pageSize: number;
+    pagesScanned: number;
+    productCount: number;
+    nextCursor: string | null;
+    reachedPageLimit: boolean;
+    failedSources: string[];
+}
+interface SelectedProductSummary {
+    selectionMode: 'manual' | 'interactive' | 'automatic';
+    id: string;
+    title: string;
+    salesCount: number;
+    source: string;
+    price: unknown;
+    brandName: string;
+    shopName: string;
+}
+interface TTSWorkflowResult {
+    flowType: 'tts';
+    productQuery: ProductQuerySummary;
+    selectedProduct: SelectedProductSummary;
+    upload: TtsUploadResult;
+    publish: ShoppablePublishResult;
+    warnings: WorkflowWarning[];
+}
+
+type CliCommandName = 'config' | 'get-oauth-url' | 'get-account-info' | 'upload' | 'publish' | 'poll-status' | 'query-video' | 'query-products' | 'publish-tt-flow' | 'publish-tts-flow';
+interface ConfigCommandOptions {
+    appKey?: string;
+    baseUrl?: string;
+    show?: boolean;
+}
+interface GetOAuthUrlCommandOptions {
+    type?: OAuthAccountType | string;
+}
+interface GetAccountInfoCommandOptions {
+    type?: AccountType | string;
+    accountId?: string;
+}
+interface UploadCommandOptions {
+    file?: string;
+    type?: UploadType | string;
+    creatorId?: string;
+    token?: string;
+}
+interface PublishCommandOptions {
+    type?: PublishType | string;
+    businessId?: string;
+    videoUrl?: string;
+    creatorId?: string;
+    fileId?: string;
+    productId?: string;
+    productTitle?: string;
+    caption?: string;
+    brandOrganic?: boolean;
+    brandedContent?: boolean;
+    disableComment?: boolean;
+    disableDuet?: boolean;
+    disableStitch?: boolean;
+    thumbnailOffset?: string;
+}
+interface PollStatusCommandOptions {
+    businessId?: string;
+    shareId?: string;
+    interval?: string;
+    maxPolls?: string;
+}
+interface QueryVideoCommandOptions {
+    businessId?: string;
+    itemIds?: string;
+    cursor?: string;
+    maxCount?: string;
+}
+interface QueryProductsCommandOptions {
+    creatorId?: string;
+    productType?: ProductType | string;
+    pageSize?: string;
+    cursor?: string;
+}
+interface PublishTTFlowCommandOptions {
+    businessId?: string;
+    file?: string;
+    caption?: string;
+    token?: string;
+    brandOrganic?: boolean;
+    brandedContent?: boolean;
+    disableComment?: boolean;
+    disableDuet?: boolean;
+    disableStitch?: boolean;
+    thumbnailOffset?: string;
+    interval?: string;
+    maxPolls?: string;
+    queryInterval?: string;
+    queryMaxAttempts?: string;
+}
+interface PublishTTSFlowCommandOptions {
+    creatorId?: string;
+    file?: string;
+    caption?: string;
+    token?: string;
+    productType?: ProductType | string;
+    pageSize?: string;
+    maxProductPages?: string;
+    productId?: string;
+    productTitle?: string;
+    interactive?: boolean;
+}
+
+export type { AccountType, CliCommandName, ConfigCommandOptions, GetAccountInfoCommandOptions, GetOAuthUrlCommandOptions, NormalPublishOptions, NormalPublishResult, NormalUploadResult, NormalizedProductItem, NormalizedVideoItem, NormalizedVideoQueryResult, OAuthAccountType, OpenApiResponse, PollStatusCommandOptions, ProductCursor, ProductPageData, ProductQuerySummary, ProductType, PublishCommandOptions, PublishTTFlowCommandOptions, PublishTTSFlowCommandOptions, PublishType, QueryProductsCommandOptions, QueryVideoCommandOptions, QueryVideoData, RawProductItem, RawVideoItem, SelectedProductSummary, ShoppablePublishResult, TTFlowQueryResult, TTFlowStatusResult, TTSWorkflowResult, TTWorkflowResult, TtOAuthUrlData, TtsOAuthUrlData, TtsUploadResult, UploadCommandOptions, UploadTokenData, UploadType, VideoStatus, VideoStatusData, WorkflowWarning };

package/dist/index.mjs

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

package/package.json

@@ -1,10 +1,21 @@
 {
   "name": "beervid-app-cli",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "BEERVID App CLI — TikTok video publish, account auth, and data query",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Lupeiwen0/beervid-app-cli"
+  },
   "type": "module",
+  "types": "dist/index.d.ts",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    }
   },
   "bin": {
     "beervid": "dist/cli.mjs"
@@ -19,6 +30,8 @@
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
+    "sync:skill-version": "node scripts/sync-skill-version.mjs",
+    "version": "npm run sync:skill-version",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {

package/skills/beervid-app-cli/FAQ.md

@@ -0,0 +1,214 @@
+# 常见问题（FAQ）
+
+本文档只保留 BEERVID Open API 接入中的高频误区和补充说明；首次接入请先看 [QUICKSTART.md](./QUICKSTART.md)。
+
+## 目录
+
+1. [基础概念](#基础概念)
+2. [账号授权](#账号授权)
+3. [视频上传](#视频上传)
+4. [视频发布](#视频发布)
+5. [数据查询](#数据查询)
+6. [CLI 使用](#cli-使用)
+
+---
+
+## 基础概念
+
+### Q: TT 和 TTS 有什么区别？
+
+**A:**
+- **TT**：普通 TikTok 账号，用于普通视频发布，也支持视频数据查询
+- **TTS**：TikTok Shop 跨境账号，用于挂车视频发布，不支持视频数据查询
+
+### Q: businessId 和 creatorUserOpenId 有什么区别？
+
+**A:**
+- `businessId`：TT 账号的业务 ID，来自 OAuth 回调里的 `ttAbId`
+- `creatorUserOpenId`：TTS 账号的 OpenId，来自 OAuth 回调里的 `ttsAbId`
+
+它们都是后续 API 的核心入参，但分别服务于不同账号体系。
+
+### Q: 同一个达人既要做 TTS 挂车发布，又要查视频数据，应该怎么授权？
+
+**A:**
+- 需要分别完成两次授权：一次 TTS，一次 TT
+- TTS 授权用于挂车发布、商品查询
+- TT 授权用于视频数据查询
+- 不能只授权 TTS 就去查视频数据
+
+### Q: TT 和 TTS 账号怎么建立关联？
+
+**A:**
+- 官方当前没有提供 `uno_id` 这类可直接关联 TT/TTS 的稳定字段
+- 当前推荐在授权完成后分别调用 `account/info`
+- 用两边返回的 `username` 作为你方系统内的关联键，建立 TT 和 TTS 的软关联
+- 真正调用 API 时仍然分别使用 `businessId` 和 `creatorUserOpenId`
+
+### Q: API 是否支持国内 TikTok（抖音）？
+
+**A:**
+当前这套 Open API 面向国际版 TikTok 和 TikTok Shop 跨境账号；如果是抖音场景，不要默认这套接口可直接复用。
+
+---
+
+## 账号授权
+
+### Q: 用户授权后，如何拿到 ttAbId 或 ttsAbId？
+
+**A:**
+从回调 URL 的 `state` 参数中解析 JSON：
+
+```javascript
+const urlParams = new URLSearchParams(window.location.search)
+const stateJson = decodeURIComponent(urlParams.get('state'))
+const state = JSON.parse(stateJson)
+
+const ttAbId = state.ttAbId
+const ttsAbId = state.ttsAbId
+```
+
+更完整的处理方式见 [oauth-callback.md](./docs/oauth-callback.md)。
+
+### Q: 一个用户可以绑定多个 TikTok 账号吗？
+
+**A:**
+可以。每次授权返回的 `ttAbId` / `ttsAbId` 都是独立账号标识，你可以在自己系统里做一对多关联。
+
+如果同一达人既授权了 TT 又授权了 TTS，也建议保存成两条独立记录，再通过 `username` 建立关联关系。
+
+### Q: 如何解绑账号？
+
+**A:**
+当前 API 不提供单独的解绑接口。通常做法是在你自己的系统中删除或停用对应账号记录。
+
+---
+
+## 视频上传
+
+### Q: `--file` 支持本地路径还是 URL？
+
+**A:**
+两者都支持：
+
+```bash
+beervid upload --file ./video.mp4
+beervid upload --file https://example.com/video.mp4
+```
+
+如果传 URL，当前 CLI 会先下载再上传。
+
+### Q: 上传凭证的有效期是多久？
+
+**A:**
+当前项目参考里使用的是 `expiresIn: 1800`，也就是 30 分钟。稳妥做法是每次上传前重新获取，不要长期缓存旧 token。
+
+### Q: 如何实现上传进度显示？
+
+**A:**
+如果你不是直接用 CLI，而是自己封装上传，当前更适合用 XHR 做进度监听，而不是裸 `fetch`。
+
+---
+
+## 视频发布
+
+### Q: 为什么 TT 发布需要轮询，TTS 通常不需要？
+
+**A:**
+- **TT**：发布接口先返回 `shareId`，后续还要轮询状态，直到 `PUBLISH_COMPLETE` 且 `post_ids` 非空
+- **TTS**：挂车发布接口通常直接返回 `videoId`
+
+### Q: TT 发布成功的判定条件是什么？
+
+**A:**
+不是只看 `status === PUBLISH_COMPLETE`，还要同时满足 `post_ids` 非空。只有这两个条件同时成立，才能把 `post_ids[0]` 当成真正的 `videoId` 使用。
+
+### Q: TTS 发布时 productTitle 为什么要截断？
+
+**A:**
+当前 OpenAPI 约束是 `productTitle` 最多 30 字符，超出要提前截断：
+
+```typescript
+const productTitle = originalTitle.length > 30
+  ? originalTitle.slice(0, 30)
+  : originalTitle
+```
+
+### Q: 发布失败后可以直接重试吗？
+
+**A:**
+读接口和写接口要分开看：
+- `query-products`、`query-video`、`poll-status` 这类读操作适合退避重试
+- `publish` 这类写操作先考虑幂等，再决定是否补偿重试
+
+详见 [retry-and-idempotency.md](./docs/retry-and-idempotency.md)。
+
+---
+
+## 数据查询
+
+### Q: TTS 账号可以查询视频数据吗？
+
+**A:**
+不可以。视频数据查询只适用于 TT 账号。
+
+如果你要查询某个 TTS 达人的视频数据，需要额外为同一达人完成 TT 授权，再使用 TT 的 `businessId` 调用 `query-video`。
+
+### Q: `query-video` 一定要传 itemIds 吗？
+
+**A:**
+不一定。当前 CLI 既支持指定 `itemIds`：
+
+```bash
+beervid query-video --business-id biz_123 --item-ids 7123,7124
+```
+
+也支持按分页方式查列表：
+
+```bash
+beervid query-video --business-id biz_123 --cursor 0 --max-count 20
+```
+
+### Q: 商品分页里的 cursor 是怎么来的？
+
+**A:**
+当前实现不是直接透传后端的单个 token，而是把：
+
+- `shopToken`
+- `showcaseToken`
+
+组成一个 JSON 对象，再做 base64 编码。这样可以同时追踪 `shop` 和 `showcase` 两个来源的分页进度。
+
+---
+
+## CLI 使用
+
+### Q: 配置保存在哪里？
+
+**A:**
+默认保存在 `~/.beervid/config.json`。
+
+### Q: 环境变量和配置文件哪个优先级高？
+
+**A:**
+优先级是：
+
+`环境变量 > 配置文件 > 默认值`
+
+### Q: CLI 命令执行失败时先看什么？
+
+**A:**
+优先看这三步：
+
+1. `beervid config --show`
+2. `beervid get-oauth-url --type tt`
+3. 查看 [troubleshooting.md](./docs/troubleshooting.md)
+
+---
+
+## 相关文档
+
+- [快速开始指南](./QUICKSTART.md)
+- [完整 API 参考](./references/api-reference.md)
+- [OAuth 回调](./docs/oauth-callback.md)
+- [故障排查指南](./docs/troubleshooting.md)

package/skills/beervid-app-cli/QUICKSTART.md

@@ -0,0 +1,206 @@
+# 快速开始指南
+
+5 分钟从零到发布第一个 TikTok 视频。
+
+## 前置准备
+
+1. **获取 API Key**
+   - 联系 BEERVID 平台获取 `BEERVID_APP_KEY`
+   - 确保你的应用已在 BEERVID 平台注册
+
+2. **安装 CLI**
+   ```bash
+   npm install -g beervid-app-cli
+   ```
+
+3. **配置 API Key**
+   ```bash
+   beervid config --app-key "your-api-key-here"
+   ```
+
+## 场景一：发布普通视频（TT 账号）
+
+### 步骤 1：获取授权链接
+
+```bash
+beervid get-oauth-url --type tt
+```
+
+输出示例：
+```json
+"https://www.tiktok.com/v2/auth/authorize?client_key=..."
+```
+
+### 步骤 2：用户授权
+
+1. 将上面的 URL 发送给用户
+2. 用户点击授权后，会跳转到你配置的回调地址
+3. 从回调 URL 的 `state` 参数中解析 JSON，获取 `ttAbId`
+
+回调示例：
+```
+https://your-domain.com/callback?state=%7B%22ttAbId%22%3A%227281234567890%22%7D
+```
+
+解析后得到：
+```json
+{
+  "ttAbId": "7281234567890"
+}
+```
+
+### 步骤 3：一键发布视频
+
+使用 `ttAbId` 作为 `businessId` 发布视频：
+
+```bash
+beervid publish-tt-flow \
+  --business-id "7281234567890" \
+  --file ./my-video.mp4 \
+  --caption "我的第一个视频"
+```
+
+这个命令会自动完成：
+- 获取上传凭证
+- 上传视频文件
+- 发布视频
+- 轮询发布状态
+- 查询视频数据
+
+输出示例：
+```json
+{
+  "upload": {
+    "fileUrl": "https://cdn.beervid.ai/uploads/xxx.mp4"
+  },
+  "publish": {
+    "shareId": "share_abc123"
+  },
+  "status": {
+    "status": "PUBLISH_COMPLETE",
+    "post_ids": ["7123456789012345678"]
+  },
+  "query": {
+    "videoList": [
+      {
+        "itemId": "7123456789012345678",
+        "shareUrl": "https://www.tiktok.com/@username/video/7123456789012345678"
+      }
+    ]
+  }
+}
+```
+
+完成！你的第一个视频已成功发布到 TikTok。
+
+## 场景二：发布挂车视频（TTS 账号）
+
+### 步骤 1：获取授权链接
+
+```bash
+beervid get-oauth-url --type tts
+```
+
+### 步骤 2：用户授权
+
+从回调 URL 的 `state` 参数中解析 `ttsAbId`：
+
+```json
+{
+  "ttsAbId": "open_user_abc123"
+}
+```
+
+### 步骤 3：一键发布挂车视频
+
+```bash
+beervid publish-tts-flow \
+  --creator-id "open_user_abc123" \
+  --file ./product-video.mp4
+```
+
+CLI 会自动：
+1. 查询可用商品列表
+2. 自动选择一个可发布商品；如果你想手动挑选，请加 `--interactive`
+3. 上传视频
+4. 发布挂车视频
+
+输出示例：
+```json
+{
+  "products": [
+    {
+      "products": [
+        {
+          "id": "prod_789",
+          "title": "Premium Widget"
+        }
+      ]
+    }
+  ],
+  "selectedProduct": {
+    "id": "prod_789",
+    "title": "Premium Widget"
+  },
+  "upload": {
+    "videoFileId": "vf_abc123def456"
+  },
+  "publish": {
+    "videoId": "7234567890123456789"
+  }
+}
+```
+
+## 场景三：同一达人既要挂车发布，又要查询视频数据
+
+如果这个达人是 TTS 账号，并且你还想查询该账号的视频播放、点赞、评论等数据，需要额外再完成一次 TT 授权。
+
+### 步骤 1：先授权 TTS，用于挂车发布
+
+拿到 `ttsAbId`，作为 `creatorUserOpenId` 使用：
+
+```json
+{
+  "ttsAbId": "open_user_abc123"
+}
+```
+
+### 步骤 2：再授权 TT，用于视频数据查询
+
+拿到 `ttAbId`，作为 `businessId` 使用：
+
+```json
+{
+  "ttAbId": "7281234567890"
+}
+```
+
+### 步骤 3：分别调用账号详情接口，建立本地关联
+
+官方当前没有提供 `uno_id` 这种可直接关联 TT/TTS 的字段，推荐调用 `account/info` 后，用 `username` 作为当前的关联键：
+
+```text
+TTS account/info -> username = creator_name
+TT  account/info -> username = creator_name
+
+=> 在你方系统里建立一条 TT <-> TTS 关联
+```
+
+### 步骤 4：按场景使用不同 ID
+
+- 挂车发布：使用 `creatorUserOpenId`
+- 商品查询：使用 `creatorUserOpenId`
+- 视频数据查询：使用 `businessId`
+
+## 下一步
+
+- 查看 [SKILL.md](./SKILL.md) 了解完整功能
+- 查看 [references/api-reference.md](./references/api-reference.md) 了解 API 详情
+- 查看 [docs/](./docs/) 了解生产环境部署建议
+- 查看 [example/](./example/) 了解代码集成示例
+
+## 需要帮助？
+
+- 查看 [FAQ.md](./FAQ.md) 常见问题
+- 查看 [TROUBLESHOOTING.md](./docs/troubleshooting.md) 故障排查
+- 提交 Issue: https://github.com/Lupeiwen0/beervid-app-cli/issues