@sovovs/bycli 2.1.59 → 2.1.61

package/clis/iwhalecloud/client.js

@@ -0,0 +1,97 @@
+import { Strategy } from '@sovovs/bycli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError, TimeoutError } from '@sovovs/bycli/errors';
+
+export const HOST = 'mail.iwhalecloud.com';
+export const BASE = `https://${HOST}`;
+export const metadata = { site: 'iwhalecloud', domain: HOST, access: 'read', strategy: Strategy.COOKIE,
+  browser: true, navigateBefore: false, siteSession: 'persistent' };
+export const idArg = { name: 'emailId', positional: true, required: true, help: 'list 返回的 emailId（请加引号）' };
+export const SORT_FIELDS = Object.freeze({ date: 'DateTimeReceived', from: 'From', to: 'DisplayTo',
+  subject: 'Subject', attachments: 'HasAttachments', importance: 'Importance', size: 'Size',
+  sent: 'DateTimeSent', created: 'DateTimeCreated' });
+const FOLDERS = Object.freeze({ inbox: 'inbox', sent: 'sentitems', drafts: 'drafts', trash: 'deleteditems', spam: 'junkemail' });
+export function integer(value, name, min, max) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < min || n > max) throw new ArgumentError(`${name} must be an integer between ${min} and ${max}`);
+  return n;
+}
+export function requiredId(value) {
+  const id = String(value ?? '').trim();
+  if (!id) throw new ArgumentError('emailId is required; use an emailId returned by list');
+  return id;
+}
+export function folderId(args) {
+  if (args['folder-id']) return { __type: 'FolderId:#Exchange', Id: String(args['folder-id']) };
+  const key = String(args.folder ?? 'inbox');
+  if (!Object.hasOwn(FOLDERS, key)) throw new ArgumentError(`Unknown folder; choose ${Object.keys(FOLDERS).join(', ')} or --folder-id`);
+  return { __type: 'DistinguishedFolderId:#Exchange', Id: FOLDERS[key] };
+}
+export async function connect(page) {
+  await page.goto(`${BASE}/owa/`, { waitUntil: 'load' });
+}
+
+// Keep the session token inside the browser; never include it in CLI output or errors.
+export async function request(page, action, body) {
+  const result = await page.evaluate(async (actionName, requestBody) => {
+    if (location.origin !== 'https://mail.iwhalecloud.com' || /\/auth\//i.test(location.pathname)) return { auth: true };
+    const cookie = document.cookie.split(';').map(x => x.trim()).find(x => x.startsWith('X-OWA-CANARY='));
+    if (!cookie) return { auth: true };
+    try {
+      const response = await fetch(`/owa/service.svc?action=${actionName}`, {
+        method: 'POST', credentials: 'same-origin', redirect: 'error', signal: AbortSignal.timeout(30000),
+        headers: { 'Content-Type': 'application/json; charset=utf-8', Action: actionName,
+          'X-OWA-CANARY': decodeURIComponent(cookie.slice('X-OWA-CANARY='.length)) },
+        body: JSON.stringify({ __type: `${actionName}JsonRequest:#Exchange`,
+          Header: { __type: 'JsonRequestHeaders:#Exchange', RequestServerVersion: 'Exchange2013' }, Body: requestBody }),
+      });
+      if ([401, 403, 440].includes(response.status)) return { auth: true };
+      if (!response.ok) return { status: response.status };
+      const text = await response.text();
+      if (/^\s*</.test(text)) return { auth: true };
+      try { return { data: JSON.parse(text) }; } catch { return { malformed: true }; }
+    } catch (error) {
+      return { timeout: error.name === 'TimeoutError' || error.name === 'AbortError', failed: true };
+    }
+  }, action, body);
+  if (result?.auth) throw new AuthRequiredError(HOST);
+  if (result?.timeout) throw new TimeoutError(`iwhalecloud ${action}`, 30);
+  if (!result?.data) throw new CommandExecutionError(`iwhalecloud ${action} request failed${result?.status ? ` (HTTP ${result.status})` : ''}`);
+  const messages = result.data.Body?.ResponseMessages?.Items;
+  if (!Array.isArray(messages) || !messages.length) throw new CommandExecutionError(`iwhalecloud ${action}: invalid response envelope`);
+  for (const message of messages) {
+    if (message.ResponseClass !== 'Success' || message.ResponseCode !== 'NoError') {
+      const code = String(message.ResponseCode ?? 'UnknownError');
+      if (['ErrorInvalidClientAccessToken', 'ErrorInvalidUserSid'].includes(code)) throw new AuthRequiredError(HOST);
+      if (code === 'ErrorItemNotFound') throw new EmptyResultError(`iwhalecloud ${action}`, 'The mail may have been moved or deleted; refresh list');
+      throw new CommandExecutionError(`iwhalecloud ${action}: ${code}`);
+    }
+  }
+  return messages[0];
+}
+
+export function mailRow(item) {
+  if (!item?.ItemId?.Id) throw new CommandExecutionError('OWA returned an item without an emailId');
+  const sender = item.From?.Mailbox ?? item.Sender?.Mailbox ?? {};
+  return { emailId: item.ItemId.Id, subject: item.Subject ?? '', fromName: sender.Name ?? '', fromEmail: sender.EmailAddress ?? '',
+    toDisplay: item.DisplayTo ?? '', date: item.DateTimeReceived ?? '', times: { sentAt: item.DateTimeSent ?? '', createdAt: item.DateTimeCreated ?? '' },
+    unread: typeof item.IsRead === 'boolean' ? !item.IsRead : null, hasAttachments: item.HasAttachments ?? false,
+    importance: item.Importance ?? '', size: item.Size ?? 0,
+    url: `${BASE}/owa/#path=/mail/item/${encodeURIComponent(item.ItemId.Id)}` };
+}
+export const listColumns = ['emailId', 'subject', 'fromName', 'fromEmail', 'toDisplay', 'date', 'times', 'unread', 'hasAttachments', 'importance', 'size', 'url'];
+
+export async function getMail(page, emailId, bodyType = 'text') {
+  const message = await request(page, 'GetItem', { __type: 'GetItemRequest:#Exchange', ShapeName: 'ItemPart',
+    ItemShape: { __type: 'ItemResponseShape:#Exchange', BaseShape: 'AllProperties', BodyType: bodyType === 'html' ? 'HTML' : 'Text',
+      MaximumBodySize: 0, MaximumRecipientsToReturn: 10000 }, ItemIds: [{ __type: 'ItemId:#Exchange', Id: emailId }] });
+  if (!Array.isArray(message.Items) || message.Items.length !== 1 || message.Items[0]?.ItemId?.Id !== emailId) {
+    throw new CommandExecutionError('OWA GetItem did not return the requested mail');
+  }
+  return message.Items[0];
+}
+export function attachmentsOf(item) {
+  if (item.Attachments != null && !Array.isArray(item.Attachments)) throw new CommandExecutionError('OWA returned invalid attachments');
+  return (item.Attachments ?? []).map((a, index) => ({ index: index + 1, attachmentId: a.AttachmentId?.Id ?? '',
+    name: a.Name ?? '', contentType: a.ContentType ?? '', size: a.Size ?? 0, inline: a.IsInline ?? false,
+    kind: a.__type?.split(':')[0] ?? 'Unknown' }));
+}

package/clis/iwhalecloud/download.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { cli } from '@sovovs/bycli/registry';
+import { ArgumentError, AuthRequiredError, CliError, CommandExecutionError, EmptyResultError, TimeoutError } from '@sovovs/bycli/errors';
+import { metadata, idArg, requiredId, connect, getMail, attachmentsOf, BASE, HOST } from './client.js';
+import { browserDownloadResponse } from './browser-download.js';
+
+function safeName(name) {
+  const leaf = String(name).replaceAll('\\', '/').split('/').pop() ?? '';
+  const clean = leaf.replace(/[<>:"/\\|?*\x00-\x1f\x7f]/g, '_').replace(/^[. ]+|[. ]+$/g, '');
+  // Keep UTF-8 filenames below filesystem byte limits, preserving the extension.
+  const ext = path.extname(clean).slice(0, 20);
+  let stem = clean.slice(0, clean.length - ext.length) || 'attachment';
+  while (Buffer.byteLength(stem + ext) > 220) stem = Array.from(stem).slice(0, -1).join('');
+  return stem + ext;
+}
+async function reserveFile(directory, name) {
+  const ext = path.extname(name); const stem = name.slice(0, name.length - ext.length);
+  for (let index = 0; index < 10000; index++) {
+    const file = path.join(directory, index ? `${stem} (${index})${ext}` : name);
+    try { return { file, handle: await fs.open(file, 'wx', 0o600) }; }
+    catch (error) { if (error.code !== 'EEXIST') throw error; }
+  }
+  throw new CommandExecutionError('Too many files with the same attachment name');
+}
+
+export async function runDownload(page, args, deps = {}) {
+  const id = requiredId(args.emailId);
+  const output = path.resolve(String(args.output ?? '.'));
+  await connect(page);
+  const item = await getMail(page, id);
+  const attachments = attachmentsOf(item);
+  const selector = String(args.attachment ?? 'all');
+  const selected = selector === 'all' ? attachments.filter(a => !a.inline)
+    : attachments.filter(a => a.attachmentId === selector || String(a.index) === selector);
+  if (!selected.length) throw new EmptyResultError('iwhalecloud download', 'No matching attachments; use read to inspect attachment IDs and indexes');
+  if (selected.length > 1 && selector !== 'all') throw new ArgumentError('Attachment selector is ambiguous; use the attachment ID');
+  if (selected.some(a => !a.attachmentId || a.kind !== 'FileAttachment')) {
+    throw new CommandExecutionError('Only file attachments can be downloaded; select a FileAttachment ID shown by read');
+  }
+  try { await fs.mkdir(output, { recursive: true }); }
+  catch { throw new CommandExecutionError('Cannot create attachment output directory', 'Choose a writable directory with --output'); }
+  const rows = [];
+  for (const attachment of selected) {
+    let reserved;
+    let response;
+    try {
+      response = deps.fetch
+        ? await deps.fetch(`${BASE}/owa/service.svc/s/GetFileAttachment?id=${encodeURIComponent(attachment.attachmentId)}`)
+        : await browserDownloadResponse(page, attachment.attachmentId);
+      if ([301, 302, 303, 307, 308, 401, 403, 440].includes(response.status)) throw new AuthRequiredError(HOST);
+      if (!response.ok || !response.body) throw new CommandExecutionError(`Attachment download failed (HTTP ${response.status})`);
+      const contentType = response.headers.get('content-type') ?? '';
+      if (contentType.includes('text/html') && !attachment.contentType.includes('text/html')) throw new AuthRequiredError(HOST);
+      reserved = await reserveFile(output, safeName(attachment.name));
+      await pipeline(Readable.fromWeb(response.body), reserved.handle.createWriteStream());
+      const stat = await fs.stat(reserved.file);
+      rows.push({ emailId: id, attachmentId: attachment.attachmentId, name: attachment.name,
+        path: reserved.file, size: stat.size, contentType: attachment.contentType });
+    } catch (error) {
+      if (reserved) { await reserved.handle.close().catch(() => {}); await fs.unlink(reserved.file).catch(() => {}); }
+      if (response?.body && !response.body.locked) await response.body.cancel().catch(() => {});
+      const saved = rows.length ? `; ${rows.length} earlier attachment(s) were saved in ${output}` : '';
+      if (error instanceof CliError) { error.message += saved; throw error; }
+      if (error.name === 'TimeoutError' || error.name === 'AbortError') throw new TimeoutError(`Attachment download${saved}`, 120);
+      throw new CommandExecutionError(`Attachment download failed${saved}`, 'Check connectivity and retry; existing files will not be overwritten');
+    }
+  }
+  return rows;
+}
+cli({ ...metadata, name: 'download', description: '下载浩鲸邮件附件到本地目录，同名文件自动编号',
+  example: 'bycli iwhalecloud download "<emailId>" --attachment all --output ./mail-downloads -f yaml',
+  args: [idArg, { name: 'attachment', default: 'all', help: 'all（不含内嵌图片）、附件 ID 或 read 中的序号（从 1 开始）' },
+    { name: 'output', default: '.', help: '本地输出目录' }],
+  columns: ['emailId', 'attachmentId', 'name', 'path', 'size', 'contentType'], func: runDownload });

package/clis/iwhalecloud/list.js

@@ -0,0 +1,59 @@
+import { cli } from '@sovovs/bycli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@sovovs/bycli/errors';
+import { metadata, SORT_FIELDS, integer, folderId, connect, request, mailRow, listColumns } from './client.js';
+
+export async function runList(page, args) {
+  const limit = integer(args.limit ?? 20, 'limit', 1, 10000);
+  let offset = integer(args.offset ?? 0, 'offset', 0, 2147483647);
+  const sort = String(args.sort ?? 'default');
+  const order = String(args.order ?? 'default');
+  if (sort !== 'default' && !Object.hasOwn(SORT_FIELDS, sort)) throw new ArgumentError(`Unknown sort: ${sort}`);
+  if (!['default', 'asc', 'desc'].includes(order)) throw new ArgumentError('order must be default, asc or desc');
+  if (sort === 'default' && order !== 'default') throw new ArgumentError('Specify --sort to use --order; default preserves server ordering');
+  const folder = folderId(args);
+  await connect(page);
+  const rows = [];
+  const seen = new Set();
+  while (rows.length < limit) {
+    // Split the validated total into server pages; do not cap the caller's total.
+    const remaining = limit - rows.length;
+    const batchSize = remaining > 100 ? 100 : remaining;
+    const body = { __type: 'FindItemRequest:#Exchange',
+      ItemShape: { __type: 'ItemResponseShape:#Exchange', BaseShape: 'AllProperties' },
+      ParentFolderIds: [folder], Traversal: 'Shallow',
+      Paging: { __type: 'IndexedPageView:#Exchange', BasePoint: 'Beginning', Offset: offset, MaxEntriesReturned: batchSize } };
+    if (sort !== 'default') {
+      const ascending = order === 'asc' || (order === 'default' && ['from', 'to', 'subject'].includes(sort));
+      body.SortOrder = [{ __type: 'SortResults:#Exchange', Order: ascending ? 'Ascending' : 'Descending',
+        Path: { __type: 'PropertyUri:#Exchange', FieldURI: SORT_FIELDS[sort] } }];
+      if (sort !== 'date') body.SortOrder.push({ __type: 'SortResults:#Exchange', Order: 'Descending',
+        Path: { __type: 'PropertyUri:#Exchange', FieldURI: 'DateTimeReceived' } });
+    }
+    const message = await request(page, 'FindItem', body);
+    const root = message.RootFolder;
+    if (!root || !Array.isArray(root.Items)) throw new CommandExecutionError('OWA FindItem returned invalid items');
+    for (const item of root.Items) {
+      const row = mailRow(item);
+      if (seen.has(row.emailId)) throw new CommandExecutionError('Mailbox changed while paging; repeat list to avoid incomplete results');
+      seen.add(row.emailId); rows.push(row);
+      if (rows.length === limit) break;
+    }
+    if (root.IncludesLastItemInRange === true || rows.length >= limit) break;
+    const next = root.IndexedPagingOffset;
+    if (!root.Items.length || !Number.isSafeInteger(next) || next <= offset) throw new CommandExecutionError('OWA pagination did not advance');
+    offset = next;
+  }
+  if (!rows.length) throw new EmptyResultError('iwhalecloud list', 'No mail at this folder/offset');
+  return rows;
+}
+
+cli({ ...metadata, name: 'list', description: '浩鲸邮箱邮件列表：服务端分页、默认排序及 9 种字段排序',
+  example: 'bycli iwhalecloud list --sort date --order desc --limit 50 -f yaml',
+  args: [
+    { name: 'folder', default: 'inbox', choices: ['inbox', 'sent', 'drafts', 'trash', 'spam'], help: '邮件文件夹' },
+    { name: 'folder-id', help: '自定义文件夹的 OWA FolderId，优先于 --folder' },
+    { name: 'limit', type: 'int', default: 20, help: '返回数量，1–10000；自动分页' },
+    { name: 'offset', type: 'int', default: 0, help: '服务端起始偏移，0 表示第一封' },
+    { name: 'sort', default: 'default', choices: ['default', ...Object.keys(SORT_FIELDS)], help: 'default 保留服务端默认顺序' },
+    { name: 'order', default: 'default', choices: ['default', 'asc', 'desc'], help: '默认：姓名/主题升序，其余降序；显式方向须指定 --sort' },
+  ], columns: listColumns, func: runList });

package/clis/iwhalecloud/read.js

@@ -0,0 +1,25 @@
+import { cli } from '@sovovs/bycli/registry';
+import { ArgumentError, CommandExecutionError } from '@sovovs/bycli/errors';
+import { metadata, idArg, requiredId, connect, getMail, mailRow, listColumns, attachmentsOf } from './client.js';
+
+export async function runRead(page, args) {
+  const id = requiredId(args.emailId);
+  const bodyType = String(args['body-type'] ?? 'text');
+  if (!['text', 'html'].includes(bodyType)) throw new ArgumentError('body-type must be text or html');
+  await connect(page);
+  const item = await getMail(page, id, bodyType);
+  if (typeof item.Body?.Value !== 'string' || item.Body.IsTruncated === true) {
+    throw new CommandExecutionError('OWA did not return a complete mail body', 'Open the mail in Outlook to check content restrictions');
+  }
+  const recipients = entries => (entries ?? []).map(entry => {
+    const mailbox = entry.Mailbox ?? entry;
+    return { name: mailbox.Name ?? '', email: mailbox.EmailAddress ?? '' };
+  });
+  return [{ ...mailRow(item), to: recipients(item.ToRecipients), cc: recipients(item.CcRecipients), bcc: recipients(item.BccRecipients),
+    recipientCounts: item.RecipientCounts ?? {}, bodyType: item.Body?.BodyType ?? bodyType, body: item.Body?.Value ?? '',
+    attachments: attachmentsOf(item) }];
+}
+cli({ ...metadata, name: 'read', description: '读取浩鲸邮件完整正文、收件人和附件列表（不标记已读）',
+  example: 'bycli iwhalecloud read "<emailId>" -f yaml',
+  args: [idArg, { name: 'body-type', default: 'text', choices: ['text', 'html'], help: '正文格式' }],
+  columns: [...listColumns, 'to', 'cc', 'bcc', 'recipientCounts', 'bodyType', 'body', 'attachments'], func: runRead });

package/dist/src/browser/cdp.js

@@ -232,6 +232,14 @@ class CDPPage extends BasePage {
                 const maxMs = options?.settleMs ?? 1000;
                 await this.evaluate(waitForDomStableJs(maxMs, Math.min(500, maxMs)));
             }
+            try {
+                const current = await this.evaluate('window.location.href');
+                if (typeof current === 'string' && current)
+                    this._lastUrl = current;
+            }
+            catch {
+                // Retain the requested URL when the document is still unavailable.
+            }
         }
         finally {
             if (guard)

package/dist/src/browser/page.js

@@ -108,6 +108,16 @@ export class Page extends BasePage {
             this._page = result.page;
         }
         this._lastUrl = url;
+        const refreshUrl = async () => {
+            try {
+                const current = await this.evaluate('window.location.href');
+                if (typeof current === 'string' && current)
+                    this._lastUrl = current;
+            }
+            catch {
+                // Navigation may still be settling; retain the requested URL as fallback.
+            }
+        };
         // Inject stealth + settle in a single round-trip instead of two sequential exec calls.
         // Some security-sensitive editors reject runtime environment patches, so callers can
         // retain the normal DOM-settle behavior while opting out of stealth injection.
@@ -139,6 +149,7 @@ export class Page extends BasePage {
                         throw retryErr;
                 }
             }
+            await refreshUrl();
         }
         else if (useStealth) {
             // Even with waitUntil='none', still inject stealth (best-effort)
@@ -151,6 +162,7 @@ export class Page extends BasePage {
             catch {
                 // Non-fatal: stealth is best-effort
             }
+            await refreshUrl();
         }
     }
     /** Get the active page identity (targetId) */

package/extension/README.md

@@ -0,0 +1,26 @@
+# byCLI Browser Bridge Extension
+
+The extension connects Chrome tabs to the local byCLI daemon. It uses Chrome
+extension APIs only as a transport and browser-control layer for explicit CLI
+commands.
+
+## Permission Notes
+
+- `debugger`: sends CDP commands to byCLI-controlled or bound tabs.
+- `tabs` / `tabGroups`: manages the dedicated byCLI automation container and
+  reports selected tab metadata back to the CLI.
+- `cookies`: reads cookies for browser-backed adapters that need authenticated
+  fetches.
+- `downloads`: surfaces download lifecycle to `bycli browser wait download`.
+  The extension observes started / in-progress / completed / failed downloads so
+  the CLI can wait for a file triggered by an automation command. byCLI
+  filters by the command's filename/URL pattern and timeout, and does not modify,
+  redirect, or persist browser download history.
+
+Suggested Chrome Web Store justification for `downloads`:
+
+> This extension uses `chrome.downloads` to surface download lifecycle
+> (started / in-progress / completed / failed) to the byCLI command-line tool,
+> so agents can wait for downloads triggered during an automation workflow. The
+> command filters by a user-provided filename or URL pattern and timeout. We do
+> not modify, redirect, or persist user download history.