@chainlesschain/personal-data-hub 0.1.0 → 0.2.0

package/lib/adapters/ai-chat-history/vendors/tongyi.js

@@ -0,0 +1,193 @@
+/**
+ * 通义千问 (Aliyun Tongyi) vendor adapter — Phase 10.2 wiring.
+ *
+ * Reference: docs/design/Adapter_AIChat_History.md §6.3
+ *   - login  https://tongyi.aliyun.com/
+ *   - convs  POST /dialog/conversation/list
+ *   - msgs   POST /dialog/conversation/messages
+ *   - X-Csrf-Token header required (from XSRF-TOKEN cookie)
+ *   - 阿里通用 anti-bot — conservative rateLimits.
+ *
+ * Endpoints + payload shapes are reverse-engineered and SUBJECT TO DRIFT.
+ * Tests use the same fixture-fetch pattern as DeepSeek + Kimi so wire breakage
+ * surfaces immediately when a real cookie is reconnected.
+ */
+
+"use strict";
+
+const BASE = "https://tongyi.aliyun.com";
+const CONV_LIST_PATH = "/dialog/conversation/list";
+const MSG_LIST_PATH = "/dialog/conversation/messages";
+const USER_INFO_PATH = "/api/user/info";
+
+const DEFAULT_PAGE_SIZE = 30;
+
+function _ensureClient(ctx) {
+  if (!ctx || !ctx.httpClient) {
+    throw new Error("tongyi: ctx.httpClient required");
+  }
+  return ctx.httpClient;
+}
+
+function _csrfHeader(session) {
+  // Tongyi reads CSRF from a cookie + echoes it back as a header.
+  const value = session && (session.get("XSRF-TOKEN") || session.get("_csrf"));
+  return value ? { "X-Csrf-Token": value, "X-Xsrf-Token": value } : {};
+}
+
+async function validateCookie(ctx) {
+  const client = _ensureClient(ctx);
+  try {
+    const data = await client.getJson(BASE + USER_INFO_PATH, {
+      session: ctx.session,
+      headers: _csrfHeader(ctx.session),
+    });
+    if (data && (data.success || data.code === 200) && (data.data || data.userId)) {
+      const userId = (data.data && (data.data.userId || data.data.uid)) || data.userId;
+      return { ok: true, userId };
+    }
+    return { ok: false, reason: "UNEXPECTED_RESPONSE_SHAPE" };
+  } catch (err) {
+    return { ok: false, reason: err.code || err.message };
+  }
+}
+
+async function *listConversations(ctx, opts = {}) {
+  const client = _ensureClient(ctx);
+  const pageSize = Number.isFinite(opts.pageSize) ? opts.pageSize : DEFAULT_PAGE_SIZE;
+  const sinceTs = opts.since && opts.since.lastUpdatedAt ? Number(opts.since.lastUpdatedAt) : 0;
+
+  let pageNum = 1;
+  while (true) {
+    const body = { pageNum, pageSize };
+    const data = await client.postJson(BASE + CONV_LIST_PATH, body, {
+      session: ctx.session,
+      headers: _csrfHeader(ctx.session),
+    });
+    const items = _extractList(data);
+    if (items.length === 0) return;
+
+    let stopped = false;
+    for (const c of items) {
+      const updatedAt = _toMs(c.gmtModified || c.updatedAt || c.gmtCreate);
+      if (sinceTs && updatedAt <= sinceTs) {
+        stopped = true;
+        break;
+      }
+      yield {
+        vendor: "tongyi",
+        originalId: String(c.sessionId || c.id),
+        title: c.summary || c.firstQuery || c.title || undefined,
+        modelName: c.modelName || c.model || undefined,
+        createdAt: _toMs(c.gmtCreate || c.createdAt),
+        updatedAt,
+        messageCount: c.messageCount || undefined,
+        archived: Boolean(c.archived),
+        extra: { agentName: c.agentName || c.botName },
+      };
+    }
+    if (stopped) return;
+    if (items.length < pageSize) return;
+    pageNum++;
+    if (pageNum > 200) return; // safety
+  }
+}
+
+async function *listMessages(ctx, conversationId, _opts = {}) {
+  const client = _ensureClient(ctx);
+  const body = { sessionId: String(conversationId), parentMsgId: "" };
+  const data = await client.postJson(BASE + MSG_LIST_PATH, body, {
+    session: ctx.session,
+    headers: _csrfHeader(ctx.session),
+  });
+  const msgs = _extractList(data);
+
+  // Tongyi returns messages mixed user/bot in their own order; we sort
+  // ascending by createTime for stable chronological yield.
+  msgs.sort((a, b) => _toMs(a.createTime || a.gmtCreate) - _toMs(b.createTime || b.gmtCreate));
+
+  for (const m of msgs) {
+    yield {
+      vendor: "tongyi",
+      originalId: String(m.msgId || m.id),
+      conversationId: String(conversationId),
+      role: _normalizeRole(m.senderType || m.role || (m.contentType === "user" ? "user" : "assistant")),
+      content: _buildContent(m),
+      createdAt: _toMs(m.createTime || m.gmtCreate),
+      parentMessageId: m.parentMsgId ? String(m.parentMsgId) : undefined,
+      modelName: m.modelName || m.model || undefined,
+      extra: m.feedback ? { feedback: m.feedback } : undefined,
+    };
+  }
+}
+
+function _extractList(data) {
+  if (!data) return [];
+  if (Array.isArray(data.data)) return data.data;
+  if (data.data && Array.isArray(data.data.list)) return data.data.list;
+  if (data.data && Array.isArray(data.data.records)) return data.data.records;
+  if (Array.isArray(data.list)) return data.list;
+  return [];
+}
+
+function _normalizeRole(r) {
+  if (r === "user" || r === "USER" || r === 1) return "user";
+  if (r === "assistant" || r === "ASSISTANT" || r === "bot" || r === 2) return "assistant";
+  if (r === "system" || r === "SYSTEM" || r === 0) return "system";
+  return r ? String(r).toLowerCase() : "assistant";
+}
+
+function _buildContent(m) {
+  // Tongyi messages have content fanned across `contents[].content` for
+  // multi-segment replies (image + text). Flatten to single text.
+  const segments = Array.isArray(m.contents) ? m.contents : null;
+  const text = segments
+    ? segments.map((s) => s.content || "").filter(Boolean).join("\n")
+    : (m.content || "");
+  const content = { text };
+
+  const files = []
+    .concat(Array.isArray(m.fileList) ? m.fileList : [])
+    .concat(Array.isArray(m.imageList) ? m.imageList : []);
+  if (files.length > 0) {
+    content.attachments = files
+      .map((f) => ({
+        type: (f.type === "image" || /image/i.test(f.fileType || "")) ? "image" : "file",
+        filename: f.fileName || f.name,
+        url: f.url || f.fileUrl,
+        size: f.size,
+        mimeType: f.fileType,
+      }))
+      .filter((a) => a.url || a.filename);
+  }
+  return content;
+}
+
+function _toMs(t) {
+  if (typeof t === "number") return t > 1e12 ? t : t * 1000;
+  if (typeof t === "string") {
+    const n = Number(t);
+    if (Number.isFinite(n)) return n > 1e12 ? n : n * 1000;
+    const d = Date.parse(t);
+    return Number.isFinite(d) ? d : 0;
+  }
+  return 0;
+}
+
+const SPEC = {
+  name: "tongyi",
+  displayName: "通义千问",
+  androidPackage: "com.aliyun.tongyi",
+  loginUrl: "https://tongyi.aliyun.com/",
+  cookieDomains: ["tongyi.aliyun.com", ".aliyun.com"],
+  rateLimits: { perMinute: 20, minIntervalMs: 2000 }, // Aliyun anti-bot — conservative
+
+  validateCookie,
+  listConversations,
+  listMessages,
+};
+
+module.exports = {
+  SPEC,
+  _internal: { _toMs, _normalizeRole, _buildContent, _csrfHeader, _extractList, BASE },
+};

package/lib/adapters/ai-chat-history/vendors/zhipu.js

@@ -0,0 +1,202 @@
+/**
+ * 智谱清言 (Zhipu Qingyan) vendor adapter — Phase 10.2 wiring.
+ *
+ * Reference: docs/design/Adapter_AIChat_History.md §6.4
+ *   - login  https://chatglm.cn/
+ *   - convs  GET /chatglm/backend-api/v1/conversation/list
+ *   - msgs   GET /chatglm/backend-api/v1/conversation/<id>
+ *   - cookie chatglm_token (Bearer-style — re-projected from cookie when
+ *            present; otherwise relies on cookie auth alone)
+ *
+ * GLM-4 messages have optional `tool_calls` for web-search injection; we
+ * thread those into RawMessage.extra.toolCalls so schema-map preserves them
+ * across the KG / RAG flow.
+ *
+ * Endpoint shapes are reverse-engineered + SUBJECT TO DRIFT.
+ */
+
+"use strict";
+
+const BASE = "https://chatglm.cn";
+const CONV_LIST_PATH = "/chatglm/backend-api/v1/conversation/list";
+const CONV_DETAIL_PATH = "/chatglm/backend-api/v1/conversation/";
+const USER_INFO_PATH = "/chatglm/backend-api/v1/user/info";
+
+const DEFAULT_PAGE_SIZE = 30;
+
+function _ensureClient(ctx) {
+  if (!ctx || !ctx.httpClient) {
+    throw new Error("zhipu: ctx.httpClient required");
+  }
+  return ctx.httpClient;
+}
+
+function _authHeader(session) {
+  const token = session && session.get("chatglm_token");
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}
+
+async function validateCookie(ctx) {
+  const client = _ensureClient(ctx);
+  try {
+    const data = await client.getJson(BASE + USER_INFO_PATH, {
+      session: ctx.session,
+      headers: _authHeader(ctx.session),
+    });
+    if (data && data.status === 0 && data.result) {
+      return { ok: true, userId: data.result.user_id || data.result.id };
+    }
+    if (data && (data.user_id || data.id)) {
+      return { ok: true, userId: data.user_id || data.id };
+    }
+    return { ok: false, reason: "UNEXPECTED_RESPONSE_SHAPE" };
+  } catch (err) {
+    return { ok: false, reason: err.code || err.message };
+  }
+}
+
+async function *listConversations(ctx, opts = {}) {
+  const client = _ensureClient(ctx);
+  const pageSize = Number.isFinite(opts.pageSize) ? opts.pageSize : DEFAULT_PAGE_SIZE;
+  const sinceTs = opts.since && opts.since.lastUpdatedAt ? Number(opts.since.lastUpdatedAt) : 0;
+
+  let page = 1;
+  while (true) {
+    const url = new URL(BASE + CONV_LIST_PATH);
+    url.searchParams.set("page", String(page));
+    url.searchParams.set("page_size", String(pageSize));
+
+    const data = await client.getJson(url.toString(), {
+      session: ctx.session,
+      headers: _authHeader(ctx.session),
+    });
+    const list = _extractList(data);
+    if (list.length === 0) return;
+
+    let stopped = false;
+    for (const c of list) {
+      const updatedAt = _toMs(c.update_time || c.updateTime || c.create_time);
+      if (sinceTs && updatedAt <= sinceTs) {
+        stopped = true;
+        break;
+      }
+      yield {
+        vendor: "zhipu",
+        originalId: String(c.conversation_id || c.id),
+        title: c.title || c.summary || undefined,
+        modelName: c.model || c.model_name || undefined,
+        createdAt: _toMs(c.create_time || c.createTime),
+        updatedAt,
+        messageCount: c.message_count || undefined,
+        archived: Boolean(c.archived),
+        extra: { assistantId: c.assistant_id },
+      };
+    }
+    if (stopped) return;
+    if (list.length < pageSize) return;
+    page++;
+    if (page > 200) return;
+  }
+}
+
+async function *listMessages(ctx, conversationId, _opts = {}) {
+  const client = _ensureClient(ctx);
+  const url = BASE + CONV_DETAIL_PATH + encodeURIComponent(conversationId);
+  const data = await client.getJson(url, {
+    session: ctx.session,
+    headers: _authHeader(ctx.session),
+  });
+
+  // GLM detail returns { result: { messages: [...] } } or { messages: [...] }.
+  let msgs = [];
+  if (data && data.result && Array.isArray(data.result.messages)) msgs = data.result.messages;
+  else if (data && Array.isArray(data.messages)) msgs = data.messages;
+  else if (data && data.result && Array.isArray(data.result.history)) msgs = data.result.history;
+
+  msgs.sort((a, b) => _toMs(a.create_time || a.timestamp) - _toMs(b.create_time || b.timestamp));
+
+  for (const m of msgs) {
+    yield {
+      vendor: "zhipu",
+      originalId: String(m.id || m.message_id),
+      conversationId: String(conversationId),
+      role: _normalizeRole(m.role || m.sender),
+      content: _buildContent(m),
+      createdAt: _toMs(m.create_time || m.timestamp),
+      parentMessageId: m.parent_id ? String(m.parent_id) : undefined,
+      modelName: m.model || undefined,
+      extra: {
+        toolCalls: Array.isArray(m.tool_calls) ? m.tool_calls : undefined,
+        searchQuery: m.search_query,
+      },
+    };
+  }
+}
+
+function _extractList(data) {
+  if (!data) return [];
+  if (Array.isArray(data.result)) return data.result;
+  if (data.result && Array.isArray(data.result.list)) return data.result.list;
+  if (data.result && Array.isArray(data.result.conversations)) return data.result.conversations;
+  if (Array.isArray(data.conversations)) return data.conversations;
+  if (Array.isArray(data.list)) return data.list;
+  return [];
+}
+
+function _normalizeRole(r) {
+  if (r === "user" || r === "USER") return "user";
+  if (r === "assistant" || r === "ASSISTANT" || r === "bot") return "assistant";
+  if (r === "system" || r === "SYSTEM") return "system";
+  if (r === "tool" || r === "TOOL") return "tool";
+  return r ? String(r).toLowerCase() : "assistant";
+}
+
+function _buildContent(m) {
+  const content = { text: m.content || m.text || "" };
+  if (Array.isArray(m.attachments) && m.attachments.length > 0) {
+    content.attachments = m.attachments
+      .map((a) => ({
+        type: (a.type === "image" || /image/i.test(a.mime_type || "")) ? "image" : "file",
+        filename: a.name || a.file_name,
+        url: a.url || a.download_url,
+        size: a.size,
+        mimeType: a.mime_type,
+      }))
+      .filter((a) => a.url || a.filename);
+  }
+  if (Array.isArray(m.images) && m.images.length > 0) {
+    content.attachments = (content.attachments || []).concat(
+      m.images.map((i) => ({ type: "image", url: i.url || i, mimeType: "image/png" })),
+    );
+  }
+  return content;
+}
+
+function _toMs(t) {
+  if (typeof t === "number") return t > 1e12 ? t : t * 1000;
+  if (typeof t === "string") {
+    const n = Number(t);
+    if (Number.isFinite(n)) return n > 1e12 ? n : n * 1000;
+    const d = Date.parse(t);
+    return Number.isFinite(d) ? d : 0;
+  }
+  return 0;
+}
+
+const SPEC = {
+  name: "zhipu",
+  displayName: "智谱清言",
+  androidPackage: "com.zhipuai.qingyan",
+  loginUrl: "https://chatglm.cn/",
+  cookieDomains: ["chatglm.cn", ".chatglm.cn"],
+  rateLimits: { perMinute: 20, minIntervalMs: 2000 },
+
+  validateCookie,
+  listConversations,
+  listMessages,
+};
+
+module.exports = {
+  SPEC,
+  _internal: { _toMs, _normalizeRole, _buildContent, _authHeader, _extractList, BASE },
+};

package/lib/adapters/alipay-bill/alipay-bill-adapter.js

@@ -0,0 +1,307 @@
+/**
+ * AlipayBillAdapter — Phase 6 of the Personal Data Hub.
+ *
+ * **Not a server-pull adapter** — Alipay has no public API. Users export
+ * a CSV bill from the Alipay app (我的 → 账单 → 开具交易流水证明 → 发到
+ * 邮箱), then drop the resulting `alipay_record_*.zip` into our UI.
+ *
+ * The adapter's `sync()` therefore takes an explicit `csvPath` (or
+ * `zipPath` + password) opt rather than auto-fetching. Registry calls
+ * with no opt → no-op (returns immediately). UI drives sync per-file.
+ *
+ * Watermark: Alipay CSVs are full-month exports; no incremental
+ * server-side state. We dedupe via `source.originalId = txId` so re-
+ * importing the same CSV produces 0 new events. Watermark is only
+ * informational ("last imported file hash + row count").
+ */
+
+"use strict";
+
+const fs = require("node:fs");
+const crypto = require("node:crypto");
+
+const { EVENT_SUBTYPES, PERSON_SUBTYPES, CAPTURED_BY } = require("../../constants");
+const { newId } = require("../../ids");
+const { parseAlipayCsvBuffer } = require("./csv-parser");
+const { extractCsvFromZip } = require("./zip-decryptor");
+const {
+  classifyCounterparty,
+  counterpartyToPersonId,
+} = require("./counterparty");
+
+const NAME = "alipay-bill";
+const VERSION = "0.1.0"; // Phase 6 — initial CSV-import adapter
+
+/**
+ * Map Alipay's `类型` string → UnifiedSchema Event.subtype.
+ * Per design doc §4.4.
+ */
+function mapAlipayTypeToSubtype(alipayType, direction) {
+  const t = String(alipayType || "");
+  if (t.includes("转账")) return "transfer";
+  if (t.includes("退款")) return "refund";
+  if (t.includes("理财") || t.includes("余额宝")) return "investment";
+  if (t.includes("红包")) return "redenvelope";
+  if (t.includes("缴费")) return "utility";
+  if (t.includes("交易关闭") || t.includes("交易失败")) return "cancelled";
+  return direction === "收入" ? "income" : "payment";
+}
+
+class AlipayBillAdapter {
+  constructor(opts) {
+    if (!opts || typeof opts !== "object") {
+      throw new Error("AlipayBillAdapter: opts required");
+    }
+    const account = opts.account;
+    if (!account || typeof account !== "object") {
+      throw new Error("AlipayBillAdapter: opts.account required");
+    }
+    if (typeof account.email !== "string" || account.email.length === 0) {
+      throw new Error("AlipayBillAdapter: account.email required (Alipay account identifier)");
+    }
+    this.account = account;
+    // ZIP password (= 身份证后 6 位 by default). Optional — if the user's
+    // export is unencrypted (rare) or they extract manually first, pass
+    // csvPath at sync() time.
+    this._zipPassword = typeof opts.zipPassword === "string" ? opts.zipPassword : null;
+    // Test seams
+    this._csvParser = typeof opts.csvParser === "function" ? opts.csvParser : parseAlipayCsvBuffer;
+    this._zipExtractor = typeof opts.zipExtractor === "function" ? opts.zipExtractor : extractCsvFromZip;
+
+    this.name = NAME;
+    this.version = VERSION;
+    this.capabilities = ["import:csv-zip", "parse:transactions"];
+    this.rateLimits = {};
+    this.dataDisclosure = {
+      fields: [
+        "alipay:txId, createdAt, paidAt, counterparty, itemName, amount, direction, status, note",
+      ],
+      sensitivity: "high",
+      legalGate: false,
+    };
+  }
+
+  async authenticate(_ctx = {}) {
+    // No server auth — adapter is always "ok" once configured.
+    return { ok: true, account: this.account.email, provider: "alipay-bill" };
+  }
+
+  async healthCheck() {
+    return { ok: true, lastChecked: Date.now() };
+  }
+
+  /**
+   * `sync()` here is driven by an explicit file path. When called with
+   * no zipPath/csvPath the adapter emits 0 events (waiting for user
+   * action). Registry's syncAll() will hit this case for periodic
+   * checks — same as Phase 5 EmailAdapter handles authcode-not-set.
+   *
+   * @param {object} opts
+   * @param {string} [opts.zipPath]       full path to alipay_record_*.zip
+   * @param {string} [opts.csvPath]       full path to a pre-extracted .csv
+   * @param {string} [opts.zipPassword]   overrides constructor zipPassword
+   * @param {Function} [opts.onProgress]
+   */
+  async *sync(opts = {}) {
+    const zipPath = typeof opts.zipPath === "string" ? opts.zipPath : null;
+    const csvPath = typeof opts.csvPath === "string" ? opts.csvPath : null;
+    if (!zipPath && !csvPath) {
+      // Idle — no file to import this run
+      return;
+    }
+
+    const onProgress = typeof opts.onProgress === "function" ? opts.onProgress : null;
+    const emit = (phase, payload = {}) => {
+      if (!onProgress) return;
+      try { onProgress({ phase, adapter: NAME, ...payload }); } catch (_e) {}
+    };
+
+    emit("opening", { zipPath, csvPath });
+
+    let csvBuffer;
+    let sourceFile;
+    if (zipPath) {
+      const password = typeof opts.zipPassword === "string" ? opts.zipPassword : this._zipPassword;
+      const out = await this._zipExtractor(zipPath, { password });
+      csvBuffer = out.buffer;
+      sourceFile = `${zipPath}::${out.filename}`;
+    } else {
+      csvBuffer = fs.readFileSync(csvPath);
+      sourceFile = csvPath;
+    }
+    const fileSha256 = crypto.createHash("sha256").update(csvBuffer).digest("hex");
+    emit("parsing", { sourceFile, fileSha256, bytes: csvBuffer.length });
+
+    const parsed = this._csvParser(csvBuffer);
+    emit("parsed", {
+      sourceFile,
+      encoding: parsed.encoding,
+      rows: parsed.rows.length,
+      header: parsed.header,
+    });
+
+    let yielded = 0;
+    for (const row of parsed.rows) {
+      emit("row", { current: yielded + 1, total: parsed.rows.length, txId: row.txId });
+      yield this._rowToRawEvent(row, {
+        sourceFile,
+        fileSha256,
+        accountEmail: this.account.email,
+        importedAt: Date.now(),
+        billPeriod: parsed.header,
+      });
+      yielded += 1;
+    }
+
+    emit("done", { yielded, sourceFile });
+  }
+
+  /**
+   * normalize(raw) → NormalizedBatch (Event + Persons + Items).
+   * Per design doc §5.4.
+   */
+  normalize(raw) {
+    if (!raw || typeof raw !== "object" || !raw.payload) {
+      throw new Error("AlipayBillAdapter.normalize: missing raw or raw.payload");
+    }
+    const row = raw.payload.row;
+    if (!row || typeof row !== "object") {
+      throw new Error("AlipayBillAdapter.normalize: payload.row missing");
+    }
+
+    // Parse the amount and timestamps
+    const amount = parseFloat(row.amount);
+    const occurredAt = parseAlipayDateTime(row.paidAt) || parseAlipayDateTime(row.createdAt) || raw.capturedAt || Date.now();
+
+    // Counterparty → Person (with stable id for dedup)
+    const counterpartyId = counterpartyToPersonId(row.counterparty);
+    const counterpartyKind = classifyCounterparty(row.counterparty);
+    const direction = row.direction === "收入" ? "in" : "out";
+
+    const subtype = mapAlipayTypeToSubtype(row.alipayType, row.direction);
+    const eventId = newId();
+
+    // Skip closed / failed transactions — they polluted vault with
+    // "transaction never happened" rows. Mark as cancelled instead.
+    const isCancelled = subtype === "cancelled" || /关闭|失败/.test(row.status || "");
+
+    const ingestedAt = Date.now();
+    const source = {
+      adapter: NAME,
+      adapterVersion: VERSION,
+      originalId: row.txId,
+      capturedAt: raw.capturedAt || occurredAt,
+      capturedBy: CAPTURED_BY ? (CAPTURED_BY.EXPORT || "export") : "export",
+    };
+
+    const event = {
+      id: eventId,
+      type: "event",
+      subtype: isCancelled ? "cancelled" : subtype,
+      occurredAt,
+      actor: direction === "out" ? "person-self" : counterpartyId,
+      participants: [counterpartyId, "person-self"].filter(Boolean),
+      content: {
+        title: row.itemName || row.alipayType || row.counterparty,
+        ...(row.note ? { text: row.note } : {}),
+        amount: {
+          value: Number.isFinite(amount) ? amount : 0,
+          currency: "CNY",
+          direction,
+        },
+      },
+      ingestedAt,
+      source,
+      extra: {
+        alipayType: row.alipayType,
+        sourceChannel: row.sourceChannel || undefined,
+        merchantOrderNumber: row.merchantOrderNumber || undefined,
+        txStatus: row.status,
+        serviceFee: parseFloat(row.serviceFee || "0") || 0,
+        refundedAmount: parseFloat(row.refundedAmount || "0") || 0,
+        fundStatus: row.fundStatus || undefined,
+        accountEmail: raw.payload.accountEmail,
+        fileSha256: raw.payload.fileSha256,
+        billPeriod: raw.payload.billPeriod || undefined,
+        counterpartyKind,
+        ...(counterpartyKind === "unknown" ? { needsResolve: true } : {}),
+      },
+    };
+
+    const persons = [{
+      id: counterpartyId,
+      type: "person",
+      subtype: counterpartyKind === "contact"
+        ? (PERSON_SUBTYPES ? (PERSON_SUBTYPES.CONTACT || "contact") : "contact")
+        : (PERSON_SUBTYPES ? (PERSON_SUBTYPES.MERCHANT || "merchant") : "merchant"),
+      names: [row.counterparty || "(unknown)"],
+      identifiers: {},
+      ingestedAt,
+      source,
+      extra: {
+        ...(counterpartyKind === "unknown" ? { needsResolve: true } : {}),
+        firstSeenAt: occurredAt,
+      },
+    }];
+
+    // Item (only when an itemName is present and not just an alipayType)
+    const items = [];
+    if (row.itemName && row.itemName !== row.alipayType) {
+      items.push({
+        id: newId(),
+        type: "item",
+        subtype: "product",
+        name: row.itemName,
+        price: { value: amount, currency: "CNY" },
+        merchant: counterpartyId,
+        ingestedAt,
+        source,
+        extra: {
+          sourceEventId: eventId,
+        },
+      });
+    }
+
+    return { events: [event], persons, places: [], items, topics: [] };
+  }
+
+  _rowToRawEvent(row, ctx) {
+    return {
+      adapter: NAME,
+      originalId: row.txId,
+      capturedAt: parseAlipayDateTime(row.paidAt) || parseAlipayDateTime(row.createdAt) || ctx.importedAt,
+      payload: {
+        row,
+        accountEmail: ctx.accountEmail,
+        sourceFile: ctx.sourceFile,
+        fileSha256: ctx.fileSha256,
+        importedAt: ctx.importedAt,
+        billPeriod: ctx.billPeriod,
+      },
+    };
+  }
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────
+
+/**
+ * Parse "2024-04-01 09:23:13" → ms epoch (local time). Alipay timestamps
+ * are local-time strings (no timezone marker). Returns null on parse
+ * failure.
+ */
+function parseAlipayDateTime(s) {
+  if (typeof s !== "string" || s.length === 0) return null;
+  // Replace space with T so Date can parse it
+  const iso = s.replace(" ", "T");
+  const d = new Date(iso);
+  const t = d.getTime();
+  return Number.isFinite(t) ? t : null;
+}
+
+module.exports = {
+  AlipayBillAdapter,
+  mapAlipayTypeToSubtype,
+  parseAlipayDateTime,
+  NAME,
+  VERSION,
+};