@zhin.js/plugin-ledger 0.0.0-stage → 1.0.1

package/lib/store.d.ts

@@ -0,0 +1,48 @@
+import type { DeliveryTarget, PluginDatabaseHost } from 'zhin.js';
+export declare const ENTRY_TABLE = "ledger_entries";
+export declare const USER_TABLE = "ledger_users";
+/** Separate table: existing databases only run CREATE TABLE IF NOT EXISTS, so new columns on `ledger_users` would never appear. */
+export declare const PRIVATE_TARGET_TABLE = "ledger_private_targets";
+/** One expense. `seq` is the per-user number shown as `#id`; amounts are integer cents. */
+export interface LedgerEntry {
+    readonly ownerKey: string;
+    readonly seq: number;
+    readonly category: string;
+    readonly amountCents: number;
+    readonly note: string;
+    readonly createdAt: number;
+}
+/** Per-user settings: the next entry number and the opt-in daily report. */
+export interface LedgerUserRecord {
+    readonly ownerKey: string;
+    readonly nextSeq: number;
+    readonly reportEnabled: boolean;
+    readonly reportTarget: DeliveryTarget | undefined;
+    readonly lastReportDate: string;
+}
+/** Registers both tables; called from `setup()` before the database starts. */
+export declare function defineLedgerTables(database: Pick<PluginDatabaseHost, 'define'>): void;
+/**
+ * Every query filters on `owner_key`, the caller's own identity, so one user can never read,
+ * number or delete another user's entries. Models are looked up per call because the
+ * database only starts after `setup()`.
+ */
+export declare class LedgerStore {
+    #private;
+    constructor(database: PluginDatabaseHost);
+    getUser(ownerKey: string): Promise<LedgerUserRecord | undefined>;
+    /** Reserves the next per-user entry number. Callers serialise per user (see LedgerService). */
+    reserveSequence(ownerKey: string): Promise<number>;
+    insertEntry(entry: LedgerEntry): Promise<void>;
+    listEntries(ownerKey: string): Promise<LedgerEntry[]>;
+    findEntry(ownerKey: string, seq: number): Promise<LedgerEntry | undefined>;
+    deleteEntry(ownerKey: string, seq: number): Promise<void>;
+    setReport(ownerKey: string, enabled: boolean, target: DeliveryTarget | undefined, lastReportDate: string): Promise<void>;
+    /** The real private conversation saved when the user talked to the bot in private. */
+    getPrivateTarget(ownerKey: string): Promise<DeliveryTarget | undefined>;
+    /** Saves the real private conversation; an enabled daily report follows it. */
+    setPrivateTarget(ownerKey: string, target: DeliveryTarget): Promise<void>;
+    listReportSubscribers(): Promise<LedgerUserRecord[]>;
+    markReported(ownerKey: string, dateKey: string): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/lib/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAqB,cAAc,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAErF,eAAO,MAAM,WAAW,mBAAmB,CAAC;AAC5C,eAAO,MAAM,UAAU,iBAAiB,CAAC;AACzC,mIAAmI;AACnI,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAE7D,2FAA2F;AAC3F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,cAAc,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC,GAAG,IAAI,CAoBrF;AAgCD;;;;GAIG;AACH,qBAAa,WAAW;;gBAGV,QAAQ,EAAE,kBAAkB;IAUlC,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAqBtE,+FAA+F;IACzF,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOlD,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAW9C,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAOrD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAQ1E,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,GAAG,SAAS,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9H,sFAAsF;IAChF,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAK7E,+EAA+E;IACzE,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAYzE,qBAAqB,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAOpD,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGrE"}

package/lib/store.js

@@ -0,0 +1,162 @@
+export const ENTRY_TABLE = 'ledger_entries';
+export const USER_TABLE = 'ledger_users';
+/** Separate table: existing databases only run CREATE TABLE IF NOT EXISTS, so new columns on `ledger_users` would never appear. */
+export const PRIVATE_TARGET_TABLE = 'ledger_private_targets';
+/** Registers both tables; called from `setup()` before the database starts. */
+export function defineLedgerTables(database) {
+    database.define(ENTRY_TABLE, {
+        owner_key: { type: 'text', nullable: false },
+        seq: { type: 'integer', nullable: false },
+        category: { type: 'text', nullable: false },
+        amount_cents: { type: 'integer', nullable: false },
+        note: { type: 'text', default: '' },
+        created_at: { type: 'text', nullable: false },
+    });
+    database.define(USER_TABLE, {
+        owner_key: { type: 'text', nullable: false },
+        next_seq: { type: 'integer', default: 1 },
+        report_enabled: { type: 'integer', default: 0 },
+        report_target: { type: 'text', default: '' },
+        last_report_date: { type: 'text', default: '' },
+    });
+    database.define(PRIVATE_TARGET_TABLE, {
+        owner_key: { type: 'text', nullable: false },
+        target: { type: 'text', nullable: false },
+    });
+}
+function toEntry(row) {
+    return {
+        ownerKey: String(row.owner_key),
+        seq: Number(row.seq),
+        category: String(row.category),
+        amountCents: Number(row.amount_cents),
+        note: String(row.note ?? ''),
+        createdAt: Date.parse(String(row.created_at)),
+    };
+}
+function parseTarget(raw) {
+    if (typeof raw !== 'string' || raw === '')
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+function toUser(row) {
+    return {
+        ownerKey: String(row.owner_key),
+        nextSeq: Number(row.next_seq ?? 1),
+        reportEnabled: Number(row.report_enabled ?? 0) === 1,
+        reportTarget: parseTarget(row.report_target),
+        lastReportDate: String(row.last_report_date ?? ''),
+    };
+}
+/**
+ * Every query filters on `owner_key`, the caller's own identity, so one user can never read,
+ * number or delete another user's entries. Models are looked up per call because the
+ * database only starts after `setup()`.
+ */
+export class LedgerStore {
+    #database;
+    constructor(database) {
+        this.#database = database;
+    }
+    #model(table) {
+        const model = this.#database.models.get(table);
+        if (!model)
+            throw new Error(`记账数据表 ${table} 不可用`);
+        return model;
+    }
+    async getUser(ownerKey) {
+        const rows = await this.#model(USER_TABLE)
+            .select('owner_key', 'next_seq', 'report_enabled', 'report_target', 'last_report_date')
+            .where({ owner_key: ownerKey });
+        const first = rows[0];
+        return first ? toUser(first) : undefined;
+    }
+    async #ensureUser(ownerKey) {
+        const existing = await this.getUser(ownerKey);
+        if (existing)
+            return existing;
+        await this.#model(USER_TABLE).insert({
+            owner_key: ownerKey,
+            next_seq: 1,
+            report_enabled: 0,
+            report_target: '',
+            last_report_date: '',
+        });
+        return { ownerKey, nextSeq: 1, reportEnabled: false, reportTarget: undefined, lastReportDate: '' };
+    }
+    /** Reserves the next per-user entry number. Callers serialise per user (see LedgerService). */
+    async reserveSequence(ownerKey) {
+        const user = await this.#ensureUser(ownerKey);
+        const reserved = user.nextSeq;
+        await this.#model(USER_TABLE).update({ next_seq: reserved + 1 }).where({ owner_key: ownerKey });
+        return reserved;
+    }
+    async insertEntry(entry) {
+        await this.#model(ENTRY_TABLE).insert({
+            owner_key: entry.ownerKey,
+            seq: entry.seq,
+            category: entry.category,
+            amount_cents: entry.amountCents,
+            note: entry.note,
+            created_at: new Date(entry.createdAt).toISOString(),
+        });
+    }
+    async listEntries(ownerKey) {
+        const rows = await this.#model(ENTRY_TABLE)
+            .select('owner_key', 'seq', 'category', 'amount_cents', 'note', 'created_at')
+            .where({ owner_key: ownerKey });
+        return rows.map(toEntry);
+    }
+    async findEntry(ownerKey, seq) {
+        const rows = await this.#model(ENTRY_TABLE)
+            .select('owner_key', 'seq', 'category', 'amount_cents', 'note', 'created_at')
+            .where({ owner_key: ownerKey, seq });
+        const first = rows[0];
+        return first ? toEntry(first) : undefined;
+    }
+    async deleteEntry(ownerKey, seq) {
+        await this.#model(ENTRY_TABLE).delete().where({ owner_key: ownerKey, seq });
+    }
+    async setReport(ownerKey, enabled, target, lastReportDate) {
+        await this.#ensureUser(ownerKey);
+        await this.#model(USER_TABLE).update({
+            report_enabled: enabled ? 1 : 0,
+            report_target: target ? JSON.stringify(target) : '',
+            last_report_date: lastReportDate,
+        }).where({ owner_key: ownerKey });
+    }
+    /** The real private conversation saved when the user talked to the bot in private. */
+    async getPrivateTarget(ownerKey) {
+        const rows = await this.#model(PRIVATE_TARGET_TABLE).select('owner_key', 'target').where({ owner_key: ownerKey });
+        return parseTarget(rows[0]?.target);
+    }
+    /** Saves the real private conversation; an enabled daily report follows it. */
+    async setPrivateTarget(ownerKey, target) {
+        const raw = JSON.stringify(target);
+        const model = this.#model(PRIVATE_TARGET_TABLE);
+        const existing = await model.select('owner_key', 'target').where({ owner_key: ownerKey });
+        if (existing.length > 0)
+            await model.update({ target: raw }).where({ owner_key: ownerKey });
+        else
+            await model.insert({ owner_key: ownerKey, target: raw });
+        const user = await this.getUser(ownerKey);
+        if (user?.reportEnabled) {
+            await this.#model(USER_TABLE).update({ report_target: raw }).where({ owner_key: ownerKey });
+        }
+    }
+    async listReportSubscribers() {
+        const rows = await this.#model(USER_TABLE)
+            .select('owner_key', 'next_seq', 'report_enabled', 'report_target', 'last_report_date')
+            .where({ report_enabled: 1 });
+        return rows.map(toUser);
+    }
+    async markReported(ownerKey, dateKey) {
+        await this.#model(USER_TABLE).update({ last_report_date: dateKey }).where({ owner_key: ownerKey });
+    }
+}
+//# sourceMappingURL=store.js.map

package/lib/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,93 @@
 {
   "name": "@zhin.js/plugin-ledger",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.1",
+  "description": "Personal expense ledger for Zhin.js (Plugin Runtime): per-user entries in integer cents, period and category summaries, group privacy and an opt-in daily report",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "README.md",
+    "commands",
+    "lib",
+    "plugin.js",
+    "schedules",
+    "src",
+    "schema.json"
+  ],
+  "keywords": [
+    "zhin",
+    "zhin.js",
+    "bot",
+    "plugin",
+    "ledger",
+    "expense"
+  ],
+  "author": {
+    "name": "lc-cn",
+    "email": "admin@liucl.cn",
+    "url": "https://github.com/lc-cn"
+  },
+  "peerDependencies": {
+    "zhin.js": "^1.1.13",
+    "@zhin.js/command": "^1.1.9",
+    "@zhin.js/schedule-feature": "^1.1.7"
+  },
+  "peerDependenciesMeta": {
+    "@zhin.js/command": {
+      "optional": true
+    },
+    "@zhin.js/schedule-feature": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "@zhin.js/schedule-feature": "1.1.7",
+    "@zhin.js/testing": "1.0.5",
+    "zhin.js": "1.1.13"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "plugins/utils/ledger"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/schedule-feature",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc -p tsconfig.check.json",
+    "test": "vitest run --root ../../.. plugins/utils/ledger/tests"
+  }
 }

package/plugin.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { databaseHostToken, definePlugin, outboundHostToken } from 'zhin.js';
+import { resolveLedgerConfig } from "./lib/config.js";
+import { ledgerServiceToken } from "./lib/runtime.js";
+import { LedgerService } from "./lib/service.js";
+import { defineLedgerTables } from "./lib/store.js";
+export default definePlugin({
+    name: 'ledger',
+    metadata: { displayName: '记账' },
+    requires: [databaseHostToken],
+    setup(context) {
+        const config = resolveLedgerConfig(context.config.get());
+        const database = context.resources.use(databaseHostToken);
+        defineLedgerTables(database);
+        const outbound = context.resources.has(outboundHostToken) ? context.resources.use(outboundHostToken) : undefined;
+        const service = new LedgerService(database, outbound, config);
+        context.resources.provide(ledgerServiceToken, service);
+    },
+});

package/schedules/daily-report/index.js

@@ -0,0 +1,10 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineSchedule } from '@zhin.js/schedule-feature';
+import { ledgerServiceToken } from "../../lib/runtime.js";
+export default defineSchedule({
+    cron: '0 * * * * *',
+    description: '每分钟检查一次；到达 reportTime 后给已订阅用户私信当天记账日报，每人每天一次',
+    execute: async (context) => {
+        await context.use(ledgerServiceToken).runDailyReports();
+    },
+});

package/schedules/daily-report/index.ts

@@ -0,0 +1,10 @@
+import { defineSchedule } from '@zhin.js/schedule-feature';
+import { ledgerServiceToken } from '../../src/runtime.js';
+
+export default defineSchedule({
+  cron: '0 * * * * *',
+  description: '每分钟检查一次；到达 reportTime 后给已订阅用户私信当天记账日报，每人每天一次',
+  execute: async (context) => {
+    await context.use(ledgerServiceToken).runDailyReports();
+  },
+});

package/schema.json

@@ -0,0 +1,31 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "timezone": {
+      "type": "string",
+      "description": "计算今日、本周（周一开始）、本月与日报日期所用的 IANA 时区",
+      "default": "Asia/Shanghai",
+      "x-zhin-config": {
+        "effect": "reload"
+      }
+    },
+    "reportTime": {
+      "type": "string",
+      "description": "记账日报的发送时间（HH:MM，按 timezone）；只发给用「记账日报 开启」订阅的用户",
+      "default": "22:00",
+      "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$",
+      "x-zhin-config": {
+        "effect": "reload"
+      }
+    },
+    "reportWhenEmpty": {
+      "type": "boolean",
+      "description": "当天没有记账时是否仍发送日报",
+      "default": false,
+      "x-zhin-config": {
+        "effect": "reload"
+      }
+    }
+  }
+}

package/src/config.ts

@@ -0,0 +1,39 @@
+import { Schema } from 'zhin.js';
+
+export const DEFAULT_TIMEZONE = 'Asia/Shanghai';
+export const DEFAULT_REPORT_TIME = '22:00';
+
+export const ledgerConfig = Schema.object({
+  timezone: Schema.string().default(DEFAULT_TIMEZONE).description('计算今日、本周（周一开始）、本月与日报日期所用的 IANA 时区').effect('reload'),
+  reportTime: Schema.string().default(DEFAULT_REPORT_TIME).description('记账日报的发送时间（HH:MM，按 timezone）；只发给用「记账日报 开启」订阅的用户').effect('reload'),
+  reportWhenEmpty: Schema.boolean().default(false).description('当天没有记账时是否仍发送日报').effect('reload'),
+});
+
+export type LedgerConfig = Schema.Output<typeof ledgerConfig>;
+
+export interface ResolvedLedgerConfig {
+  readonly timezone: string;
+  readonly reportTime: string;
+  readonly reportWhenEmpty: boolean;
+}
+
+const REPORT_TIME_PATTERN = /^(?:[01]\d|2[0-3]):[0-5]\d$/u;
+
+function assertTimezone(timezone: string): void {
+  try {
+    if (!timezone || timezone !== timezone.trim() || /^[+-]/u.test(timezone)) throw new RangeError('Invalid IANA timezone');
+    new Intl.DateTimeFormat('zh-CN', { timeZone: timezone }).format(0);
+  } catch {
+    throw new TypeError(`记账 timezone 必须是有效的 IANA 时区：${timezone}`);
+  }
+}
+
+/** Applies defaults and fails setup on an invalid timezone or report time instead of guessing. */
+export function resolveLedgerConfig(config: Partial<LedgerConfig> | undefined): ResolvedLedgerConfig {
+  const timezone = config?.timezone ?? DEFAULT_TIMEZONE;
+  const reportTime = config?.reportTime ?? DEFAULT_REPORT_TIME;
+  const reportWhenEmpty = config?.reportWhenEmpty ?? false;
+  assertTimezone(timezone);
+  if (!REPORT_TIME_PATTERN.test(reportTime)) throw new TypeError(`记账 reportTime 必须是 HH:MM：${reportTime}`);
+  return { timezone, reportTime, reportWhenEmpty };
+}

package/src/entry-input.ts

@@ -0,0 +1,39 @@
+import { parseAmountToCents } from './money.js';
+
+export const MAX_CATEGORY_LENGTH = 20;
+export const MAX_NOTE_LENGTH = 100;
+
+export const ADD_USAGE = '格式：记 <类别> <金额> [备注]，例如：记 午饭 18.5 和同事';
+
+export interface ParsedEntryInput {
+  readonly category: string;
+  readonly amountCents: number;
+  readonly note: string;
+}
+
+export type EntryInputResult =
+  | { readonly ok: true; readonly entry: ParsedEntryInput }
+  | { readonly ok: false; readonly reason: string };
+
+function rejected(reason: string): EntryInputResult {
+  return { ok: false, reason };
+}
+
+/** Parses the text after `记`: category, amount, then an optional free-form note. */
+export function parseEntryInput(text: string): EntryInputResult {
+  const words = text.trim().split(/\s+/u).filter((word) => word !== '');
+  if (words.length < 2) return rejected(ADD_USAGE);
+  const category = words[0]!;
+  const amountText = words[1]!;
+  const note = words.slice(2).join(' ');
+  const amount = parseAmountToCents(amountText);
+  if (!amount.ok) {
+    const categoryLooksLikeAmount = parseAmountToCents(category).ok;
+    if (categoryLooksLikeAmount) return rejected(`类别要写在金额前面。${ADD_USAGE}`);
+    return rejected(`${amount.reason}。${ADD_USAGE}`);
+  }
+  if (parseAmountToCents(category).ok) return rejected(`类别不能是数字。${ADD_USAGE}`);
+  if ([...category].length > MAX_CATEGORY_LENGTH) return rejected(`类别最多 ${MAX_CATEGORY_LENGTH} 个字`);
+  if ([...note].length > MAX_NOTE_LENGTH) return rejected(`备注最多 ${MAX_NOTE_LENGTH} 个字`);
+  return { ok: true, entry: { category, amountCents: amount.cents, note } };
+}

package/src/identity.ts

@@ -0,0 +1,50 @@
+import { createDeliveryTarget, type DeliveryTarget } from 'zhin.js';
+import type { CommandMessage } from 'zhin.js/command';
+
+/** The person using a ledger command and where they are talking from. */
+export interface LedgerCaller {
+  /** Stable per-user key: adapter + endpoint (bot account) + sender id. */
+  readonly ownerKey: string;
+  readonly senderId: string;
+  /** The conversation the command came from. */
+  readonly conversation: DeliveryTarget;
+  /** The caller's own private conversation with the same bot account. */
+  readonly privateTarget: DeliveryTarget;
+  /** False in groups and channels, where other people can read replies. */
+  readonly isPrivate: boolean;
+}
+
+export class LedgerInputError extends Error {}
+
+export function ledgerOwnerKey(adapter: string, endpointId: string, senderId: string): string {
+  return JSON.stringify([adapter, endpointId, senderId]);
+}
+
+/** Builds the caller from a command message; commands without a real sender are refused. */
+export function ledgerCaller(input: CommandMessage | undefined): LedgerCaller {
+  const senderId = input?.sender?.id;
+  if (!input || !senderId) throw new LedgerInputError('记账需要在真实会话中由具体用户发送');
+  const conversation = createDeliveryTarget(input);
+  const endpoint = conversation.endpoint;
+  const isPrivate = conversation.kind === 'private';
+  const privateTarget: DeliveryTarget = isPrivate
+    ? conversation
+    : Object.freeze({ endpoint, kind: 'private', id: senderId });
+  return {
+    ownerKey: ledgerOwnerKey(endpoint.adapter, endpoint.id, senderId),
+    senderId,
+    conversation,
+    privateTarget,
+    isPrivate,
+  };
+}
+
+/** Turns expected input problems into a reply and lets real failures surface. */
+export async function replyLedger(operation: () => Promise<string>): Promise<string> {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof LedgerInputError) return error.message;
+    throw error;
+  }
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+export { ledgerConfig, resolveLedgerConfig, DEFAULT_REPORT_TIME, DEFAULT_TIMEZONE, type LedgerConfig, type ResolvedLedgerConfig } from './config.js';
+export { parseEntryInput, ADD_USAGE, MAX_CATEGORY_LENGTH, MAX_NOTE_LENGTH, type EntryInputResult, type ParsedEntryInput } from './entry-input.js';
+export { ledgerCaller, ledgerOwnerKey, replyLedger, LedgerInputError, type LedgerCaller } from './identity.js';
+export { formatCents, parseAmountToCents, MASKED_AMOUNT, MAX_ENTRY_CENTS, type AmountParseResult } from './money.js';
+export {
+  describePeriodRange,
+  isInPeriod,
+  localDateKey,
+  localTimeKey,
+  parsePeriodWord,
+  periodLabel,
+  weekEndKey,
+  weekStartKey,
+  type LedgerPeriod,
+} from './period.js';
+export {
+  formatCategoryStatistics,
+  formatEntryList,
+  formatPeriodSummary,
+  summarize,
+  totalsByCategory,
+  MAX_LISTED_ENTRIES,
+  type CategoryTotal,
+  type LedgerReply,
+  type PeriodSummary,
+} from './report-format.js';
+export { ledgerServiceToken } from './runtime.js';
+export { LedgerService, type DailyReportAction, type LedgerServiceOptions } from './service.js';
+export { defineLedgerTables, LedgerStore, ENTRY_TABLE, USER_TABLE, PRIVATE_TARGET_TABLE, type LedgerEntry, type LedgerUserRecord } from './store.js';

package/src/money.ts

@@ -0,0 +1,53 @@
+/**
+ * Amounts are stored as integer cents (分) and parsed from text without floating point,
+ * so 0.1 + 0.2 style rounding errors cannot enter the ledger.
+ */
+
+/** Largest single entry: ¥1,000,000.00, which also keeps sums far below Number.MAX_SAFE_INTEGER. */
+export const MAX_ENTRY_CENTS = 100_000_000;
+
+export type AmountParseResult =
+  | { readonly ok: true; readonly cents: number }
+  | { readonly ok: false; readonly reason: string };
+
+const AMOUNT_PATTERN = /^(\d{1,7})(?:\.(\d{1,2}))?$/u;
+const CURRENCY_PREFIX = /^[¥￥]/u;
+const CURRENCY_SUFFIX = /(?:元|块|rmb|RMB|CNY)$/u;
+
+/** Turns full-width digits and the full-width dot into ASCII so `１２．５` parses like `12.5`. */
+function toHalfWidth(text: string): string {
+  return text.replace(/[０-９．]/gu, (character) => {
+    if (character === '．') return '.';
+    const fullWidthZero = '０'.codePointAt(0)!;
+    return String(character.codePointAt(0)! - fullWidthZero);
+  });
+}
+
+function invalid(reason: string): AmountParseResult {
+  return { ok: false, reason };
+}
+
+/** Parses `18`, `18.5`, `18.50`, `¥18.5` or `18.5元` into cents; rejects negatives, zero, exponents and more than two decimals. */
+export function parseAmountToCents(raw: string): AmountParseResult {
+  const normalized = toHalfWidth(raw.trim());
+  const withoutCurrency = normalized.replace(CURRENCY_PREFIX, '').replace(CURRENCY_SUFFIX, '').trim();
+  if (withoutCurrency.startsWith('-')) return invalid('金额不能为负数');
+  const match = AMOUNT_PATTERN.exec(withoutCurrency);
+  if (!match) return invalid('金额格式不正确，请写成 18 或 18.50（最多两位小数）');
+  const wholeYuan = Number(match[1]);
+  const fractionDigits = (match[2] ?? '').padEnd(2, '0');
+  const cents = wholeYuan * 100 + Number(fractionDigits);
+  if (cents === 0) return invalid('金额必须大于 0');
+  if (cents > MAX_ENTRY_CENTS) return invalid('单笔金额不能超过 ¥1000000.00');
+  return { ok: true, cents };
+}
+
+/** Formats cents as `¥12.50`. */
+export function formatCents(cents: number): string {
+  const wholeYuan = Math.floor(cents / 100);
+  const remainingCents = cents % 100;
+  return `¥${wholeYuan}.${String(remainingCents).padStart(2, '0')}`;
+}
+
+/** The text shown instead of an amount where other people can read the reply. */
+export const MASKED_AMOUNT = '¥***';