beervid-app-cli 0.2.3 → 0.2.5

package/skills/beervid-app-cli/example/standard/api-client.ts

@@ -0,0 +1,181 @@
+/**
+ * BEERVID Open API 通用客户端封装
+ *
+ * 提供 openApiGet / openApiPost / openApiUpload 三个基础请求函数，
+ * 包含统一的认证、错误处理和可选的重试机制。
+ *
+ * 使用方式：
+ *   import { openApiGet, openApiPost, openApiUpload } from './api-client.js'
+ */
+
+// ─── 环境配置 ───────────────────────────────────────────────────────────────
+
+const API_KEY = process.env['BEERVID_APP_KEY'] ?? ''
+const BASE_URL = process.env['BEERVID_APP_BASE_URL'] ?? 'https://open.beervid.ai'
+
+if (!API_KEY) {
+  console.error('错误: 请设置环境变量 BEERVID_APP_KEY')
+  console.error('  export BEERVID_APP_KEY="your-api-key"')
+  process.exit(1)
+}
+
+// ─── 类型定义 ───────────────────────────────────────────────────────────────
+
+interface OpenApiResponse<T> {
+  code: number
+  message: string
+  data: T
+  error: boolean
+  success: boolean
+}
+
+// ─── 响应处理 ───────────────────────────────────────────────────────────────
+
+async function handleResponse<T>(res: Response, path: string): Promise<T> {
+  if (!res.ok && res.status >= 500) {
+    throw new Error(`HTTP ${res.status} — ${path}`)
+  }
+
+  const json = (await res.json()) as OpenApiResponse<T>
+
+  if (json.code !== 0 || !json.success) {
+    throw new Error(
+      `Open API 错误 [${path}]: ${json.message ?? '未知错误'} (code: ${json.code})`
+    )
+  }
+
+  return json.data
+}
+
+// ─── GET 请求 ───────────────────────────────────────────────────────────────
+
+export async function openApiGet<T>(
+  path: string,
+  params?: Record<string, string>
+): Promise<T> {
+  const url = new URL(path, BASE_URL)
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      url.searchParams.set(k, v)
+    }
+  }
+
+  const res = await fetch(url.toString(), {
+    method: 'GET',
+    headers: {
+      'X-API-KEY': API_KEY,
+      'Content-Type': 'application/json',
+    },
+  })
+
+  return handleResponse<T>(res, path)
+}
+
+// ─── POST 请求 ──────────────────────────────────────────────────────────────
+
+export async function openApiPost<T>(
+  path: string,
+  body?: Record<string, unknown>
+): Promise<T> {
+  const url = new URL(path, BASE_URL)
+
+  const res = await fetch(url.toString(), {
+    method: 'POST',
+    headers: {
+      'X-API-KEY': API_KEY,
+      'Content-Type': 'application/json',
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  })
+
+  return handleResponse<T>(res, path)
+}
+
+// ─── 文件上传 ───────────────────────────────────────────────────────────────
+
+export async function openApiUpload<T>(
+  path: string,
+  formData: FormData,
+  options?: {
+    params?: Record<string, string>
+    uploadToken?: string
+  }
+): Promise<T> {
+  const url = new URL(path, BASE_URL)
+  if (options?.params) {
+    for (const [k, v] of Object.entries(options.params)) {
+      url.searchParams.set(k, v)
+    }
+  }
+
+  // 上传使用 X-UPLOAD-TOKEN 认证（非 X-API-KEY）
+  const headerName = options?.uploadToken ? 'X-UPLOAD-TOKEN' : 'X-API-KEY'
+  const headerValue = options?.uploadToken ?? API_KEY
+
+  const res = await fetch(url.toString(), {
+    method: 'POST',
+    headers: { [headerName]: headerValue },
+    body: formData,
+  })
+
+  return handleResponse<T>(res, path)
+}
+
+// ─── 重试封装 ───────────────────────────────────────────────────────────────
+
+interface RetryOptions {
+  maxRetries: number
+  baseDelay: number
+  label?: string
+}
+
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = { maxRetries: 3, baseDelay: 1000 }
+): Promise<T> {
+  let lastError: Error | null = null
+
+  for (let attempt = 1; attempt <= options.maxRetries + 1; attempt++) {
+    try {
+      return await fn()
+    } catch (err) {
+      lastError = err as Error
+
+      if (attempt > options.maxRetries) break
+
+      // 只重试网络错误和 5xx
+      const msg = lastError.message
+      const isRetryable =
+        msg.includes('fetch failed') ||
+        msg.includes('ECONNRESET') ||
+        /HTTP 5\d\d/.test(msg)
+      if (!isRetryable) break
+
+      const delay = options.baseDelay * Math.pow(2, attempt - 1)
+      const label = options.label ?? 'API 调用'
+      console.warn(`${label} 第 ${attempt} 次失败，${(delay / 1000).toFixed(1)}s 后重试...`)
+      await new Promise((r) => setTimeout(r, delay))
+    }
+  }
+
+  throw lastError
+}
+
+// ─── 辅助函数 ───────────────────────────────────────────────────────────────
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * 轮询间隔策略（阶梯递增）
+ *
+ * 前 6 次（0-30s）：每 5 秒   → 覆盖大部分快速完成的场景
+ * 第 7-12 次（30s-90s）：每 10 秒  → 中等耗时视频
+ * 第 13 次起（90s+）：每 15 秒     → 长耗时视频，降低 API 压力
+ */
+export function getPollingInterval(pollCount: number): number {
+  if (pollCount <= 6) return 5_000
+  if (pollCount <= 12) return 10_000
+  return 15_000
+}

package/skills/beervid-app-cli/example/standard/get-oauth-url.ts

@@ -0,0 +1,44 @@
+/**
+ * 获取 OAuth 授权 URL 示例
+ *
+ * 用法：
+ *   npx tsx get-oauth-url.ts --type tt
+ *   npx tsx get-oauth-url.ts --type tts
+ *
+ * 生产环境：如果要往授权链接里追加你方自定义安全字段，
+ * 先判断现有 state 是否为 JSON 对象；若是，再在该 JSON 中追加字段。
+ * 详见 docs/oauth-callback.md
+ */
+
+import { parseArgs } from 'node:util'
+import { openApiGet } from './api-client.js'
+
+const { values } = parseArgs({
+  options: {
+    type: { type: 'string', default: 'tt' },
+  },
+  strict: false,
+})
+
+const accountType = (values['type'] ?? 'tt').toLowerCase()
+
+if (accountType !== 'tt' && accountType !== 'tts') {
+  console.error('错误: --type 必须为 tt 或 tts')
+  process.exit(1)
+}
+
+console.log(`获取 ${accountType.toUpperCase()} OAuth 授权 URL...\n`)
+
+if (accountType === 'tt') {
+  // TT 账号：返回值即 URL 字符串
+  const url = await openApiGet<string>('/api/v1/open/thirdparty-auth/tt-url')
+  console.log('TT OAuth URL:')
+  console.log(url)
+} else {
+  // TTS 账号：返回值是包含 crossBorderUrl 的对象
+  const data = await openApiGet<{ crossBorderUrl: string }>('/api/v1/open/thirdparty-auth/tts-url')
+  console.log('TTS OAuth URL (跨境):')
+  console.log(data.crossBorderUrl)
+}
+
+console.log('\n请将 URL 提供给用户，用户在浏览器中完成授权后，你的回调 URL 将收到 accountId。')

package/skills/beervid-app-cli/example/standard/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "beervid-example-standard",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "oauth": "tsx get-oauth-url.ts",
+    "tt": "tsx tt-publish-flow.ts",
+    "tts": "tsx tts-publish-flow.ts",
+    "products": "tsx query-products.ts"
+  },
+  "devDependencies": {
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/skills/beervid-app-cli/example/standard/query-products.ts

@@ -0,0 +1,141 @@
+/**
+ * TTS 商品查询与分页示例
+ *
+ * 用法：
+ *   npx tsx query-products.ts --creator-id open_user_abc
+ *   npx tsx query-products.ts --creator-id open_user_abc --type shop --max-pages 3
+ */
+
+import { parseArgs } from 'node:util'
+import { openApiPost, withRetry } from './api-client.js'
+
+const { values } = parseArgs({
+  options: {
+    'creator-id': { type: 'string' },
+    type: { type: 'string', default: 'all' },
+    'page-size': { type: 'string', default: '20' },
+    'max-pages': { type: 'string', default: '5' },
+  },
+  strict: false,
+})
+
+const creatorId = values['creator-id']
+const productTypes = values['type'] === 'all' ? ['shop', 'showcase'] : [values['type'] ?? 'shop']
+const pageSize = parseInt(values['page-size'] ?? '20', 10)
+const maxPages = parseInt(values['max-pages'] ?? '5', 10)
+
+if (!creatorId) {
+  console.error('用法: npx tsx query-products.ts --creator-id <id>')
+  process.exit(1)
+}
+
+// ─── 类型定义 ───────────────────────────────────────────────────────────────
+
+interface Product {
+  id: string
+  title: string
+  price?: unknown
+  images?: string[]
+  salesCount?: number
+  source?: string
+  reviewStatus?: string
+  inventoryStatus?: string
+}
+
+interface ProductPage {
+  products?: Product[]
+  nextPageToken?: string | null
+}
+
+// ─── 查询商品 ───────────────────────────────────────────────────────────────
+
+console.log(`查询商品（创作者: ${creatorId}）\n`)
+
+const allProducts = new Map<string, Product>()
+
+for (const productType of productTypes) {
+  console.log(`--- ${productType} ---`)
+  let pageToken = ''
+  let page = 0
+
+  while (page < maxPages) {
+    page++
+    console.log(`  第 ${page} 页...`)
+
+    const data = await withRetry(
+      () => openApiPost<ProductPage | ProductPage[]>(
+        '/api/v1/open/tts/products/query',
+        {
+          creatorUserOpenId: creatorId,
+          productType,
+          pageSize,
+          pageToken,
+        }
+      ),
+      { maxRetries: 2, baseDelay: 2000 }
+    )
+
+    const groups = Array.isArray(data) ? data : [data]
+    let pageProductCount = 0
+
+    for (const group of groups) {
+      for (const product of group.products ?? []) {
+        pageProductCount++
+        if (!allProducts.has(product.id)) {
+          // 解析图片 URL
+          const images = (product.images ?? []).map((img) => {
+            const match = img.match(/url=([^,}]+)/)
+            return match?.[1]?.trim() ?? ''
+          }).filter(Boolean)
+
+          allProducts.set(product.id, {
+            ...product,
+            images,
+            source: product.source ?? productType,
+          })
+        }
+      }
+
+      if (group.nextPageToken === null || group.nextPageToken === undefined) {
+        pageToken = ''
+        break
+      }
+      pageToken = group.nextPageToken
+    }
+
+    console.log(`    获得 ${pageProductCount} 个商品`)
+
+    if (!pageToken) {
+      console.log(`  已到最后一页`)
+      break
+    }
+  }
+
+  if (pageToken) {
+    console.log(`  ⚠ 已达到最大页数限制 (${maxPages})，仍有未拉取的分页`)
+  }
+}
+
+// ─── 结果汇总 ───────────────────────────────────────────────────────────────
+
+const products = Array.from(allProducts.values())
+const publishable = products.filter((p) => {
+  if (p.reviewStatus && p.reviewStatus.toUpperCase() !== 'APPROVED') return false
+  if (p.inventoryStatus && p.inventoryStatus.toUpperCase() !== 'IN_STOCK') return false
+  return true
+})
+
+console.log(`\n汇总：`)
+console.log(`  总商品数: ${products.length}`)
+console.log(`  可发布商品: ${publishable.length}`)
+
+if (publishable.length > 0) {
+  const sorted = publishable.sort((a, b) => (b.salesCount ?? 0) - (a.salesCount ?? 0))
+  console.log('\n可发布商品（按销量降序）:')
+  for (const [i, p] of sorted.slice(0, 10).entries()) {
+    console.log(`  ${i + 1}. [${p.source}] ${p.title} | ID: ${p.id} | 销量: ${p.salesCount ?? 0}`)
+  }
+  if (sorted.length > 10) {
+    console.log(`  ... 共 ${sorted.length} 个`)
+  }
+}

package/skills/beervid-app-cli/example/standard/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist"
+  },
+  "include": ["*.ts"]
+}

package/skills/beervid-app-cli/example/standard/tt-publish-flow.ts

@@ -0,0 +1,194 @@
+/**
+ * TT 完整发布流程 — 最佳实践示例
+ *
+ * 流程：上传视频 → 发布 → 轮询状态（阶梯递增间隔） → 查询视频数据
+ *
+ * 用法：
+ *   npx tsx tt-publish-flow.ts --file ./video.mp4 --business-id biz_123 [--caption "My video"]
+ */
+
+import { readFileSync } from 'node:fs'
+import { resolve, basename } from 'node:path'
+import { parseArgs } from 'node:util'
+import {
+  openApiPost,
+  openApiUpload,
+  withRetry,
+  sleep,
+  getPollingInterval,
+} from './api-client.js'
+
+// ─── 参数解析 ───────────────────────────────────────────────────────────────
+
+const { values } = parseArgs({
+  options: {
+    file: { type: 'string' },
+    'business-id': { type: 'string' },
+    caption: { type: 'string', default: '' },
+    'max-polls': { type: 'string', default: '60' },
+  },
+  strict: false,
+})
+
+const filePath = values['file']
+const businessId = values['business-id']
+const caption = values['caption'] ?? ''
+const maxPolls = parseInt(values['max-polls'] ?? '60', 10)
+
+if (!filePath || !businessId) {
+  console.error('用法: npx tsx tt-publish-flow.ts --file <路径> --business-id <id> [--caption <text>]')
+  process.exit(1)
+}
+
+// ─── 步骤 1：获取上传凭证 ──────────────────────────────────────────────────
+
+console.log('━'.repeat(60))
+console.log('TT 完整发布流程')
+console.log('━'.repeat(60))
+
+console.log('\n[1/4] 获取上传凭证...')
+
+const tokenData = await withRetry(
+  () => openApiPost<{ uploadToken: string; expiresIn: number }>(
+    '/api/v1/open/upload-token/generate'
+  ),
+  { maxRetries: 3, baseDelay: 1000, label: '获取上传凭证' }
+)
+
+console.log(`  ✓ 获得上传凭证（有效期 ${tokenData.expiresIn} 秒）`)
+
+// ─── 步骤 2：上传视频 ──────────────────────────────────────────────────────
+
+console.log('\n[2/4] 上传视频...')
+
+const absPath = resolve(filePath)
+const buffer = readFileSync(absPath)
+const fileName = basename(absPath)
+const file = new File([buffer], fileName, { type: 'video/mp4' })
+
+console.log(`  文件: ${fileName} (${(buffer.byteLength / 1024 / 1024).toFixed(1)} MB)`)
+
+const formData = new FormData()
+formData.append('file', file)
+
+const uploadResult = await withRetry(
+  () => openApiUpload<{ fileUrl: string }>(
+    '/api/v1/open/file-upload',
+    formData,
+    { uploadToken: tokenData.uploadToken }
+  ),
+  { maxRetries: 2, baseDelay: 5000, label: '视频上传' }
+)
+
+console.log(`  ✓ 上传成功: ${uploadResult.fileUrl}`)
+
+// ─── 步骤 3：发布视频 ──────────────────────────────────────────────────────
+
+console.log('\n[3/4] 发布视频...')
+
+// ⚠️ 发布操作不重试！重复调用会产生多条视频
+const publishResult = await openApiPost<{ shareId: string }>(
+  '/api/v1/open/tiktok/video/publish',
+  {
+    businessId,
+    videoUrl: uploadResult.fileUrl,
+    caption,
+  }
+)
+
+console.log(`  ✓ 已提交发布，shareId: ${publishResult.shareId}`)
+
+// ─── 步骤 4：轮询发布状态（阶梯递增间隔） ──────────────────────────────────
+
+console.log('\n[4/4] 轮询发布状态...')
+console.log('  轮询策略：前 6 次每 5s → 7-12 次每 10s → 之后每 15s')
+
+let videoId: string | null = null
+
+for (let i = 1; i <= maxPolls; i++) {
+  const interval = getPollingInterval(i)
+
+  const statusData = await withRetry(
+    () => openApiPost<{
+      status?: string
+      Status?: string
+      reason?: string
+      post_ids?: string[]
+    }>('/api/v1/open/tiktok/video/status', {
+      businessId,
+      shareId: publishResult.shareId,
+    }),
+    { maxRetries: 2, baseDelay: 1000, label: '轮询状态' }
+  )
+
+  const status = statusData.status ?? statusData.Status ?? 'UNKNOWN'
+  const postIds = statusData.post_ids ?? []
+
+  // 状态判定
+  if (status === 'FAILED') {
+    console.error(`  ✗ 发布失败: ${statusData.reason ?? '未知原因'}`)
+    process.exit(1)
+  }
+
+  if (status === 'PUBLISH_COMPLETE' && postIds.length > 0) {
+    videoId = postIds[0]!
+    console.log(`  ✓ 发布完成！视频 ID: ${videoId}（第 ${i} 次查询）`)
+    break
+  }
+
+  // 注意：PUBLISH_COMPLETE 但 post_ids 为空 → 继续轮询
+  const statusLabel = status === 'PUBLISH_COMPLETE' ? 'COMPLETE(等待 post_ids)' : status
+  console.log(`  [${i}/${maxPolls}] 状态: ${statusLabel}，${interval / 1000}s 后重试...`)
+
+  if (i < maxPolls) {
+    await sleep(interval)
+  }
+}
+
+if (!videoId) {
+  console.error(`  ✗ 超时：${maxPolls} 次轮询后仍未获得视频 ID`)
+  process.exit(2)
+}
+
+// ─── 查询视频数据 ──────────────────────────────────────────────────────────
+
+console.log('\n[可选] 查询视频数据...')
+
+// 视频刚发布后数据可能尚未同步，等待几秒后查询
+await sleep(5000)
+
+const queryData = await withRetry(
+  () => openApiPost<{
+    videoList?: Array<Record<string, unknown>>
+    videos?: Array<Record<string, unknown>>
+  }>('/api/v1/open/tiktok/video/query', {
+    businessId,
+    itemIds: [videoId],
+  }),
+  { maxRetries: 3, baseDelay: 5000, label: '查询视频数据' }
+)
+
+// 兼容新旧字段格式
+const videoList = queryData.videoList ?? queryData.videos ?? []
+if (videoList.length > 0) {
+  const video = videoList[0]!
+  console.log('  ✓ 视频数据:')
+  console.log(`    播放量: ${video['videoViews'] ?? video['video_views'] ?? 0}`)
+  console.log(`    点赞:   ${video['likes'] ?? 0}`)
+  console.log(`    评论:   ${video['comments'] ?? 0}`)
+  console.log(`    分享:   ${video['shares'] ?? 0}`)
+  console.log(`    链接:   ${video['shareUrl'] ?? video['share_url'] ?? '-'}`)
+} else {
+  console.log('  ⚠ 视频数据暂未同步，稍后可手动查询')
+}
+
+// ─── 结果汇总 ──────────────────────────────────────────────────────────────
+
+console.log('\n' + '━'.repeat(60))
+console.log('流程完成！')
+console.log(JSON.stringify({
+  businessId,
+  fileUrl: uploadResult.fileUrl,
+  shareId: publishResult.shareId,
+  videoId,
+}, null, 2))