feat(douyin): add Douyin creator center adapter (14 commands, 8-phase publish pipeline) (#416)

* feat(douyin): add Douyin creator center adapter (14 commands, 8-phase publish pipeline)

- publish: 8-phase pipeline (STS2 → TOS multipart upload w/ resume → ImageX cover → transcode poll → safety check → create_v2)
- draft: save as draft (phases 1-6 + is_draft:1, no timing)
- videos/drafts/delete/profile/update: content management
- hashtag (search/suggest/hot) / location / activities / collections / stats: discovery & analytics
- _shared: tos-upload (AWS Sig V4, multipart, resume), imagex-upload, transcode poller (encode=2), browser-fetch, sts2, creation-id, timing, text-extra
- 124 tests, tsc clean

* fix(douyin): accept unix timestamp strings

* docs(douyin): add browser adapter guide

---------

Co-authored-by: jackwener <jakevingoo@gmail.com>

Author: nianyi778

docs/adapters/browser/douyin.md

@@ -0,0 +1,75 @@
+# Douyin (抖音创作者中心)
+
+**Mode**: 🔐 Browser · **Domain**: `creator.douyin.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli douyin profile` | 获取账号信息 |
+| `opencli douyin videos` | 获取作品列表 |
+| `opencli douyin drafts` | 获取草稿列表 |
+| `opencli douyin draft` | 上传视频并保存为草稿 |
+| `opencli douyin publish` | 定时发布视频到抖音 |
+| `opencli douyin update` | 更新视频信息 |
+| `opencli douyin delete` | 删除作品 |
+| `opencli douyin stats` | 查询作品数据分析 |
+| `opencli douyin collections` | 获取合集列表 |
+| `opencli douyin activities` | 获取官方活动列表 |
+| `opencli douyin location` | 搜索发布可用的地理位置 |
+| `opencli douyin hashtag search` | 按关键词搜索话题 |
+| `opencli douyin hashtag suggest` | 基于封面 URI 推荐话题 |
+| `opencli douyin hashtag hot` | 获取热点词 |
+
+## Usage Examples
+
+```bash
+# 账号与作品
+opencli douyin profile
+opencli douyin videos --limit 10
+opencli douyin videos --status scheduled
+opencli douyin drafts
+
+# 发布前辅助信息
+opencli douyin collections
+opencli douyin activities
+opencli douyin location "东京塔"
+opencli douyin hashtag search "春游"
+opencli douyin hashtag hot --limit 10
+
+# 保存草稿
+opencli douyin draft ./video.mp4 \
+  --title "春游 vlog" \
+  --caption "#春游 先存草稿"
+
+# 定时发布
+opencli douyin publish ./video.mp4 \
+  --title "春游 vlog" \
+  --caption "#春游 今天去看樱花" \
+  --schedule "2026-04-08T12:00:00+09:00"
+
+# 也支持 Unix 秒字符串
+opencli douyin publish ./video.mp4 \
+  --title "春游 vlog" \
+  --schedule 1775617200
+
+# 更新与删除
+opencli douyin update 1234567890 --caption "更新后的文案"
+opencli douyin update 1234567890 --reschedule "2026-04-09T20:00:00+09:00"
+opencli douyin delete 1234567890
+
+# JSON 输出
+opencli douyin profile -f json
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** `creator.douyin.com`
+- The logged-in account must have access to Douyin Creator Center publishing features
+- [Browser Bridge extension](/guide/browser-bridge) installed
+
+## Notes
+
+- `publish` requires `--schedule` to be at least 2 hours later and no more than 14 days later
+- `draft` and `publish` upload the video through Douyin/ByteDance browser-authenticated APIs, so cookies in the active browser session must be valid
+- `hashtag suggest` expects a valid `cover`/`cover_uri` value produced during the publish pipeline; for normal manual use, `hashtag search` and `hashtag hot` are usually more convenient

src/clis/douyin/_shared/browser-fetch.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { IPage } from '../../../types.js';
+import { browserFetch } from './browser-fetch.js';
+
+function makePage(result: unknown): IPage {
+  return {
+    goto: vi.fn(), evaluate: vi.fn().mockResolvedValue(result),
+    getCookies: vi.fn(), snapshot: vi.fn(), click: vi.fn(),
+    typeText: vi.fn(), pressKey: vi.fn(), scrollTo: vi.fn(),
+    getFormState: vi.fn(), wait: vi.fn(), tabs: vi.fn(),
+    closeTab: vi.fn(), newTab: vi.fn(), selectTab: vi.fn(),
+    networkRequests: vi.fn(), consoleMessages: vi.fn(),
+    scroll: vi.fn(), autoScroll: vi.fn(),
+    installInterceptor: vi.fn(), getInterceptedRequests: vi.fn(),
+    screenshot: vi.fn(),
+  } as unknown as IPage;
+}
+
+describe('browserFetch', () => {
+  it('returns parsed JSON on success', async () => {
+    const page = makePage({ status_code: 0, data: { ak: 'KEY' } });
+    const result = await browserFetch(page, 'GET', 'https://creator.douyin.com/api/test');
+    expect(result).toEqual({ status_code: 0, data: { ak: 'KEY' } });
+  });
+
+  it('throws when status_code is non-zero', async () => {
+    const page = makePage({ status_code: 8, message: 'fail' });
+    await expect(
+      browserFetch(page, 'GET', 'https://creator.douyin.com/api/test')
+    ).rejects.toThrow('Douyin API error 8');
+  });
+
+  it('returns result even when no status_code field', async () => {
+    const page = makePage({ some_field: 'value' });
+    const result = await browserFetch(page, 'GET', 'https://creator.douyin.com/api/test');
+    expect(result).toEqual({ some_field: 'value' });
+  });
+});

src/clis/douyin/_shared/browser-fetch.ts

@@ -0,0 +1,45 @@
+import type { IPage } from '../../../types.js';
+import { CommandExecutionError } from '../../../errors.js';
+
+export interface FetchOptions {
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Execute a fetch() call inside the Chrome browser context via page.evaluate.
+ * This ensures a_bogus signing and cookies are handled automatically by the browser.
+ */
+export async function browserFetch(
+  page: IPage,
+  method: 'GET' | 'POST',
+  url: string,
+  options: FetchOptions = {}
+): Promise<unknown> {
+  const js = `
+    (async () => {
+      const res = await fetch(${JSON.stringify(url)}, {
+        method: ${JSON.stringify(method)},
+        credentials: 'include',
+        headers: {
+          'Content-Type': 'application/json',
+          ...${JSON.stringify(options.headers ?? {})}
+        },
+        ${options.body ? `body: JSON.stringify(${JSON.stringify(options.body)}),` : ''}
+      });
+      return res.json();
+    })()
+  `;
+
+  const result = await page.evaluate(js);
+
+  if (result && typeof result === 'object' && 'status_code' in result) {
+    const code = (result as { status_code: number }).status_code;
+    if (code !== 0) {
+      const msg = (result as { status_msg?: string }).status_msg ?? 'unknown error';
+      throw new CommandExecutionError(`Douyin API error ${code}: ${msg}`);
+    }
+  }
+
+  return result;
+}

src/clis/douyin/_shared/creation-id.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { generateCreationId } from './creation-id.js';
+
+describe('generateCreationId', () => {
+  it('starts with "pin"', () => {
+    expect(generateCreationId()).toMatch(/^pin/);
+  });
+
+  it('has 4 random lowercase-alphanumeric chars after "pin"', () => {
+    expect(generateCreationId()).toMatch(/^pin[a-z0-9]{4}/);
+  });
+
+  it('ends with a numeric timestamp (ms)', () => {
+    const before = Date.now();
+    const id = generateCreationId();
+    const after = Date.now();
+    const ts = parseInt(id.replace(/^pin[a-z0-9]{4}/, ''), 10);
+    expect(ts).toBeGreaterThanOrEqual(before);
+    expect(ts).toBeLessThanOrEqual(after);
+  });
+
+  it('generates unique IDs', () => {
+    const ids = new Set(Array.from({ length: 100 }, generateCreationId));
+    expect(ids.size).toBe(100);
+  });
+});

src/clis/douyin/_shared/creation-id.ts

@@ -0,0 +1,8 @@
+const CHARS = 'abcdefghijklmnopqrstuvwxyz0123456789';
+
+export function generateCreationId(): string {
+  const random = Array.from({ length: 4 }, () =>
+    CHARS[Math.floor(Math.random() * CHARS.length)]
+  ).join('');
+  return 'pin' + random + Date.now();
+}

src/clis/douyin/_shared/imagex-upload.test.ts

@@ -0,0 +1,113 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { CommandExecutionError } from '../../../errors.js';
+import { imagexUpload } from './imagex-upload.js';
+import type { ImageXUploadInfo } from './imagex-upload.js';
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeTempImage(ext = '.jpg'): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'imagex-test-'));
+  const filePath = path.join(dir, `cover${ext}`);
+  fs.writeFileSync(filePath, Buffer.from([0xff, 0xd8, 0xff, 0xe0])); // minimal JPEG header bytes
+  return filePath;
+}
+
+const FAKE_UPLOAD_INFO: ImageXUploadInfo = {
+  upload_url: 'https://imagex.bytedance.com/upload/presigned/fake',
+  store_uri: 'tos-cn-i-alisg.example.com/cover/abc123',
+};
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe('imagexUpload', () => {
+  let imagePath: string;
+
+  beforeEach(() => {
+    imagePath = makeTempImage('.jpg');
+  });
+
+  afterEach(() => {
+    // Clean up temp files
+    try {
+      fs.unlinkSync(imagePath);
+      fs.rmdirSync(path.dirname(imagePath));
+    } catch {
+      // ignore cleanup errors
+    }
+    vi.restoreAllMocks();
+  });
+
+  it('throws CommandExecutionError when image file does not exist', async () => {
+    await expect(
+      imagexUpload('/nonexistent/path/cover.jpg', FAKE_UPLOAD_INFO),
+    ).rejects.toThrow(CommandExecutionError);
+
+    await expect(
+      imagexUpload('/nonexistent/path/cover.jpg', FAKE_UPLOAD_INFO),
+    ).rejects.toThrow('Cover image file not found');
+  });
+
+  it('PUTs the image and returns store_uri on success', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      text: vi.fn().mockResolvedValue(''),
+    });
+    vi.stubGlobal('fetch', mockFetch);
+
+    const result = await imagexUpload(imagePath, FAKE_UPLOAD_INFO);
+
+    expect(result).toBe(FAKE_UPLOAD_INFO.store_uri);
+    expect(mockFetch).toHaveBeenCalledOnce();
+    const [url, init] = mockFetch.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe(FAKE_UPLOAD_INFO.upload_url);
+    expect(init.method).toBe('PUT');
+    expect((init.headers as Record<string, string>)['Content-Type']).toBe(
+      'image/jpeg',
+    );
+  });
+
+  it('uses image/png Content-Type for .png files', async () => {
+    const pngPath = makeTempImage('.png');
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      text: vi.fn().mockResolvedValue(''),
+    });
+    vi.stubGlobal('fetch', mockFetch);
+
+    try {
+      await imagexUpload(pngPath, FAKE_UPLOAD_INFO);
+      const [, init] = mockFetch.mock.calls[0] as [string, RequestInit];
+      expect((init.headers as Record<string, string>)['Content-Type']).toBe(
+        'image/png',
+      );
+    } finally {
+      try {
+        fs.unlinkSync(pngPath);
+        fs.rmdirSync(path.dirname(pngPath));
+      } catch {
+        // ignore
+      }
+    }
+  });
+
+  it('throws CommandExecutionError on non-2xx PUT response', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 403,
+      text: vi.fn().mockResolvedValue('Forbidden'),
+    });
+    vi.stubGlobal('fetch', mockFetch);
+
+    await expect(imagexUpload(imagePath, FAKE_UPLOAD_INFO)).rejects.toThrow(
+      CommandExecutionError,
+    );
+    await expect(imagexUpload(imagePath, FAKE_UPLOAD_INFO)).rejects.toThrow(
+      'ImageX upload failed with status 403',
+    );
+  });
+});

src/clis/douyin/_shared/imagex-upload.ts

@@ -0,0 +1,76 @@
+/**
+ * ImageX cover image uploader.
+ *
+ * Uploads a JPEG/PNG image to ByteDance ImageX via a pre-signed PUT URL
+ * obtained from the Douyin "apply cover upload" API.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { CommandExecutionError } from '../../../errors.js';
+
+export interface ImageXUploadInfo {
+  /** Pre-signed PUT target URL (provided by the apply cover upload API) */
+  upload_url: string;
+  /** Image URI to use in create_v2 (returned from the apply step) */
+  store_uri: string;
+}
+
+/**
+ * Detect MIME type from file extension.
+ * Falls back to image/jpeg for unknown extensions.
+ */
+function detectContentType(filePath: string): string {
+  const ext = path.extname(filePath).toLowerCase();
+  switch (ext) {
+    case '.png':
+      return 'image/png';
+    case '.gif':
+      return 'image/gif';
+    case '.webp':
+      return 'image/webp';
+    default:
+      return 'image/jpeg';
+  }
+}
+
+/**
+ * Upload a cover image to ByteDance ImageX via a pre-signed PUT URL.
+ *
+ * @param imagePath - Local file path to the image (JPEG/PNG/etc.)
+ * @param uploadInfo - Upload URL and store_uri from the apply cover upload API
+ * @returns The store_uri (= image_uri for use in create_v2)
+ */
+export async function imagexUpload(
+  imagePath: string,
+  uploadInfo: ImageXUploadInfo,
+): Promise<string> {
+  if (!fs.existsSync(imagePath)) {
+    throw new CommandExecutionError(
+      `Cover image file not found: ${imagePath}`,
+      'Ensure the file path is correct and accessible.',
+    );
+  }
+
+  const imageBuffer = fs.readFileSync(imagePath);
+  const contentType = detectContentType(imagePath);
+
+  const res = await fetch(uploadInfo.upload_url, {
+    method: 'PUT',
+    headers: {
+      'Content-Type': contentType,
+      'Content-Length': String(imageBuffer.byteLength),
+    },
+    body: imageBuffer as unknown as BodyInit,
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new CommandExecutionError(
+      `ImageX upload failed with status ${res.status}: ${body}`,
+      'Check that the upload URL is valid and has not expired.',
+    );
+  }
+
+  return uploadInfo.store_uri;
+}