@sovovs/bycli 2.1.45 → 2.1.46

package/cli-manifest.json

@@ -29457,8 +29457,8 @@
   {
     "site": "weixin",
     "name": "user-growth",
-    "description": "读取公众号用户增长趋势，包括新增、取消、净增和累计关注人数",
-    "access": "read",
+    "description": "读取公众号用户增长趋势，可选返回全部渠道并下载官方“全部来源”XLS",
+    "access": "write",
     "domain": "mp.weixin.qq.com",
     "strategy": "cookie",
     "browser": true,
@@ -29481,6 +29481,12 @@
         "default": "all",
         "required": false,
         "help": "传播渠道名称或代码；多个值用逗号分隔"
+      },
+      {
+        "name": "output",
+        "type": "str",
+        "required": false,
+        "help": "可选的官方“全部来源”XLS 保存目录；不传则不下载"
       }
     ],
     "columns": [
@@ -29490,7 +29496,9 @@
       "new_followers",
       "unfollows",
       "net_new_followers",
-      "cumulative_followers"
+      "cumulative_followers",
+      "official_xls_path",
+      "official_xls_size"
     ],
     "type": "js",
     "modulePath": "weixin/user-growth.js",

package/clis/weixin/_wechat/user-analysis.js

@@ -79,6 +79,9 @@ export function resolveAttributeDate(value, options = {}) {
 }
 
 export function parseGrowthSources(value = 'all') {
+  if (String(value).trim() === 'all-sources') {
+    return SOURCE_ENTRIES.map(([name, code]) => ({ name, code }));
+  }
   const rawItems = String(value).split(',').map(item => item.trim()).filter(Boolean);
   argument(rawItems.length > 0, 'source must not be empty');
   const seen = new Set();

package/clis/weixin/_wechat/user-growth-download.js

@@ -0,0 +1,152 @@
+import { constants } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { copyFile, link, mkdir, stat, unlink } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+import { ArgumentError, CommandExecutionError, TimeoutError } from '@sovovs/bycli/errors';
+import { buildGrowthUrl } from './user-analysis.js';
+
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+
+function commandError(message) {
+  return new CommandExecutionError(`WeChat user-growth XLS download ${message}`);
+}
+
+export function buildUserGrowthDownloadUrl({ token, begin, end }) {
+  const url = new URL(buildGrowthUrl({
+    token,
+    begin,
+    end,
+    sourceCodes: [99999999],
+  }));
+  url.searchParams.delete('f');
+  url.searchParams.delete('ajax');
+  url.searchParams.set('download', '1');
+  return url.toString();
+}
+
+export function isTrustedUserGrowthDownloadUrl(candidateValue, expectedValue) {
+  let candidate;
+  let expected;
+  try {
+    candidate = new URL(candidateValue);
+    expected = new URL(expectedValue);
+  } catch {
+    return false;
+  }
+  const exactParams = ['download', 'begin_date', 'end_date', 'source', 'token'];
+  return candidate.protocol === 'https:'
+    && candidate.hostname === 'mp.weixin.qq.com'
+    && candidate.port === ''
+    && candidate.pathname === '/misc/useranalysis'
+    && exactParams.every(name => candidate.searchParams.get(name) === expected.searchParams.get(name))
+    && candidate.searchParams.get('download') === '1'
+    && candidate.searchParams.get('source') === '99999999';
+}
+
+async function publishExclusively(source, outputDir, filename, beforePublish) {
+  const extension = extname(filename);
+  const stem = filename.slice(0, -extension.length);
+  const staged = resolve(outputDir, `.bycli-user-growth-${randomUUID()}.tmp`);
+  let stagedCreated = false;
+  try {
+    try {
+      await copyFile(source, staged, constants.COPYFILE_EXCL);
+      stagedCreated = true;
+    } catch {
+      try {
+        await unlink(staged);
+      } catch {
+        // COPYFILE_EXCL may fail before creating its destination.
+      }
+      throw commandError('could not stage the downloaded file');
+    }
+    for (let index = 0; index <= 9999; index += 1) {
+      const candidate = resolve(outputDir, index === 0 ? filename : `${stem}-${index}${extension}`);
+      try {
+        await beforePublish?.();
+        await link(staged, candidate);
+        return candidate;
+      } catch (error) {
+        if (error?.code === 'EEXIST') continue;
+        throw commandError('could not publish the downloaded file');
+      }
+    }
+    throw commandError('could not allocate a destination filename');
+  } finally {
+    if (stagedCreated) {
+      try {
+        await unlink(staged);
+      } catch {
+        // The final hard link remains a complete file.
+      }
+    }
+  }
+}
+
+export async function downloadUserGrowthXls(page, options) {
+  if (typeof options?.outputDir !== 'string' || !options.outputDir.trim()) {
+    throw new ArgumentError('output must be a non-empty directory');
+  }
+  if (typeof page?.waitForDownload !== 'function') {
+    throw commandError('requires browser download support');
+  }
+
+  const expectedUrl = buildUserGrowthDownloadUrl(options);
+  const startedAfterMs = Date.now();
+  let downloaded;
+  try {
+    await page.goto(expectedUrl, { waitUntil: 'none' });
+    downloaded = await page.waitForDownload('download=1', DOWNLOAD_TIMEOUT_MS, {
+      includeRecent: true,
+      startedAfterMs,
+    });
+  } catch (error) {
+    if (error instanceof TimeoutError) throw error;
+    throw commandError('could not complete the browser download');
+  }
+
+  if (!downloaded || downloaded.downloaded !== true) {
+    throw new TimeoutError('Weixin user-growth XLS download', DOWNLOAD_TIMEOUT_MS / 1000);
+  }
+  if (typeof downloaded.filename !== 'string'
+    || !downloaded.filename
+    || extname(downloaded.filename).toLowerCase() !== '.xls'
+    || downloaded.state !== 'complete'
+    || !['safe', 'accepted'].includes(downloaded.danger)) {
+    throw commandError('returned incomplete or unsafe download metadata');
+  }
+  if (![downloaded.url, downloaded.finalUrl]
+    .some(value => isTrustedUserGrowthDownloadUrl(value, expectedUrl))) {
+    throw commandError('rejected an unrelated downloaded file');
+  }
+
+  let sourceInfo;
+  try {
+    sourceInfo = await stat(downloaded.filename);
+  } catch {
+    throw commandError('could not read the downloaded file');
+  }
+  if (!sourceInfo.isFile() || sourceInfo.size <= 0) {
+    throw commandError('returned an empty downloaded file');
+  }
+
+  const outputDir = resolve(options.outputDir);
+  try {
+    await mkdir(outputDir, { recursive: true });
+  } catch {
+    throw commandError('could not create the output directory');
+  }
+  const filename = `weixin-user-growth-${options.begin}-${options.end}-all.xls`;
+  const target = await publishExclusively(
+    downloaded.filename,
+    outputDir,
+    filename,
+    options.beforePublish,
+  );
+  try {
+    await unlink(downloaded.filename);
+  } catch {
+    // Destination publication succeeded; browser temporary cleanup is best effort.
+  }
+  return { status: 'downloaded', path: target, size: sourceInfo.size };
+}

package/clis/weixin/user-growth.js

@@ -1,4 +1,4 @@
-import { EmptyResultError } from '@sovovs/bycli/errors';
+import { ArgumentError, EmptyResultError } from '@sovovs/bycli/errors';
 import { cli, Strategy } from '@sovovs/bycli/registry';
 import { resolveBrowserCredentials } from './_wechat/auth-session.js';
 import {
@@ -6,6 +6,7 @@ import {
   parseGrowthSources,
   resolveGrowthRange,
 } from './_wechat/user-analysis.js';
+import { downloadUserGrowthXls } from './_wechat/user-growth-download.js';
 
 const COLUMNS = [
   'date',
@@ -15,14 +16,16 @@ const COLUMNS = [
   'unfollows',
   'net_new_followers',
   'cumulative_followers',
+  'official_xls_path',
+  'official_xls_size',
 ];
 
 export const userGrowthCommand = cli({
   site: 'weixin',
   name: 'user-growth',
-  access: 'read',
+  access: 'write',
   domain: 'mp.weixin.qq.com',
-  description: '读取公众号用户增长趋势，包括新增、取消、净增和累计关注人数',
+  description: '读取公众号用户增长趋势，可选返回全部渠道并下载官方“全部来源”XLS',
   strategy: Strategy.COOKIE,
   browser: true,
   navigateBefore: false,
@@ -30,9 +33,14 @@ export const userGrowthCommand = cli({
     { name: 'begin', help: '开始日期（YYYY-MM-DD）；默认 30 天窗口的第一天' },
     { name: 'end', help: '结束日期（YYYY-MM-DD）；默认昨天' },
     { name: 'source', default: 'all', help: '传播渠道名称或代码；多个值用逗号分隔' },
+    { name: 'output', help: '可选的官方“全部来源”XLS 保存目录；不传则不下载' },
   ],
   columns: COLUMNS,
   func: async (page, args) => {
+    const outputDir = typeof args.output === 'string' ? args.output.trim() : null;
+    if (args.output !== undefined && (!outputDir || typeof args.output !== 'string')) {
+      throw new ArgumentError('output must be a non-empty directory');
+    }
     const { token } = await resolveBrowserCredentials(page);
     const { begin, end } = resolveGrowthRange(args);
     const sources = parseGrowthSources(args.source);
@@ -40,6 +48,9 @@ export const userGrowthCommand = cli({
     if (rows.length === 0) {
       throw new EmptyResultError('weixin user-growth', `No user growth rows are available from ${begin} through ${end}.`);
     }
+    const artifact = outputDir
+      ? await downloadUserGrowthXls(page, { token, begin, end, outputDir })
+      : null;
     return rows.map(row => ({
       date: row.date,
       source: row.source,
@@ -48,6 +59,8 @@ export const userGrowthCommand = cli({
       unfollows: row.unfollows,
       net_new_followers: row.netNewFollowers,
       cumulative_followers: row.cumulativeFollowers,
+      official_xls_path: artifact?.path ?? null,
+      official_xls_size: artifact?.size ?? null,
     }));
   },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sovovs/bycli",
-  "version": "2.1.45",
+  "version": "2.1.46",
   "publishConfig": {
     "access": "public"
   },