@jackwener/opencli 1.7.3 → 1.7.4

package/clis/xiaoyuzhou/auth.js

@@ -0,0 +1,303 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { CliError, CommandExecutionError, ConfigError, EXIT_CODES, getErrorMessage } from '@jackwener/opencli/errors';
+
+export const XIAOYUZHOU_API_BASE_URL = 'https://api.xiaoyuzhoufm.com';
+export const XIAOYUZHOU_TOKEN_TTL_MS = 20 * 60 * 1000;
+export const XIAOYUZHOU_REFRESH_SKEW_MS = 60 * 1000;
+export const XIAOYUZHOU_DEFAULT_DEVICE_ID = '81ADBFD6-6921-482B-9AB9-A29E7CC7BB55';
+export const XIAOYUZHOU_DEFAULT_DEVICE_PROPERTIES = '';
+export const XIAOYUZHOU_DEFAULT_USER_AGENT = 'Xiaoyuzhou/2.98.0 (build:2908; iOS 26.2.1)';
+
+function getNowMs() {
+    return Date.now();
+}
+
+export function getXiaoyuzhouCredentialFile() {
+    return path.join(os.homedir(), '.opencli', 'xiaoyuzhou.json');
+}
+
+function createXiaoyuzhouAuthError(message) {
+    return new CliError('AUTH_REQUIRED', message, `Update ${getXiaoyuzhouCredentialFile()} with fresh Xiaoyuzhou credentials before retrying.`, EXIT_CODES.NOPERM);
+}
+
+function coerceNumber(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+
+export function normalizeXiaoyuzhouCredentials(raw = {}) {
+    const lastUpdatedTs = coerceNumber(raw.last_updated_ts ?? raw.lastUpdatedTs);
+    let expiresAt = coerceNumber(raw.expires_at ?? raw.expiresAt);
+    if (expiresAt > 0 && expiresAt < 10_000_000_000) {
+        expiresAt *= 1000;
+    }
+    if (!expiresAt && lastUpdatedTs > 0) {
+        expiresAt = lastUpdatedTs * 1000 + XIAOYUZHOU_TOKEN_TTL_MS;
+    }
+    return {
+        access_token: String(raw.access_token ?? raw.accessToken ?? '').trim(),
+        refresh_token: String(raw.refresh_token ?? raw.refreshToken ?? '').trim(),
+        expires_at: expiresAt,
+        device_id: String(raw.device_id ?? raw.deviceId ?? XIAOYUZHOU_DEFAULT_DEVICE_ID).trim() || XIAOYUZHOU_DEFAULT_DEVICE_ID,
+        device_properties: String(raw.device_properties ?? raw.deviceProperties ?? XIAOYUZHOU_DEFAULT_DEVICE_PROPERTIES),
+    };
+}
+export function loadXiaoyuzhouCredentials() {
+    const filePath = getXiaoyuzhouCredentialFile();
+    if (fs.existsSync(filePath)) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+            const credentials = normalizeXiaoyuzhouCredentials(parsed);
+            if (!credentials.access_token || !credentials.refresh_token) {
+                throw new ConfigError(`Xiaoyuzhou credential file is missing access_token or refresh_token: ${filePath}`, 'Recreate the file with valid credentials.');
+            }
+            return credentials;
+        }
+        catch (error) {
+            if (error instanceof ConfigError) {
+                throw error;
+            }
+            throw new ConfigError(`Failed to parse Xiaoyuzhou credential file: ${filePath}`, `Ensure ${filePath} contains valid JSON. (${getErrorMessage(error)})`);
+        }
+    }
+    throw new ConfigError(`Missing Xiaoyuzhou credentials. Expected ${filePath}`, `Create ${filePath} with access_token and refresh_token.`);
+}
+
+export function saveXiaoyuzhouCredentials(credentials) {
+    const filePath = getXiaoyuzhouCredentialFile();
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify({
+        access_token: credentials.access_token,
+        refresh_token: credentials.refresh_token,
+        expires_at: credentials.expires_at,
+        device_id: credentials.device_id,
+        device_properties: credentials.device_properties,
+    }, null, 2)}\n`, 'utf-8');
+}
+
+export function shouldRefreshXiaoyuzhouCredentials(credentials, now = getNowMs()) {
+    return Number.isFinite(credentials.expires_at)
+        && credentials.expires_at > 0
+        && now >= credentials.expires_at - XIAOYUZHOU_REFRESH_SKEW_MS;
+}
+
+export function buildXiaoyuzhouHeaders(credentials, options = {}) {
+    const {
+        contentType = 'application/json',
+        includeLocalTime = false,
+        includeRefreshToken = false,
+    } = options;
+    const headers = {
+        'Content-Type': contentType,
+        Host: 'api.xiaoyuzhoufm.com',
+        'User-Agent': XIAOYUZHOU_DEFAULT_USER_AGENT,
+        Market: 'AppStore',
+        'App-BuildNo': '2908',
+        OS: 'ios',
+        Manufacturer: 'Apple',
+        BundleID: 'app.podcast.cosmos',
+        Connection: 'keep-alive',
+        'abtest-info': '{"old_user_discovery_feed":"enable"}',
+        'Accept-Language': 'en-HK;q=1.0, zh-Hans-HK;q=0.9',
+        Model: 'iPhone18,1',
+        'app-permissions': '100000',
+        Accept: '*/*',
+        'App-Version': '2.98.0',
+        WifiConnected: 'true',
+        'OS-Version': '26.2.1',
+        'x-custom-xiaoyuzhou-app-dev': '',
+        'x-jike-device-id': credentials.device_id || XIAOYUZHOU_DEFAULT_DEVICE_ID,
+        'x-jike-device-properties': credentials.device_properties ?? XIAOYUZHOU_DEFAULT_DEVICE_PROPERTIES,
+    };
+    if (credentials.access_token) {
+        headers['x-jike-access-token'] = credentials.access_token;
+    }
+    if (includeRefreshToken && credentials.refresh_token) {
+        headers['x-jike-refresh-token'] = credentials.refresh_token;
+    }
+    if (includeLocalTime) {
+        headers['Local-Time'] = new Date().toISOString();
+        headers.Timezone = Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+    }
+    return headers;
+}
+
+export async function refreshXiaoyuzhouCredentials(credentials, fetchImpl = fetch) {
+    if (!credentials.refresh_token) {
+        throw createXiaoyuzhouAuthError('Xiaoyuzhou refresh token is missing');
+    }
+    let response;
+    try {
+        response = await fetchImpl(`${XIAOYUZHOU_API_BASE_URL}/app_auth_tokens.refresh`, {
+            method: 'POST',
+            headers: buildXiaoyuzhouHeaders(credentials, {
+                contentType: 'application/x-www-form-urlencoded; charset=utf-8',
+                includeLocalTime: true,
+                includeRefreshToken: true,
+            }),
+            signal: AbortSignal.timeout(20_000),
+        });
+    }
+    catch (error) {
+        throw new CommandExecutionError(`Failed to refresh Xiaoyuzhou credentials: ${getErrorMessage(error)}`);
+    }
+    const bodyText = await response.text();
+    if (!response.ok) {
+        throw createXiaoyuzhouAuthError(`Xiaoyuzhou token refresh failed with HTTP ${response.status}${bodyText ? `: ${bodyText}` : ''}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(bodyText);
+    }
+    catch (error) {
+        throw new CommandExecutionError(`Xiaoyuzhou refresh returned invalid JSON: ${getErrorMessage(error)}`);
+    }
+    if (!parsed?.success) {
+        throw createXiaoyuzhouAuthError('Xiaoyuzhou refresh API returned success=false');
+    }
+    const nextCredentials = normalizeXiaoyuzhouCredentials({
+        ...credentials,
+        access_token: parsed['x-jike-access-token'] || '',
+        refresh_token: parsed['x-jike-refresh-token'] || '',
+        expires_at: getNowMs() + XIAOYUZHOU_TOKEN_TTL_MS,
+    });
+    if (!nextCredentials.access_token || !nextCredentials.refresh_token) {
+        throw createXiaoyuzhouAuthError('Xiaoyuzhou refresh API returned empty access_token or refresh_token');
+    }
+    saveXiaoyuzhouCredentials(nextCredentials);
+    return nextCredentials;
+}
+
+function buildApiUrl(endpoint, query) {
+    const url = new URL(endpoint, XIAOYUZHOU_API_BASE_URL);
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined && value !== null && value !== '') {
+                url.searchParams.set(key, String(value));
+            }
+        }
+    }
+    return url.toString();
+}
+
+async function performXiaoyuzhouJsonRequest(endpoint, options, credentials, fetchImpl) {
+    const {
+        method = 'GET',
+        query,
+        body,
+    } = options;
+    let response;
+    try {
+        response = await fetchImpl(buildApiUrl(endpoint, query), {
+            method,
+            headers: buildXiaoyuzhouHeaders(credentials, {
+                contentType: 'application/json',
+                includeLocalTime: true,
+            }),
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: AbortSignal.timeout(20_000),
+        });
+    }
+    catch (error) {
+        throw new CommandExecutionError(`Failed to reach Xiaoyuzhou API: ${getErrorMessage(error)}`);
+    }
+    return response;
+}
+
+export async function requestXiaoyuzhouJson(endpoint, options = {}, fetchImpl = fetch) {
+    let credentials = options.credentials ?? loadXiaoyuzhouCredentials();
+    if (shouldRefreshXiaoyuzhouCredentials(credentials)) {
+        credentials = await refreshXiaoyuzhouCredentials(credentials, fetchImpl);
+    }
+    let response = await performXiaoyuzhouJsonRequest(endpoint, options, credentials, fetchImpl);
+    if (response.status === 401) {
+        credentials = await refreshXiaoyuzhouCredentials(credentials, fetchImpl);
+        response = await performXiaoyuzhouJsonRequest(endpoint, options, credentials, fetchImpl);
+    }
+    const bodyText = await response.text();
+    if (!response.ok) {
+        throw new CommandExecutionError(`Xiaoyuzhou API request failed with HTTP ${response.status}${bodyText ? `: ${bodyText}` : ''}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(bodyText);
+    }
+    catch (error) {
+        throw new CommandExecutionError(`Xiaoyuzhou API returned invalid JSON: ${getErrorMessage(error)}`);
+    }
+    if (parsed?.success === false) {
+        throw new CommandExecutionError(parsed?.message || parsed?.msg || 'Xiaoyuzhou API returned success=false');
+    }
+    return {
+        credentials,
+        raw: parsed,
+        data: parsed?.data,
+    };
+}
+
+export async function fetchXiaoyuzhouTranscriptBody(url, fetchImpl = fetch) {
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: 'GET',
+            headers: {
+                'User-Agent': XIAOYUZHOU_DEFAULT_USER_AGENT,
+                Accept: '*/*',
+                Market: 'AppStore',
+            },
+            signal: AbortSignal.timeout(20_000),
+        });
+    }
+    catch (error) {
+        throw new CommandExecutionError(`Failed to fetch Xiaoyuzhou transcript content: ${getErrorMessage(error)}`);
+    }
+    const bodyText = await response.text();
+    if (!response.ok) {
+        throw new CommandExecutionError(`Xiaoyuzhou transcript download failed with HTTP ${response.status}${bodyText ? `: ${bodyText}` : ''}`);
+    }
+    return bodyText;
+}
+
+export function extractTranscriptText(transcriptBody) {
+    let parsed;
+    try {
+        parsed = JSON.parse(transcriptBody);
+    }
+    catch {
+        return { text: '', segmentCount: 0 };
+    }
+    let items = [];
+    if (Array.isArray(parsed)) {
+        items = parsed;
+    }
+    else if (parsed && typeof parsed === 'object') {
+        for (const key of ['segments', 'data', 'transcript', 'items']) {
+            if (Array.isArray(parsed[key])) {
+                items = parsed[key];
+                break;
+            }
+        }
+        if (items.length === 0) {
+            const directText = typeof parsed.text === 'string' ? parsed.text.trim() : '';
+            if (directText) {
+                return { text: directText, segmentCount: 1 };
+            }
+        }
+    }
+    const textItems = [];
+    for (const item of items) {
+        if (!item || typeof item !== 'object' || typeof item.text !== 'string') {
+            continue;
+        }
+        const cleaned = item.text.trim();
+        if (cleaned) {
+            textItems.push(cleaned);
+        }
+    }
+    return {
+        text: textItems.join('\n'),
+        segmentCount: textItems.length,
+    };
+}

package/clis/xiaoyuzhou/auth.test.js

@@ -0,0 +1,124 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { mockExistsSync, mockReadFileSync, mockMkdirSync, mockWriteFileSync, mockHomedir } = vi.hoisted(() => ({
+    mockExistsSync: vi.fn(),
+    mockReadFileSync: vi.fn(),
+    mockMkdirSync: vi.fn(),
+    mockWriteFileSync: vi.fn(),
+    mockHomedir: vi.fn(() => '/Users/tester'),
+}));
+
+vi.mock('node:fs', () => ({
+    existsSync: mockExistsSync,
+    readFileSync: mockReadFileSync,
+    mkdirSync: mockMkdirSync,
+    writeFileSync: mockWriteFileSync,
+}));
+
+vi.mock('node:os', () => ({
+    homedir: mockHomedir,
+}));
+
+const { extractTranscriptText, getXiaoyuzhouCredentialFile, loadXiaoyuzhouCredentials, normalizeXiaoyuzhouCredentials, refreshXiaoyuzhouCredentials, requestXiaoyuzhouJson, shouldRefreshXiaoyuzhouCredentials, XIAOYUZHOU_TOKEN_TTL_MS } = await import('./auth.js');
+
+function createJsonResponse(status, payload) {
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        text: vi.fn().mockResolvedValue(JSON.stringify(payload)),
+    };
+}
+
+describe('xiaoyuzhou auth helpers', () => {
+    beforeEach(() => {
+        mockExistsSync.mockReset();
+        mockReadFileSync.mockReset();
+        mockMkdirSync.mockReset();
+        mockWriteFileSync.mockReset();
+        vi.useRealTimers();
+    });
+
+    it('loads credentials from the local credential file', () => {
+        mockExistsSync.mockReturnValue(true);
+        mockReadFileSync.mockReturnValue(JSON.stringify({
+            access_token: 'file-access',
+            refresh_token: 'file-refresh',
+            expires_at: 123,
+        }));
+        const credentials = loadXiaoyuzhouCredentials();
+        expect(mockReadFileSync).toHaveBeenCalledWith(getXiaoyuzhouCredentialFile(), 'utf-8');
+        expect(credentials.access_token).toBe('file-access');
+        expect(credentials.refresh_token).toBe('file-refresh');
+    });
+
+    it('refreshes credentials and persists the updated token file', async () => {
+        vi.useFakeTimers();
+        vi.setSystemTime(new Date('2026-04-15T00:00:00Z'));
+        const fetchMock = vi.fn().mockResolvedValue(createJsonResponse(200, {
+            success: true,
+            'x-jike-access-token': 'new-access',
+            'x-jike-refresh-token': 'new-refresh',
+        }));
+        const refreshed = await refreshXiaoyuzhouCredentials(normalizeXiaoyuzhouCredentials({
+            access_token: 'old-access',
+            refresh_token: 'old-refresh',
+            device_id: 'device-1',
+            device_properties: 'props',
+        }), fetchMock);
+        expect(refreshed.access_token).toBe('new-access');
+        expect(refreshed.refresh_token).toBe('new-refresh');
+        expect(refreshed.expires_at).toBe(Date.now() + XIAOYUZHOU_TOKEN_TTL_MS);
+        expect(mockMkdirSync).toHaveBeenCalledWith('/Users/tester/.opencli', { recursive: true });
+        expect(mockWriteFileSync).toHaveBeenCalledWith('/Users/tester/.opencli/xiaoyuzhou.json', expect.stringContaining('"access_token": "new-access"'), 'utf-8');
+    });
+
+    it('retries once on 401 using refreshed credentials', async () => {
+        const fetchMock = vi.fn()
+            .mockResolvedValueOnce({
+            ok: false,
+            status: 401,
+            text: vi.fn().mockResolvedValue('unauthorized'),
+        })
+            .mockResolvedValueOnce(createJsonResponse(200, {
+            success: true,
+            'x-jike-access-token': 'refreshed-access',
+            'x-jike-refresh-token': 'refreshed-refresh',
+        }))
+            .mockResolvedValueOnce(createJsonResponse(200, {
+            success: true,
+            data: { title: 'Transcript Episode' },
+        }));
+        const result = await requestXiaoyuzhouJson('/v1/episode/get', {
+            query: { eid: 'ep123' },
+            credentials: normalizeXiaoyuzhouCredentials({
+                access_token: 'old-access',
+                refresh_token: 'old-refresh',
+            }),
+        }, fetchMock);
+        expect(fetchMock).toHaveBeenCalledTimes(3);
+        expect(result.data).toEqual({ title: 'Transcript Episode' });
+        expect(result.credentials.access_token).toBe('refreshed-access');
+    });
+
+    it('extracts transcript text from segment arrays and direct text payloads', () => {
+        expect(extractTranscriptText(JSON.stringify({
+            segments: [{ text: 'hello ' }, { text: ' world' }],
+        }))).toEqual({
+            text: 'hello\nworld',
+            segmentCount: 2,
+        });
+        expect(extractTranscriptText(JSON.stringify({ text: 'full transcript' }))).toEqual({
+            text: 'full transcript',
+            segmentCount: 1,
+        });
+    });
+
+    it('detects credentials that are close to expiry', () => {
+        expect(shouldRefreshXiaoyuzhouCredentials({
+            expires_at: Date.now() - 1,
+        })).toBe(true);
+        expect(shouldRefreshXiaoyuzhouCredentials({
+            expires_at: Date.now() + 10 * 60 * 1000,
+        })).toBe(false);
+    });
+});

package/clis/xiaoyuzhou/download.js

@@ -0,0 +1,49 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CliError } from '@jackwener/opencli/errors';
+import { httpDownload, sanitizeFilename } from '@jackwener/opencli/download';
+import { formatBytes } from '@jackwener/opencli/download/progress';
+import { fetchPageProps } from './utils.js';
+
+cli({
+    site: 'xiaoyuzhou',
+    name: 'download',
+    description: 'Download Xiaoyuzhou episode audio',
+    domain: 'www.xiaoyuzhoufm.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', positional: true, required: true, help: 'Episode ID (eid from podcast-episodes output)' },
+        { name: 'output', default: './xiaoyuzhou-downloads', help: 'Output directory' },
+    ],
+    columns: ['title', 'podcast', 'status', 'size', 'file'],
+    func: async (_page, args) => {
+        const pageProps = await fetchPageProps(`/episode/${args.id}`);
+        const ep = pageProps.episode;
+        if (!ep) {
+            throw new CliError('NOT_FOUND', 'Episode not found', 'Please check the ID');
+        }
+        const audioUrl = ep.media?.source?.url;
+        if (!audioUrl) {
+            throw new CliError('PARSE_ERROR', 'Audio URL not found in episode payload', 'Episode payload does not expose media.source.url');
+        }
+        const output = String(args.output || './xiaoyuzhou-downloads');
+        const ext = path.extname(new URL(audioUrl).pathname) || '.mp3';
+        const title = String(ep.title || 'episode');
+        const filename = `${args.id}_${sanitizeFilename(title, 80) || 'episode'}${ext}`;
+        const outputDir = path.join(output, String(args.id));
+        fs.mkdirSync(outputDir, { recursive: true });
+        const destPath = path.join(outputDir, filename);
+        const result = await httpDownload(audioUrl, destPath, {
+            timeout: 60000,
+        });
+        return [{
+                title,
+                podcast: ep.podcast?.title || '-',
+                status: result.success ? 'success' : 'failed',
+                size: result.success ? formatBytes(result.size) : (result.error || 'unknown error'),
+                file: result.success ? destPath : '-',
+            }];
+    },
+});

package/clis/xiaoyuzhou/download.test.js

@@ -0,0 +1,125 @@
+import path from 'node:path';
+import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+
+const { mockFetchPageProps, mockHttpDownload, mockMkdirSync } = vi.hoisted(() => ({
+    mockFetchPageProps: vi.fn(),
+    mockHttpDownload: vi.fn(),
+    mockMkdirSync: vi.fn(),
+}));
+
+vi.mock('./utils.js', async () => {
+    const actual = await vi.importActual('./utils.js');
+    return {
+        ...actual,
+        fetchPageProps: mockFetchPageProps,
+    };
+});
+
+vi.mock('@jackwener/opencli/download', () => ({
+    httpDownload: mockHttpDownload,
+    sanitizeFilename: vi.fn((value) => value.replace(/\s+/g, '_')),
+}));
+
+vi.mock('@jackwener/opencli/download/progress', () => ({
+    formatBytes: vi.fn((size) => `${size} B`),
+}));
+
+vi.mock('node:fs', () => ({
+    mkdirSync: mockMkdirSync,
+}));
+
+await import('./download.js');
+
+let cmd;
+
+function toPosixPath(value) {
+    return value.replaceAll(path.sep, '/');
+}
+
+beforeAll(() => {
+    cmd = getRegistry().get('xiaoyuzhou/download');
+    expect(cmd?.func).toBeTypeOf('function');
+});
+
+describe('xiaoyuzhou download', () => {
+    beforeEach(() => {
+        mockFetchPageProps.mockReset();
+        mockHttpDownload.mockReset();
+        mockMkdirSync.mockReset();
+    });
+
+    it('downloads audio from media.source.url into an episode subdirectory', async () => {
+        mockFetchPageProps.mockResolvedValue({
+            episode: {
+                title: 'Hello World',
+                podcast: { title: 'OpenCLI FM' },
+                media: {
+                    source: {
+                        url: 'https://media.xyzcdn.net/audio/hello-world.mp3?sign=abc',
+                    },
+                },
+            },
+        });
+        mockHttpDownload.mockResolvedValue({ success: true, size: 1234 });
+
+        const result = await cmd.func(null, {
+            id: 'ep123',
+            output: '/tmp/xiaoyuzhou-test',
+        });
+
+        expect(mockFetchPageProps).toHaveBeenCalledWith('/episode/ep123');
+        expect(toPosixPath(mockMkdirSync.mock.calls[0][0])).toBe('/tmp/xiaoyuzhou-test/ep123');
+        expect(mockMkdirSync.mock.calls[0][1]).toEqual({ recursive: true });
+        expect(mockHttpDownload).toHaveBeenCalledWith('https://media.xyzcdn.net/audio/hello-world.mp3?sign=abc', expect.stringContaining('/tmp/xiaoyuzhou-test/ep123/ep123_Hello_World.mp3'), {
+            timeout: 60000,
+        });
+        expect(result).toEqual([{
+                title: 'Hello World',
+                podcast: 'OpenCLI FM',
+                status: 'success',
+                size: '1234 B',
+                file: '/tmp/xiaoyuzhou-test/ep123/ep123_Hello_World.mp3',
+            }]);
+    });
+
+    it('preserves non-mp3 extensions from media.source.url', async () => {
+        mockFetchPageProps.mockResolvedValue({
+            episode: {
+                title: 'Lossless Episode',
+                podcast: { title: 'OpenCLI FM' },
+                media: {
+                    source: {
+                        url: 'https://media.xyzcdn.net/audio/lossless.m4a',
+                    },
+                },
+            },
+        });
+        mockHttpDownload.mockResolvedValue({ success: true, size: 2048 });
+
+        const result = await cmd.func(null, {
+            id: 'ep456',
+            output: '/tmp/xiaoyuzhou-test',
+        });
+
+        expect(mockHttpDownload.mock.calls[0][1]).toContain('ep456_Lossless_Episode.m4a');
+        expect(result[0].file).toBe('/tmp/xiaoyuzhou-test/ep456/ep456_Lossless_Episode.m4a');
+    });
+
+    it('throws when media.source.url is missing', async () => {
+        mockFetchPageProps.mockResolvedValue({
+            episode: {
+                title: 'No Audio',
+                podcast: { title: 'OpenCLI FM' },
+                media: {},
+            },
+        });
+
+        await expect(cmd.func(null, { id: 'ep789', output: '/tmp/xiaoyuzhou-test' })).rejects.toMatchObject({
+            code: 'PARSE_ERROR',
+            message: 'Audio URL not found in episode payload',
+            hint: 'Episode payload does not expose media.source.url',
+        });
+        expect(mockHttpDownload).not.toHaveBeenCalled();
+    });
+});

package/clis/xiaoyuzhou/transcript.js

@@ -0,0 +1,76 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CliError } from '@jackwener/opencli/errors';
+import { loadXiaoyuzhouCredentials, requestXiaoyuzhouJson, fetchXiaoyuzhouTranscriptBody, extractTranscriptText } from './auth.js';
+
+cli({
+    site: 'xiaoyuzhou',
+    name: 'transcript',
+    description: 'Download Xiaoyuzhou transcript as JSON and text (requires local credentials)',
+    domain: 'www.xiaoyuzhoufm.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'id', positional: true, required: true, help: 'Episode ID (eid from podcast-episodes output)' },
+        { name: 'output', default: './xiaoyuzhou-transcripts', help: 'Output directory' },
+        { name: 'json', type: 'boolean', default: true, help: 'Save transcript JSON file' },
+        { name: 'text', type: 'boolean', default: true, help: 'Save extracted transcript text file' },
+    ],
+    columns: ['title', 'podcast', 'status', 'segments', 'json_file', 'text_file'],
+    func: async (_page, kwargs) => {
+        if (kwargs.json === false && kwargs.text === false) {
+            throw new ArgumentError('At least one of --json or --text must be enabled', 'Example: opencli xiaoyuzhou transcript 69dd0c98e2c8be31551f6a33 --text true');
+        }
+        let credentials = loadXiaoyuzhouCredentials();
+        const episodeResponse = await requestXiaoyuzhouJson('/v1/episode/get', {
+            query: { eid: kwargs.id },
+            credentials,
+        });
+        credentials = episodeResponse.credentials;
+        const episode = episodeResponse.data;
+        if (!episode) {
+            throw new CliError('NOT_FOUND', 'Episode not found', 'Please check the episode ID');
+        }
+        const mediaId = String(episode.transcript?.mediaId || episode.media?.id || episode.transcriptMediaId || '').trim();
+        if (!mediaId) {
+            throw new CliError('PARSE_ERROR', 'mediaId not found in episode payload', 'Transcript metadata requires episode.transcript.mediaId, episode.media.id, or episode.transcriptMediaId');
+        }
+        const transcriptResponse = await requestXiaoyuzhouJson('/v1/episode-transcript/get', {
+            method: 'POST',
+            body: {
+                eid: kwargs.id,
+                mediaId,
+            },
+            credentials,
+        });
+        const transcriptMeta = transcriptResponse.data;
+        const transcriptUrl = String(transcriptMeta?.transcriptUrl || transcriptMeta?.url || '').trim();
+        if (!transcriptUrl) {
+            throw new CliError('EMPTY_RESULT', 'Transcript URL not found', 'This episode may not have transcript data available');
+        }
+        const transcriptBody = await fetchXiaoyuzhouTranscriptBody(transcriptUrl);
+        const { text, segmentCount } = extractTranscriptText(transcriptBody);
+        if (kwargs.text !== false && transcriptBody.trim() && !text.trim()) {
+            throw new CliError('PARSE_ERROR', 'Failed to extract transcript text', 'Transcript payload format is unsupported. Re-run with --json true to inspect the raw payload.');
+        }
+        const outputDir = path.join(String(kwargs.output || './xiaoyuzhou-transcripts'), String(kwargs.id));
+        fs.mkdirSync(outputDir, { recursive: true });
+        const jsonPath = path.join(outputDir, 'transcript.json');
+        const textPath = path.join(outputDir, 'transcript.txt');
+        if (kwargs.json !== false) {
+            fs.writeFileSync(jsonPath, transcriptBody, 'utf-8');
+        }
+        if (kwargs.text !== false) {
+            fs.writeFileSync(textPath, text, 'utf-8');
+        }
+        return [{
+                title: episode.title || 'episode',
+                podcast: episode.podcast?.title || '-',
+                status: 'success',
+                segments: kwargs.text === false ? '-' : String(segmentCount),
+                json_file: kwargs.json === false ? '-' : jsonPath,
+                text_file: kwargs.text === false ? '-' : textPath,
+            }];
+    },
+});