@d2c2d/crikket-sdk 1.0.0

package/README.md

@@ -0,0 +1,226 @@
+# @d2c2d/crikket-sdk
+
+Crikket 缺陷平台匿名 oRPC 客户端（Node.js ≥ 18，ESM）。
+
+## 安装
+
+```bash
+npm install @d2c2d/crikket-sdk
+```
+
+## 使用
+
+SDK 不读取 env 或配置文件；在脚本中自行读取 JSON 并传入参数。
+
+### 配置 `crikket.config.json`
+
+| 字段 | 说明 |
+|------|------|
+| `rpcBaseUrl` | Crikket RPC 根 URL，必填 |
+| `organizationId` | 组织 ID；`list` / `export` / `mark` 等方法需要 |
+
+```json
+{
+  "rpcBaseUrl": "http://localhost:9100",
+  "organizationId": "org_xxx"
+}
+```
+
+### 按 id 下载 — `download-bugs.mjs`
+
+```javascript
+// 用法: node download-bugs.mjs <bugId> [bugId...]
+// 示例: node download-bugs.mjs bug_1 bug_2
+// 说明: 匿名下载，无需 organizationId；输出到 ./out-bugs/{id}.md 等
+
+import { mkdirSync, readFileSync } from "node:fs";
+import { CrikketClient } from "@d2c2d/crikket-sdk";
+
+const cfg = JSON.parse(readFileSync("./crikket.config.json", "utf8"));
+const ids = process.argv.slice(2).filter((s) => s.trim());
+if (ids.length === 0) {
+  console.error("用法: node download-bugs.mjs <bugId> [bugId...]");
+  process.exit(1);
+}
+
+const outDir = "./out-bugs";
+mkdirSync(outDir, { recursive: true });
+
+const client = new CrikketClient({ baseUrl: cfg.rpcBaseUrl });
+const results = await client.downloadBugs({ ids, outDir });
+
+for (const row of results) {
+  console.log(row.ok ? `✓ ${row.id}` : `✗ ${row.id}: ${row.error}`);
+}
+if (results.some((r) => !r.ok)) process.exit(1);
+```
+
+### 导出 open bug — `export-open-bugs.mjs`
+
+```javascript
+// 用法: node export-open-bugs.mjs <search> [outDir]
+// 示例: node export-open-bugs.mjs http://localhost:3003 ./out-export
+// 说明: 按 search 筛选 open bug 并下载；实际写入 {outDir}/{search slug}/
+
+import { mkdirSync, readFileSync } from "node:fs";
+import { CrikketClient } from "@d2c2d/crikket-sdk";
+
+const cfg = JSON.parse(readFileSync("./crikket.config.json", "utf8"));
+const search = process.argv[2]?.trim();
+const outDir = process.argv[3]?.trim() ?? "./out-export";
+if (!search) {
+  console.error("用法: node export-open-bugs.mjs <search> [outDir]");
+  process.exit(1);
+}
+
+mkdirSync(outDir, { recursive: true });
+
+const client = new CrikketClient({
+  baseUrl: cfg.rpcBaseUrl,
+  organizationId: cfg.organizationId, // export 需要 org
+});
+
+const { ids, outDir: targetDir, downloadResults } = await client.exportOpenBugs({
+  search,
+  outDir,
+});
+
+console.log(`open=${ids.length} → ${targetDir}`);
+for (const row of downloadResults) {
+  console.log(row.ok ? `✓ ${row.id}` : `✗ ${row.id}: ${row.error}`);
+}
+if (downloadResults.some((r) => !r.ok)) process.exit(1);
+```
+
+### 批量 mark resolved — `mark-resolved.mjs`
+
+```javascript
+// 用法: node mark-resolved.mjs <bugId> [bugId...]
+// 示例: node mark-resolved.mjs bug_1 bug_2
+// 说明: 批量将 status 改为 resolved；markInProgress / markOpen 换方法名即可
+
+import { readFileSync } from "node:fs";
+import { CrikketClient } from "@d2c2d/crikket-sdk";
+
+const cfg = JSON.parse(readFileSync("./crikket.config.json", "utf8"));
+const ids = process.argv.slice(2).filter((s) => s.trim());
+if (ids.length === 0) {
+  console.error("用法: node mark-resolved.mjs <bugId> [bugId...]");
+  process.exit(1);
+}
+
+const client = new CrikketClient({
+  baseUrl: cfg.rpcBaseUrl,
+  organizationId: cfg.organizationId, // bulk 改 status 需要 org
+});
+
+const result = await client.markResolved({ ids });
+console.log(`updated ${result.updatedCount} bug(s): ${result.ids?.join(", ") ?? ""}`);
+```
+
+## API
+
+### `CrikketClient`
+
+**构造**
+
+```typescript
+new CrikketClient(opts: {
+  baseUrl: string;           // 非空
+  organizationId?: string;
+  fetch?: typeof fetch;
+})
+```
+
+**方法**
+
+| 方法 | 说明 | `organizationId` |
+|------|------|------------------|
+| `getBugById(id)` | 单条 bug 详情 | 否 |
+| `getDebuggerEvents(id)` | 调试事件 | 否 |
+| `downloadBugs({ ids, outDir })` | 下载 Markdown + sidecar | 否 |
+| `listByOrganizationId(input?)` | 分页列表 | 构造或 `input.organizationId` |
+| `getDashboardStats(input?)` | 仪表盘统计 | 构造或 `input.organizationId` |
+| `exportOpenBugs({ search, outDir, organizationId? })` | 列出 open 并下载 | 构造或参数 |
+| `updateBulkStatus({ ids, status, organizationId? })` | 通用批量改 status | 构造或参数 |
+| `markInProgress({ ids, organizationId? })` | → `in_progress` | 构造或参数 |
+| `markResolved({ ids, organizationId? })` | → `resolved` | 构造或参数 |
+| `markOpen({ ids, organizationId? })` | → `open` | 构造或参数 |
+
+缺少 `organizationId` 时，需要 org 的方法会在发请求前抛出错误。SDK 不校验 bug 是否属于该 org。
+
+**`listByOrganizationId` 参数**
+
+```typescript
+{
+  organizationId?: string;
+  page?: number;        // 默认 1
+  perPage?: number;     // 默认 12
+  search?: string;
+  sort?: string;        // 默认 "newest"
+  statuses?: BugStatus[];
+  priorities?: string[];
+}
+```
+
+**`downloadBugs` 返回值** — `DownloadResult[]`：
+
+```typescript
+{
+  id: string;
+  ok: boolean;
+  error?: string;
+  paths?: {
+    md: string;
+    reportJson: string;
+    debuggerJson: string;
+    networkJson?: string;
+  };
+}
+```
+
+**`exportOpenBugs` 返回值** — `ExportOpenResult`：
+
+```typescript
+{
+  ids: string[];
+  outDir: string;              // 实际写入目录（含 search slug）
+  downloadResults: DownloadResult[];
+}
+```
+
+### 主入口辅助函数
+
+| 导出 | 说明 |
+|------|------|
+| `uniqueBugIds(ids)` | trim 并去重 |
+| `validateBugIdList(ids)` | 校验非空、≤200 个 |
+| `assertBulkUpdatedCount(result, expected)` | 校验 `updatedCount` |
+| `updateBulkStatus({ baseUrl, organizationId, bugIds, status, fetchImpl? })` | 无 client 实例的 bulk 调用 |
+| `searchNormalized(search)` | 将 search 转为安全目录名 slug |
+
+### `@d2c2d/crikket-sdk/rpc`
+
+| 导出 | 说明 |
+|------|------|
+| `rpcPost(baseUrl, procedurePath, jsonInput, fetchImpl?)` | 原始 oRPC POST |
+| `unwrapProcedureResult(body)` | 解析 tRPC/oRPC 响应体 |
+| `RpcError` | HTTP 或 RPC 错误 |
+
+### 类型
+
+`BugStatus`、`BulkUpdateResult`、`CrikketClientOptions`、`DashboardStatsInput`、`DownloadResult`、`ExportOpenResult`、`ListByOrganizationIdInput`、`ListPage`
+
+## 输出目录
+
+**`downloadBugs`** — 扁平写入 `{outDir}/`：
+
+```
+{id}.md
+{id}.report.json
+{id}.debugger.json
+{id}.network.json              # 有 networkRequests 时
+{id}.attachments/*.picked_dom.html
+```
+
+**`exportOpenBugs`** — 写入 `{outDir}/{searchNormalized(search)}/`，文件名同上。

package/dist/chunk-VBFPP5MD.js

@@ -0,0 +1,71 @@
+// src/rpc.ts
+function unwrapProcedureResult(body) {
+  if (body === null || body === void 0) return body;
+  if (typeof body !== "object") return body;
+  const rec = body;
+  if ("json" in rec && rec.json !== void 0) {
+    return rec.json;
+  }
+  const nested = rec.result;
+  if (nested && typeof nested === "object") {
+    const r = nested;
+    const data = r.data;
+    if (data && typeof data === "object") {
+      const d = data;
+      if ("json" in d) return d.json;
+    }
+  }
+  if (Array.isArray(body) && body.length > 0) {
+    return unwrapProcedureResult(body[0]);
+  }
+  return body;
+}
+var RpcError = class extends Error {
+  status;
+  statusText;
+  bodyPreview;
+  constructor(status, statusText, bodyPreview) {
+    super(`RPC ${status} ${statusText}
+${bodyPreview}`);
+    this.name = "RpcError";
+    this.status = status;
+    this.statusText = statusText;
+    this.bodyPreview = bodyPreview;
+  }
+};
+async function rpcPost(rpcBaseUrl, procedurePath, jsonInput, fetchImpl) {
+  const base = rpcBaseUrl.replace(/\/+$/, "");
+  const url = `${base}/rpc/${procedurePath}`;
+  const doFetch = fetchImpl ?? globalThis.fetch;
+  const res = await doFetch(url, {
+    method: "POST",
+    headers: {
+      Accept: "*/*",
+      "content-type": "application/json"
+    },
+    body: JSON.stringify({ json: jsonInput, meta: [] })
+  });
+  const text = await res.text();
+  let parsed;
+  try {
+    parsed = text ? JSON.parse(text) : null;
+  } catch {
+    throw new RpcError(res.status, res.statusText, text.slice(0, 2e3));
+  }
+  if (!res.ok) {
+    const preview = typeof text === "string" ? text.slice(0, 2e3) : String(parsed).slice(0, 2e3);
+    throw new RpcError(res.status, res.statusText, preview);
+  }
+  if (parsed && typeof parsed === "object" && "error" in parsed) {
+    const err = parsed.error;
+    const msg = err && typeof err === "object" && err !== null && "message" in err ? String(err.message) : JSON.stringify(err);
+    throw new RpcError(res.status, "tRPC error", msg.slice(0, 2e3));
+  }
+  return unwrapProcedureResult(parsed);
+}
+
+export {
+  unwrapProcedureResult,
+  RpcError,
+  rpcPost
+};

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+export { RpcError, rpcPost, unwrapProcedureResult } from './rpc.js';
+
+type BugStatus = "open" | "in_progress" | "resolved" | "closed";
+type BulkUpdateResult = {
+    updatedCount?: number;
+    ids?: string[];
+};
+type ListByOrganizationIdInput = {
+    organizationId?: string;
+    page?: number;
+    perPage?: number;
+    search?: string;
+    sort?: string;
+    statuses?: BugStatus[];
+    priorities?: string[];
+};
+type ListPage = Record<string, unknown> & {
+    items?: unknown[];
+    pagination?: Record<string, unknown>;
+};
+type DashboardStatsInput = {
+    organizationId?: string;
+    search?: string;
+    statuses?: BugStatus[];
+    priorities?: string[];
+};
+type DownloadResult = {
+    id: string;
+    ok: boolean;
+    error?: string;
+    paths?: {
+        md: string;
+        reportJson: string;
+        debuggerJson: string;
+        networkJson?: string;
+    };
+};
+type ExportOpenResult = {
+    ids: string[];
+    outDir: string;
+    downloadResults: DownloadResult[];
+};
+type CrikketClientOptions = {
+    baseUrl: string;
+    organizationId?: string;
+    fetch?: typeof fetch;
+};
+
+declare class CrikketClient {
+    private readonly baseUrl;
+    private readonly organizationId?;
+    private readonly fetchImpl;
+    constructor(opts: CrikketClientOptions);
+    private resolveOrganizationId;
+    private rpc;
+    listByOrganizationId(input: ListByOrganizationIdInput): Promise<ListPage>;
+    getDashboardStats(input?: DashboardStatsInput): Promise<unknown>;
+    getBugById(id: string): Promise<unknown>;
+    getDebuggerEvents(id: string): Promise<unknown>;
+    updateBulkStatus(input: {
+        organizationId?: string;
+        ids: string[];
+        status: BugStatus;
+    }): Promise<BulkUpdateResult>;
+    markInProgress(input: {
+        ids: string[];
+        organizationId?: string;
+    }): Promise<BulkUpdateResult>;
+    markResolved(input: {
+        ids: string[];
+        organizationId?: string;
+    }): Promise<BulkUpdateResult>;
+    markOpen(input: {
+        ids: string[];
+        organizationId?: string;
+    }): Promise<BulkUpdateResult>;
+    downloadBugs(input: {
+        ids: string[];
+        outDir: string;
+    }): Promise<DownloadResult[]>;
+    exportOpenBugs(input: {
+        search: string;
+        outDir: string;
+        organizationId?: string;
+    }): Promise<ExportOpenResult>;
+    private listAllOpenIds;
+    private downloadOneBug;
+}
+
+declare function uniqueBugIds(ids: string[]): string[];
+declare function validateBugIdList(bugIds: string[]): string[];
+declare function assertBulkUpdatedCount(result: BulkUpdateResult, expected: number): BulkUpdateResult;
+declare function updateBulkStatus(args: {
+    baseUrl: string;
+    organizationId: string;
+    bugIds: string[];
+    status: BugStatus;
+    fetchImpl?: typeof fetch;
+}): Promise<BulkUpdateResult>;
+
+/**
+ * 将 trim 后的 search 规范为安全目录名（单表、可文档化）。
+ * 规则：若能解析为 URL，则 `{scheme}_{hostname}_{port?}`，端口仅在非 80/443 时追加；
+ * 否则对字符串做安全字符替换。
+ */
+declare function searchNormalized(searchTrimmed: string): string;
+
+export { type BugStatus, type BulkUpdateResult, CrikketClient, type CrikketClientOptions, type DashboardStatsInput, type DownloadResult, type ExportOpenResult, type ListByOrganizationIdInput, type ListPage, assertBulkUpdatedCount, searchNormalized, uniqueBugIds, updateBulkStatus, validateBugIdList };

package/dist/index.js

@@ -0,0 +1,527 @@
+import {
+  RpcError,
+  rpcPost,
+  unwrapProcedureResult
+} from "./chunk-VBFPP5MD.js";
+
+// src/client.ts
+import { mkdirSync as mkdirSync3 } from "fs";
+import { join as join3 } from "path";
+
+// src/bulk.ts
+function uniqueBugIds(ids) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const raw of ids) {
+    const id = raw.trim();
+    if (!id) continue;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return out;
+}
+function validateBugIdList(bugIds) {
+  const unique = uniqueBugIds(bugIds);
+  if (unique.length === 0) {
+    throw new Error("\u81F3\u5C11\u9700\u8981\u4E00\u4E2A bug id");
+  }
+  if (unique.length > 200) {
+    throw new Error(`bug id \u6700\u591A 200 \u4E2A\uFF08\u5F53\u524D ${unique.length}\uFF09`);
+  }
+  return unique;
+}
+function assertBulkUpdatedCount(result, expected) {
+  const updatedCount = typeof result.updatedCount === "number" ? result.updatedCount : Number.NaN;
+  if (updatedCount !== expected) {
+    throw new Error(
+      `updatedCount=${String(result.updatedCount)}\uFF0C\u671F\u671B ${expected}\uFF1B\u54CD\u5E94: ${JSON.stringify(result).slice(0, 500)}`
+    );
+  }
+  return result;
+}
+async function updateBulkStatus(args) {
+  const bugIds = validateBugIdList(args.bugIds);
+  let raw;
+  try {
+    raw = await rpcPost(
+      args.baseUrl,
+      "bugReport/updateBulkByOrganizationId",
+      {
+        organizationId: args.organizationId,
+        ids: bugIds,
+        status: args.status
+      },
+      args.fetchImpl
+    );
+  } catch (e) {
+    if (e instanceof RpcError) {
+      throw new Error(e.message);
+    }
+    throw e;
+  }
+  if (!raw || typeof raw !== "object") {
+    throw new Error(`bulk \u8FD4\u56DE\u975E\u5BF9\u8C61: ${JSON.stringify(raw).slice(0, 500)}`);
+  }
+  return assertBulkUpdatedCount(raw, bugIds.length);
+}
+
+// src/export/attachments.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+function isPickedDomHtmlAttachment(att) {
+  if (!att || typeof att !== "object") return false;
+  const o = att;
+  if (o.kind !== "picked_dom") return false;
+  const ct = typeof o.contentType === "string" ? o.contentType : "";
+  return ct.toLowerCase().includes("html");
+}
+function listPickedDomHtmlAttachments(report) {
+  if (!report || typeof report !== "object") return [];
+  const attachments = report.attachments;
+  if (!Array.isArray(attachments)) return [];
+  return attachments.filter(isPickedDomHtmlAttachment).map((a) => a).sort((a, b) => {
+    const ao = typeof a.sortOrder === "number" ? a.sortOrder : 0;
+    const bo = typeof b.sortOrder === "number" ? b.sortOrder : 0;
+    return ao - bo;
+  });
+}
+function pickedDomFileName(attachmentId) {
+  return `${attachmentId}.picked_dom.html`;
+}
+function pickedDomRelPath(bugId, attachmentId) {
+  return `./${bugId}.attachments/${pickedDomFileName(attachmentId)}`;
+}
+async function downloadPickedDomAttachments(report, outDir, bugId, fetchImpl) {
+  const picked = listPickedDomHtmlAttachments(report);
+  if (picked.length === 0) return [];
+  const attachDir = join(outDir, `${bugId}.attachments`);
+  mkdirSync(attachDir, { recursive: true });
+  const doFetch = fetchImpl ?? globalThis.fetch;
+  const rows = [];
+  for (const att of picked) {
+    const attachmentId = typeof att.id === "string" ? att.id : "";
+    const sortOrder = typeof att.sortOrder === "number" ? att.sortOrder : 0;
+    const contentType = typeof att.contentType === "string" ? att.contentType : "";
+    const sizeBytes = typeof att.sizeBytes === "number" ? att.sizeBytes : 0;
+    const url = typeof att.url === "string" ? att.url : "";
+    const base = {
+      id: attachmentId,
+      sortOrder,
+      contentType,
+      sizeBytes,
+      localRel: null
+    };
+    if (!attachmentId || !url) {
+      const msg = "missing attachment id or url";
+      console.error(`[crikket-sdk] ${bugId} picked_dom: ${msg}`);
+      rows.push({ ...base, downloadError: msg });
+      continue;
+    }
+    const filePath = join(attachDir, pickedDomFileName(attachmentId));
+    const localRel = pickedDomRelPath(bugId, attachmentId);
+    try {
+      const res = await doFetch(url);
+      if (!res.ok) {
+        throw new Error(`HTTP ${res.status} ${res.statusText}`);
+      }
+      const buf = Buffer.from(await res.arrayBuffer());
+      writeFileSync(filePath, buf);
+      rows.push({ ...base, localRel });
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      console.error(`[crikket-sdk] ${bugId} picked_dom ${attachmentId}: ${msg}`);
+      rows.push({ ...base, downloadError: msg });
+    }
+  }
+  return rows;
+}
+
+// src/export/normalizeSearch.ts
+function searchNormalized(searchTrimmed) {
+  if (!searchTrimmed) return "empty_search";
+  let urlString = searchTrimmed;
+  if (!/^[a-zA-Z][a-zA-Z+\-.]*:\/\//.test(urlString)) {
+    urlString = `http://${urlString}`;
+  }
+  try {
+    const u = new URL(urlString);
+    const scheme = u.protocol.replace(/:$/, "") || "http";
+    const host = u.hostname || "unknown";
+    const port = u.port;
+    const defaultPort = scheme === "https" ? "443" : scheme === "http" ? "80" : "";
+    const includePort = port && port !== defaultPort;
+    const raw = includePort ? `${scheme}_${host}_${port}` : `${scheme}_${host}`;
+    return sanitizeDirName(raw);
+  } catch {
+    return sanitizeDirName(searchTrimmed);
+  }
+}
+function sanitizeDirName(raw) {
+  const s = raw.replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/_+/g, "_").replace(/^\.+|\.+$/g, "").replace(/^_|_$/g, "");
+  return s || "export";
+}
+
+// src/export/writeArtifacts.ts
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join2 } from "path";
+
+// src/export/render.ts
+function escCell(s) {
+  if (s === null || s === void 0) return "";
+  return String(s).replace(/\|/g, "\\|").replace(/\r\n/g, "\n").replace(/\n/g, "<br>");
+}
+function pathnameFromBugUrl(urlStr) {
+  if (!urlStr.trim()) return "";
+  try {
+    return new URL(urlStr).pathname || "";
+  } catch {
+    return "";
+  }
+}
+function pickAttr(attrs, targetAttrs, key) {
+  const a = attrs?.[key];
+  if (typeof a === "string" && a.trim()) return a;
+  const t = targetAttrs?.[key];
+  return typeof t === "string" ? t : "";
+}
+function navigationSummary(meta) {
+  if (!meta) return "";
+  const path = typeof meta.path === "string" ? meta.path : "";
+  const url = typeof meta.url === "string" ? meta.url : "";
+  const title = typeof meta.title === "string" ? meta.title : "";
+  const parts = [path && `path=${path}`, url && url !== path && `url=${url}`, title && `title=${title}`].filter(
+    Boolean
+  );
+  return parts.join(" \xB7 ");
+}
+function actionsTable(actions) {
+  if (!Array.isArray(actions) || actions.length === 0) {
+    return "_\uFF08\u65E0 actions \u6216\u5C1A\u672A\u91C7\u96C6\uFF09_\n";
+  }
+  const lines = [
+    "| # | type | target | timestamp | navigation\uFF08path / url / title\uFF09 | text\uFF08innerText\uFF09 | targetText | id | aria-label | data-openreplay-label | class |",
+    "|---|------|--------|-----------|--------------------------------------|-------------------|------------|----|-----------|------------------------|-------|"
+  ];
+  actions.forEach((a, idx) => {
+    if (!a || typeof a !== "object") return;
+    const o = a;
+    const type = escCell(o.type);
+    const target = escCell(o.target);
+    const ts = escCell(o.timestamp);
+    const meta = o.metadata && typeof o.metadata === "object" ? o.metadata : null;
+    const text = escCell(meta?.text);
+    const targetText = escCell(meta?.targetText);
+    const attrs = meta?.attributes && typeof meta.attributes === "object" ? meta.attributes : null;
+    const targetAttrs = meta?.targetAttributes && typeof meta.targetAttributes === "object" ? meta.targetAttributes : null;
+    const nav = o.type === "navigation" && meta ? escCell(navigationSummary(meta)) : "";
+    const id = escCell(pickAttr(attrs, targetAttrs, "id"));
+    const aria = escCell(pickAttr(attrs, targetAttrs, "aria-label"));
+    const label = escCell(pickAttr(attrs, targetAttrs, "data-openreplay-label"));
+    const cls = escCell(pickAttr(attrs, targetAttrs, "class"));
+    lines.push(
+      `| ${idx + 1} | ${type} | ${target} | ${ts} | ${nav} | ${text} | ${targetText} | ${id} | ${aria} | ${label} | ${cls} |`
+    );
+  });
+  return lines.join("\n") + "\n";
+}
+function pickedDomSection(id, rows, reportRel) {
+  if (rows.length === 0) return "";
+  const tableLines = [
+    "| sortOrder | attachment id | \u672C\u5730 HTML | contentType | sizeBytes |",
+    "|-----------|---------------|-----------|-------------|-----------|"
+  ];
+  for (const row of rows) {
+    const htmlCell = row.localRel ? `[\`${row.localRel.replace(/^\.\//, "")}\`](${row.localRel})` : escCell(row.downloadError ? `\u4E0B\u8F7D\u5931\u8D25\uFF1A${row.downloadError}` : "\u4E0B\u8F7D\u5931\u8D25");
+    tableLines.push(
+      `| ${row.sortOrder} | \`${escCell(row.id)}\` | ${htmlCell} | ${escCell(row.contentType)} | ${row.sizeBytes} |`
+    );
+  }
+  return `## \u7528\u6237\u6807\u6CE8 DOM\uFF08attachments / picked_dom\uFF09
+
+\u4EE5\u4E0B HTML \u4E3A**\u7528\u6237\u5728\u63D0\u4EA4\u7F3A\u9677\u65F6\u6846\u9009/\u6807\u6CE8\u7684\u9875\u9762\u8282\u70B9 DOM \u7247\u6BB5**\uFF0C\u7528\u4E8E\u5728\u4E1A\u52A1\u4EE3\u7801\u5E93\u4E2D\u5BF9\u7167 DOM \u7ED3\u6784\u3001class \u4E0E\u53EF\u89C1\u6587\u6848\u3002
+
+${tableLines.join("\n")}
+
+> \u5B8C\u6574 \`attachments\` \u5143\u6570\u636E\u89C1 [\`${reportRel.replace(/^\.\//, "")}\`](${reportRel})\u3002
+
+`;
+}
+function renderBugMarkdown(id, report, rel, actionsForTable, pickedDomRows = []) {
+  const r = report && typeof report === "object" ? report : {};
+  const url = typeof r.url === "string" ? r.url : "";
+  const description = typeof r.description === "string" ? r.description : "";
+  const status = typeof r.status === "string" ? r.status : "";
+  const submissionStatus = typeof r.submissionStatus === "string" ? r.submissionStatus : "";
+  const debuggerIngestionStatus = typeof r.debuggerIngestionStatus === "string" ? r.debuggerIngestionStatus : "";
+  const pathFromUrl = pathnameFromBugUrl(url);
+  const attachmentUrl = typeof r.attachmentUrl === "string" ? r.attachmentUrl : "";
+  const attachmentType = typeof r.attachmentType === "string" ? r.attachmentType : "";
+  const networkLine = rel.networkRel ? `- **networkRequests**\uFF1A[\`${rel.networkRel.replace(/^\.\//, "")}\`](${rel.networkRel})\uFF08\u539F\u59CB\u8BF7\u6C42/\u54CD\u5E94\u4F53\uFF0C\u4F53\u79EF\u53EF\u80FD\u8F83\u5927\uFF09
+` : "";
+  const pickedDomBlock = pickedDomSection(id, pickedDomRows, rel.reportRel);
+  return `# Bug report \`${id}\`
+
+## Agent \u6307\u5F15\uFF08\u4EE3\u7801\u5E93\u68C0\u7D22\uFF09
+
+- **\u52FF\u5C06\u6587\u6863/\u7A97\u53E3\u6807\u9898**\uFF08\u5982 \`getById.title\`\u3001\`metadata.pageTitle\`\uFF09\u4F5C\u4E3A\u552F\u4E00\u68C0\u7D22\u5173\u952E\u8BCD\uFF1B\u5B83\u4EEC\u4F1A\u968F\u8DEF\u7531\u4E0E\u4EA7\u54C1\u6587\u6848\u53D8\u5316\u3002
+- **\u4F18\u5148\u5728\u4EE3\u7801\u5E93\u4E2D\u641C\u7D22**\uFF1A\`url\`\u3001\u8DEF\u7531 path\u3001**\u95EE\u9898\u63CF\u8FF0\uFF08description\uFF09**\u3001\u4E0B\u65B9 **\u7528\u6237\u6807\u6CE8 DOM\uFF08picked_dom\uFF09** HTML\u3001\`data-openreplay-label\`\u3001\u7A33\u5B9A \`id\`\u3001\`aria-label\`\u3001\`class\`\uFF08\u542B Tailwind \u539F\u5B50\u7C7B\uFF09\u3001\`targetText\`\uFF08\u5E38\u6BD4 innerText \u66F4\u5E72\u51C0\uFF09\u3001\u4EE5\u53CA **\u590D\u73B0\u6B65\u9AA4\u8868** \u4E2D\u7684\u53EF\u89C1\u6587\u6848\u7247\u6BB5\u3002
+
+## \u73AF\u5883\u4E0E\u8DEF\u7531
+
+| \u5B57\u6BB5 | \u503C |
+|------|-----|
+| id | \`${escCell(id)}\` |
+| url | \`${escCell(url)}\` |
+| path\uFF08\u4ECE url \u89E3\u6790\uFF0C\u4FBF\u4E8E\u641C\u8DEF\u7531\uFF09 | \`${escCell(pathFromUrl)}\` |
+| status | ${escCell(status)} |
+| submissionStatus | ${escCell(submissionStatus)} |
+| debuggerIngestionStatus | ${escCell(debuggerIngestionStatus)} |
+| attachmentUrl | ${escCell(attachmentUrl)} |
+| attachmentType | ${escCell(attachmentType)} |
+
+## \u95EE\u9898\u63CF\u8FF0\uFF08description\uFF09
+
+${description ? description : "_\uFF08\u7A7A\uFF09_"}
+
+## \u590D\u73B0\u6B65\u9AA4\u7D22\u5F15\uFF08\u6765\u81EA debugger actions\uFF09
+
+${actionsTable(Array.isArray(actionsForTable) ? actionsForTable : [])}
+
+${pickedDomBlock}> \u5B8C\u6574 \`actions\` / \`logs\` \u7B49\u89C1 sidecar\uFF1A[\`${rel.debuggerRel.replace(/^\.\//, "")}\`](${rel.debuggerRel})
+
+## \u539F\u59CB\u62A5\u544A JSON\uFF08getById\uFF09
+
+\u5B8C\u6574\u5B57\u6BB5\uFF08\u4E0E RPC \u5BF9\u9F50\uFF09\u89C1\uFF1A[\`${rel.reportRel.replace(/^\.\//, "")}\`](${rel.reportRel})
+
+${networkLine}
+`;
+}
+function extractNetworkRequests(debuggerPayload) {
+  if (!debuggerPayload || typeof debuggerPayload !== "object") return null;
+  const d = debuggerPayload;
+  if ("networkRequests" in d) return d.networkRequests;
+  const json = d.json;
+  if (json && typeof json === "object" && "networkRequests" in json) {
+    return json.networkRequests;
+  }
+  return null;
+}
+function extractActions(debuggerPayload) {
+  if (!debuggerPayload || typeof debuggerPayload !== "object") return [];
+  const d = debuggerPayload;
+  if (Array.isArray(d.actions)) return d.actions;
+  const json = d.json;
+  if (json && typeof json === "object") {
+    const j = json;
+    if (Array.isArray(j.actions)) return j.actions;
+  }
+  return [];
+}
+
+// src/export/writeArtifacts.ts
+function shouldWriteNetworkSidecar(net) {
+  if (net === null || net === void 0) return false;
+  if (Array.isArray(net)) return net.length > 0;
+  if (typeof net === "object") return Object.keys(net).length > 0;
+  return true;
+}
+function writeBugArtifacts(outDir, id, report, debuggerPayload, pickedDomRows = []) {
+  mkdirSync2(outDir, { recursive: true });
+  const reportPath = join2(outDir, `${id}.report.json`);
+  const debuggerPath = join2(outDir, `${id}.debugger.json`);
+  writeFileSync2(reportPath, JSON.stringify(report, null, 2), "utf8");
+  writeFileSync2(debuggerPath, JSON.stringify(debuggerPayload, null, 2), "utf8");
+  const net = extractNetworkRequests(debuggerPayload);
+  let networkRel = null;
+  let networkPath;
+  if (shouldWriteNetworkSidecar(net)) {
+    networkPath = join2(outDir, `${id}.network.json`);
+    writeFileSync2(networkPath, JSON.stringify(net, null, 2), "utf8");
+    networkRel = `./${id}.network.json`;
+  }
+  const actions = extractActions(debuggerPayload);
+  const md = renderBugMarkdown(
+    id,
+    report,
+    {
+      reportRel: `./${id}.report.json`,
+      debuggerRel: `./${id}.debugger.json`,
+      networkRel
+    },
+    actions,
+    pickedDomRows
+  );
+  const mdPath = join2(outDir, `${id}.md`);
+  writeFileSync2(mdPath, md, "utf8");
+  return {
+    md: mdPath,
+    reportJson: reportPath,
+    debuggerJson: debuggerPath,
+    networkJson: networkPath
+  };
+}
+
+// src/client.ts
+var CrikketClient = class {
+  baseUrl;
+  organizationId;
+  fetchImpl;
+  constructor(opts) {
+    const baseUrl = opts.baseUrl?.trim();
+    if (!baseUrl) {
+      throw new Error("baseUrl \u4E0D\u80FD\u4E3A\u7A7A");
+    }
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.organizationId = opts.organizationId?.trim() || void 0;
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+  }
+  resolveOrganizationId(input) {
+    const org = input?.trim() || this.organizationId;
+    if (!org) {
+      throw new Error("organizationId \u672A\u63D0\u4F9B\uFF08\u6784\u9020\u53C2\u6570\u6216\u65B9\u6CD5\u53C2\u6570\uFF09");
+    }
+    return org;
+  }
+  async rpc(procedurePath, jsonInput) {
+    return rpcPost(this.baseUrl, procedurePath, jsonInput, this.fetchImpl);
+  }
+  async listByOrganizationId(input) {
+    const organizationId = this.resolveOrganizationId(input.organizationId);
+    const raw = await this.rpc("bugReport/listByOrganizationId", {
+      organizationId,
+      page: input.page ?? 1,
+      perPage: input.perPage ?? 12,
+      search: input.search,
+      sort: input.sort ?? "newest",
+      statuses: input.statuses,
+      priorities: input.priorities
+    });
+    if (!raw || typeof raw !== "object") {
+      throw new Error(`list \u8FD4\u56DE\u975E\u5BF9\u8C61: ${JSON.stringify(raw).slice(0, 500)}`);
+    }
+    return raw;
+  }
+  async getDashboardStats(input = {}) {
+    const organizationId = this.resolveOrganizationId(input.organizationId);
+    return this.rpc("bugReport/getDashboardStatsByOrganizationId", {
+      organizationId,
+      search: input.search,
+      statuses: input.statuses,
+      priorities: input.priorities
+    });
+  }
+  async getBugById(id) {
+    const trimmed = id.trim();
+    if (!trimmed) throw new Error("id \u4E0D\u80FD\u4E3A\u7A7A");
+    return this.rpc("bugReport/getByIdUnauthenticated", { id: trimmed });
+  }
+  async getDebuggerEvents(id) {
+    const trimmed = id.trim();
+    if (!trimmed) throw new Error("id \u4E0D\u80FD\u4E3A\u7A7A");
+    return this.rpc("bugReport/getDebuggerEventsUnauthenticated", { id: trimmed });
+  }
+  async updateBulkStatus(input) {
+    return updateBulkStatus({
+      baseUrl: this.baseUrl,
+      organizationId: this.resolveOrganizationId(input.organizationId),
+      bugIds: input.ids,
+      status: input.status,
+      fetchImpl: this.fetchImpl
+    });
+  }
+  async markInProgress(input) {
+    return this.updateBulkStatus({ ...input, status: "in_progress" });
+  }
+  async markResolved(input) {
+    return this.updateBulkStatus({ ...input, status: "resolved" });
+  }
+  async markOpen(input) {
+    return this.updateBulkStatus({ ...input, status: "open" });
+  }
+  async downloadBugs(input) {
+    const outDir = input.outDir;
+    mkdirSync3(outDir, { recursive: true });
+    const results = [];
+    for (const rawId of input.ids) {
+      const id = rawId.trim();
+      if (!id) continue;
+      results.push(await this.downloadOneBug(outDir, id));
+    }
+    return results;
+  }
+  async exportOpenBugs(input) {
+    const search = input.search.trim();
+    if (!search) {
+      throw new Error("search \u4E0D\u80FD\u4E3A\u7A7A\uFF08trim \u540E\uFF09");
+    }
+    const organizationId = this.resolveOrganizationId(input.organizationId);
+    const targetDir = join3(input.outDir, searchNormalized(search));
+    mkdirSync3(targetDir, { recursive: true });
+    const ids = await this.listAllOpenIds(organizationId, search);
+    const downloadResults = [];
+    for (const id of ids) {
+      downloadResults.push(await this.downloadOneBug(targetDir, id));
+    }
+    return { ids, outDir: targetDir, downloadResults };
+  }
+  async listAllOpenIds(organizationId, searchTrimmed) {
+    const ids = [];
+    const seen = /* @__PURE__ */ new Set();
+    let page = 1;
+    const perPage = 50;
+    while (true) {
+      const data = await this.listByOrganizationId({
+        organizationId,
+        page,
+        perPage,
+        search: searchTrimmed,
+        sort: "newest",
+        statuses: ["open"]
+      });
+      const items = Array.isArray(data.items) ? data.items : [];
+      for (const it of items) {
+        if (it && typeof it === "object" && typeof it.id === "string") {
+          const id = it.id;
+          if (!seen.has(id)) {
+            seen.add(id);
+            ids.push(id);
+          }
+        }
+      }
+      const pagination = data.pagination && typeof data.pagination === "object" ? data.pagination : null;
+      const hasNext = pagination && pagination.hasNextPage === true;
+      if (!hasNext) break;
+      page += 1;
+    }
+    return ids;
+  }
+  async downloadOneBug(outDir, id) {
+    try {
+      const report = await this.getBugById(id);
+      const dbg = await this.getDebuggerEvents(id);
+      const pickedDomRows = await downloadPickedDomAttachments(
+        report,
+        outDir,
+        id,
+        this.fetchImpl
+      );
+      const paths = writeBugArtifacts(outDir, id, report, dbg, pickedDomRows);
+      return { id, ok: true, paths };
+    } catch (e) {
+      const message = e instanceof RpcError ? e.message : e instanceof Error ? e.message : String(e);
+      return { id, ok: false, error: message };
+    }
+  }
+};
+export {
+  CrikketClient,
+  RpcError,
+  assertBulkUpdatedCount,
+  rpcPost,
+  searchNormalized,
+  uniqueBugIds,
+  unwrapProcedureResult,
+  updateBulkStatus,
+  validateBugIdList
+};

package/dist/rpc.d.ts

@@ -0,0 +1,11 @@
+/** 解析 tRPC / oRPC HTTP 常见响应形态，取出 procedure 的 data.json。 */
+declare function unwrapProcedureResult(body: unknown): unknown;
+declare class RpcError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly bodyPreview: string;
+    constructor(status: number, statusText: string, bodyPreview: string);
+}
+declare function rpcPost(rpcBaseUrl: string, procedurePath: string, jsonInput: Record<string, unknown>, fetchImpl?: typeof fetch): Promise<unknown>;
+
+export { RpcError, rpcPost, unwrapProcedureResult };

package/dist/rpc.js

@@ -0,0 +1,10 @@
+import {
+  RpcError,
+  rpcPost,
+  unwrapProcedureResult
+} from "./chunk-VBFPP5MD.js";
+export {
+  RpcError,
+  rpcPost,
+  unwrapProcedureResult
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@d2c2d/crikket-sdk",
+  "version": "1.0.0",
+  "description": "Crikket anonymous oRPC client: export bugs, download artifacts, bulk status updates.",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./rpc": {
+      "types": "./dist/rpc.d.ts",
+      "default": "./dist/rpc.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test tests/rpc.test.ts tests/bulk.test.ts tests/client.test.ts tests/export/normalizeSearch.test.ts tests/export/attachments.test.ts tests/export/render.test.ts"
+  },
+  "keywords": [
+    "crikket",
+    "bug-report",
+    "orpc"
+  ],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.2",
+    "typescript": "^6.0.3"
+  }
+}