beervid-app-cli 0.2.3 → 0.2.5

package/skills/beervid-app-cli/example/nextjs/app/api/publish/tt/route.ts

@@ -0,0 +1,116 @@
+/**
+ * POST /api/publish/tt
+ *
+ * TT 完整发布流程：发布 → 轮询状态（阶梯递增间隔）→ 查询视频数据
+ *
+ * Body: { businessId, videoUrl, caption? }
+ *
+ * 注意：此示例使用同步轮询（请求等待直到完成）。
+ * 生产环境建议改为异步模式：发布后立即返回 shareId，后台任务轮询，客户端通过 /api/status/:shareId 查询进度。
+ */
+import { NextRequest, NextResponse } from 'next/server'
+import { openApiPost, getPollingInterval, sleep } from '@/lib/beervid-client'
+
+const MAX_POLLS = 60
+
+export async function POST(request: NextRequest) {
+  const body = await request.json()
+  const { businessId, videoUrl, caption } = body as {
+    businessId?: string
+    videoUrl?: string
+    caption?: string
+  }
+
+  if (!businessId || !videoUrl) {
+    return NextResponse.json(
+      { error: '缺少 businessId 或 videoUrl' },
+      { status: 400 }
+    )
+  }
+
+  try {
+    // ① 发布视频（⚠️ 不重试 —— 发布操作非幂等）
+    const publishResult = await openApiPost<{ shareId: string }>(
+      '/api/v1/open/tiktok/video/publish',
+      { businessId, videoUrl, caption: caption ?? '' }
+    )
+
+    // ② 轮询状态 —— 阶梯递增间隔策略
+    // 前 6 次(0-30s): 每 5s → 7-12 次(30s-90s): 每 10s → 之后: 每 15s
+    let videoId: string | null = null
+    let finalStatus = 'TIMEOUT'
+    let failReason: string | null = null
+    let pollCount = 0
+
+    for (let i = 1; i <= MAX_POLLS; i++) {
+      const interval = getPollingInterval(i)
+      await sleep(interval)
+
+      const data = await openApiPost<{
+        status?: string
+        Status?: string
+        reason?: string
+        post_ids?: string[]
+      }>('/api/v1/open/tiktok/video/status', {
+        businessId,
+        shareId: publishResult.shareId,
+      })
+
+      const status = data.status ?? data.Status ?? 'UNKNOWN'
+      const postIds = data.post_ids ?? []
+      pollCount = i
+
+      if (status === 'FAILED') {
+        finalStatus = 'FAILED'
+        failReason = data.reason ?? '未知原因'
+        break
+      }
+
+      if (status === 'PUBLISH_COMPLETE' && postIds.length > 0) {
+        finalStatus = 'PUBLISH_COMPLETE'
+        videoId = postIds[0]!
+        break
+      }
+    }
+
+    // ③ 查询视频数据（如果发布成功）
+    let videoData = null
+    if (videoId) {
+      await sleep(3000) // 等待数据同步
+      try {
+        const queryResult = await openApiPost<{
+          videoList?: Array<Record<string, unknown>>
+          videos?: Array<Record<string, unknown>>
+        }>('/api/v1/open/tiktok/video/query', {
+          businessId,
+          itemIds: [videoId],
+        })
+        const list = queryResult.videoList ?? queryResult.videos ?? []
+        if (list.length > 0) {
+          const v = list[0]!
+          videoData = {
+            videoViews: v['videoViews'] ?? v['video_views'] ?? 0,
+            likes: v['likes'] ?? 0,
+            comments: v['comments'] ?? 0,
+            shares: v['shares'] ?? 0,
+            shareUrl: v['shareUrl'] ?? v['share_url'] ?? '',
+          }
+        }
+      } catch {
+        // 视频数据查询失败不影响整体结果
+      }
+    }
+
+    return NextResponse.json({
+      success: finalStatus === 'PUBLISH_COMPLETE',
+      shareId: publishResult.shareId,
+      videoId,
+      publishStatus: finalStatus,
+      failReason,
+      pollCount,
+      videoData,
+    })
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 })
+  }
+}

package/skills/beervid-app-cli/example/nextjs/app/api/publish/tts/route.ts

@@ -0,0 +1,58 @@
+/**
+ * POST /api/publish/tts
+ *
+ * TTS 完整发布流程：发布挂车视频（立即完成，无需轮询）
+ *
+ * Body: { creatorId, videoFileId, productId, productTitle, caption? }
+ */
+import { NextRequest, NextResponse } from 'next/server'
+import { openApiPost } from '@/lib/beervid-client'
+
+const MAX_PRODUCT_TITLE_LENGTH = 29
+
+export async function POST(request: NextRequest) {
+  const body = await request.json()
+  const { creatorId, videoFileId, productId, productTitle, caption } = body as {
+    creatorId?: string
+    videoFileId?: string
+    productId?: string
+    productTitle?: string
+    caption?: string
+  }
+
+  if (!creatorId || !videoFileId || !productId || !productTitle) {
+    return NextResponse.json({
+      error: '缺少必填参数',
+      required: ['creatorId', 'videoFileId', 'productId', 'productTitle'],
+    }, { status: 400 })
+  }
+
+  try {
+    // 商品标题最多 29 字符，超出自动截断
+    const normalizedTitle = productTitle.slice(0, MAX_PRODUCT_TITLE_LENGTH)
+    const wasTruncated = normalizedTitle !== productTitle
+
+    // 挂车发布（⚠️ 不重试 —— 发布操作非幂等）
+    const result = await openApiPost<{ videoId: string }>(
+      '/api/v1/open/tts/shoppable-video/publish',
+      {
+        creatorUserOpenId: creatorId,
+        fileId: videoFileId,
+        title: caption ?? '',
+        productId,
+        productTitle: normalizedTitle,
+      }
+    )
+
+    // 挂车视频发布后立即完成，无需轮询
+    return NextResponse.json({
+      success: true,
+      videoId: result.videoId,
+      productId,
+      productTitle: normalizedTitle,
+      titleTruncated: wasTruncated,
+    })
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 })
+  }
+}

package/skills/beervid-app-cli/example/nextjs/app/api/status/[shareId]/route.ts

@@ -0,0 +1,41 @@
+/**
+ * GET /api/status/[shareId]?businessId=xxx
+ * 查询 TT 普通视频的发布状态
+ */
+import { NextRequest, NextResponse } from 'next/server'
+import { openApiPost } from '@/lib/beervid-client'
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ shareId: string }> }
+) {
+  const { shareId } = await params
+  const businessId = request.nextUrl.searchParams.get('businessId')
+
+  if (!businessId) {
+    return NextResponse.json({ error: '缺少 businessId 参数' }, { status: 400 })
+  }
+
+  try {
+    const data = await openApiPost<{
+      status?: string
+      Status?: string
+      reason?: string
+      post_ids?: string[]
+    }>('/api/v1/open/tiktok/video/status', { businessId, shareId })
+
+    const status = data.status ?? data.Status ?? 'UNKNOWN'
+    const postIds = data.post_ids ?? []
+
+    return NextResponse.json({
+      shareId,
+      publishStatus: status,
+      videoId: postIds[0] ?? null,
+      isComplete: status === 'PUBLISH_COMPLETE' && postIds.length > 0,
+      isFailed: status === 'FAILED',
+      reason: data.reason ?? null,
+    })
+  } catch (err) {
+    return NextResponse.json({ error: (err as Error).message }, { status: 500 })
+  }
+}

package/skills/beervid-app-cli/example/nextjs/app/layout.tsx

@@ -0,0 +1,9 @@
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="zh-CN">
+      <body style={{ fontFamily: 'system-ui, sans-serif', maxWidth: 800, margin: '0 auto', padding: 20 }}>
+        {children}
+      </body>
+    </html>
+  )
+}

package/skills/beervid-app-cli/example/nextjs/app/page.tsx

@@ -0,0 +1,80 @@
+export default function Home() {
+  return (
+    <main>
+      <h1>BEERVID Next.js API Route 集成示例</h1>
+      <p>本示例使用 Next.js App Router + API Route 模式集成 BEERVID Open API。</p>
+
+      <h2>API Routes</h2>
+      <table style={{ borderCollapse: 'collapse', width: '100%' }}>
+        <thead>
+          <tr>
+            <th style={th}>方法</th>
+            <th style={th}>路径</th>
+            <th style={th}>说明</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td style={td}>GET</td>
+            <td style={td}><code>/api/oauth/url?type=tt</code></td>
+            <td style={td}>获取 OAuth URL</td>
+          </tr>
+          <tr>
+            <td style={td}>GET</td>
+            <td style={td}><code>/api/oauth/callback</code></td>
+            <td style={td}>OAuth 回调处理</td>
+          </tr>
+          <tr>
+            <td style={td}>POST</td>
+            <td style={td}><code>/api/publish/tt</code></td>
+            <td style={td}>TT 完整发布流程</td>
+          </tr>
+          <tr>
+            <td style={td}>POST</td>
+            <td style={td}><code>/api/publish/tts</code></td>
+            <td style={td}>TTS 完整发布流程</td>
+          </tr>
+          <tr>
+            <td style={td}>GET</td>
+            <td style={td}><code>/api/status/[shareId]</code></td>
+            <td style={td}>发布状态查询</td>
+          </tr>
+          <tr>
+            <td style={td}>GET</td>
+            <td style={td}><code>/api/products?creatorId=xxx</code></td>
+            <td style={td}>商品查询</td>
+          </tr>
+        </tbody>
+      </table>
+
+      <h2>请求示例</h2>
+      <pre style={{ background: '#f5f5f5', padding: 16, borderRadius: 8, overflow: 'auto' }}>
+{`# 获取 OAuth URL
+curl http://localhost:3000/api/oauth/url?type=tt
+
+# TT 完整发布
+curl -X POST http://localhost:3000/api/publish/tt \\
+  -H "Content-Type: application/json" \\
+  -d '{"businessId":"biz_123","videoUrl":"https://cdn.beervid.ai/xxx.mp4"}'
+
+# TTS 完整发布
+curl -X POST http://localhost:3000/api/publish/tts \\
+  -H "Content-Type: application/json" \\
+  -d '{"creatorId":"open_user_abc","videoFileId":"vf_123","productId":"prod_1","productTitle":"Widget"}'
+
+# 查询状态
+curl http://localhost:3000/api/status/share_abc?businessId=biz_123
+
+# 查询商品
+curl http://localhost:3000/api/products?creatorId=open_user_abc`}
+      </pre>
+    </main>
+  )
+}
+
+const th: React.CSSProperties = {
+  border: '1px solid #ddd', padding: '8px 12px', textAlign: 'left', background: '#f9f9f9',
+}
+const td: React.CSSProperties = {
+  border: '1px solid #ddd', padding: '8px 12px',
+}

package/skills/beervid-app-cli/example/nextjs/lib/beervid-client.ts

@@ -0,0 +1,107 @@
+/**
+ * BEERVID Open API — 服务端客户端封装
+ *
+ * 仅在服务端使用（API Route / Server Component），
+ * 通过环境变量读取配置，不暴露给客户端。
+ */
+
+// ─── 配置 ───────────────────────────────────────────────────────────────────
+
+function getApiKey(): string {
+  const key = process.env['BEERVID_APP_KEY']
+  if (!key) throw new Error('缺少环境变量 BEERVID_APP_KEY')
+  return key
+}
+
+function getBaseUrl(): string {
+  return process.env['BEERVID_APP_BASE_URL'] ?? 'https://open.beervid.ai'
+}
+
+// ─── 类型 ───────────────────────────────────────────────────────────────────
+
+interface OpenApiResponse<T> {
+  code: number
+  message: string
+  data: T
+  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
+}
+
+// ─── 请求函数 ───────────────────────────────────────────────────────────────
+
+export async function openApiGet<T>(
+  path: string,
+  params?: Record<string, string>
+): Promise<T> {
+  const url = new URL(path, getBaseUrl())
+  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': getApiKey(), 'Content-Type': 'application/json' },
+    cache: 'no-store',
+  })
+  return handleResponse<T>(res, path)
+}
+
+export async function openApiPost<T>(
+  path: string,
+  body?: Record<string, unknown>
+): Promise<T> {
+  const url = new URL(path, getBaseUrl())
+  const res = await fetch(url.toString(), {
+    method: 'POST',
+    headers: { 'X-API-KEY': getApiKey(), 'Content-Type': 'application/json' },
+    body: body ? JSON.stringify(body) : undefined,
+    cache: 'no-store',
+  })
+  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, getBaseUrl())
+  if (options?.params) {
+    for (const [k, v] of Object.entries(options.params)) url.searchParams.set(k, v)
+  }
+  const headerName = options?.uploadToken ? 'X-UPLOAD-TOKEN' : 'X-API-KEY'
+  const headerValue = options?.uploadToken ?? getApiKey()
+  const res = await fetch(url.toString(), {
+    method: 'POST',
+    headers: { [headerName]: headerValue },
+    body: formData,
+  })
+  return handleResponse<T>(res, path)
+}
+
+// ─── 轮询策略 ───────────────────────────────────────────────────────────────
+
+/**
+ * 阶梯递增轮询间隔（毫秒）
+ * 前 6 次：5s → 7-12 次：10s → 之后：15s
+ */
+export function getPollingInterval(pollCount: number): number {
+  if (pollCount <= 6) return 5_000
+  if (pollCount <= 12) return 10_000
+  return 15_000
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms))
+}

package/skills/beervid-app-cli/example/nextjs/next.config.ts

@@ -0,0 +1,4 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {}
+
+export default nextConfig

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

@@ -0,0 +1,19 @@
+{
+  "name": "beervid-example-nextjs",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "next": "^15.3.2",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "@types/react": "^19.1.0",
+    "typescript": "^5.9.3"
+  }
+}

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

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules"]
+}

package/skills/beervid-app-cli/example/standard/README.md

@@ -0,0 +1,51 @@
+# Standard 标准请求示例
+
+使用纯 Node.js + TypeScript + 原生 `fetch` 直接调用 BEERVID Open API 的独立脚本集合。
+
+## 前置条件
+
+- Node.js ≥ 20
+- BEERVID APP_KEY
+
+## 安装
+
+```bash
+cd example/standard
+npm install
+```
+
+## 配置
+
+```bash
+export BEERVID_APP_KEY="your-api-key"
+# 可选：自定义 API 地址
+export BEERVID_APP_BASE_URL="https://open.beervid.ai"
+```
+
+## 运行
+
+每个脚本独立可运行：
+
+```bash
+# 获取 OAuth 授权 URL
+npx tsx get-oauth-url.ts
+
+# TT 完整发布流程（最佳实践）
+npx tsx tt-publish-flow.ts --file ./video.mp4 --business-id biz_123
+
+# TTS 完整发布流程（最佳实践）
+npx tsx tts-publish-flow.ts --file ./video.mp4 --creator-id open_user_abc
+
+# 商品查询与分页
+npx tsx query-products.ts --creator-id open_user_abc
+```
+
+## 文件说明
+
+| 文件 | 说明 |
+|------|------|
+| `api-client.ts` | 通用 API 客户端封装（openApiGet/Post/Upload + 重试 + 错误处理） |
+| `tt-publish-flow.ts` | ⭐ TT 完整发布流程最佳实践（含阶梯递增轮询间隔） |
+| `tts-publish-flow.ts` | ⭐ TTS 完整发布流程最佳实践（含商品筛选策略） |
+| `get-oauth-url.ts` | 获取 TT/TTS OAuth 授权 URL |
+| `query-products.ts` | TTS 商品查询与分页遍历 |