@zhin.js/plugin-ledger 1.0.1 → 1.0.3

package/src/store.ts

@@ -1,3 +1,4 @@
+import { resolveLocale, type Locale } from 'zhin.js/i18n';
 import type { DatabaseHostModel, DeliveryTarget, PluginDatabaseHost } from 'zhin.js';
 
 export const ENTRY_TABLE = 'ledger_entries';
@@ -20,6 +21,7 @@ export interface LedgerUserRecord {
   readonly ownerKey: string;
   readonly nextSeq: number;
   readonly reportEnabled: boolean;
+  readonly reportLocale?: Locale;
   readonly reportTarget: DeliveryTarget | undefined;
   readonly lastReportDate: string;
 }
@@ -38,9 +40,10 @@ export function defineLedgerTables(database: Pick<PluginDatabaseHost, 'define'>)
     owner_key: { type: 'text', nullable: false },
     next_seq: { type: 'integer', default: 1 },
     report_enabled: { type: 'integer', default: 0 },
+    report_locale: { type: 'text', length: 16, nullable: true },
     report_target: { type: 'text', default: '' },
     last_report_date: { type: 'text', default: '' },
-  });
+  }, { addColumns: ['report_locale'] });
   database.define(PRIVATE_TARGET_TABLE, {
     owner_key: { type: 'text', nullable: false },
     target: { type: 'text', nullable: false },
@@ -72,6 +75,7 @@ function toUser(row: Record<string, unknown>): LedgerUserRecord {
     ownerKey: String(row.owner_key),
     nextSeq: Number(row.next_seq ?? 1),
     reportEnabled: Number(row.report_enabled ?? 0) === 1,
+    reportLocale: resolveLocale(row.report_locale),
     reportTarget: parseTarget(row.report_target),
     lastReportDate: String(row.last_report_date ?? ''),
   };
@@ -97,7 +101,7 @@ export class LedgerStore {
 
   async getUser(ownerKey: string): Promise<LedgerUserRecord | undefined> {
     const rows = await this.#model(USER_TABLE)
-      .select('owner_key', 'next_seq', 'report_enabled', 'report_target', 'last_report_date')
+      .select('owner_key', 'next_seq', 'report_enabled', 'report_locale', 'report_target', 'last_report_date')
       .where({ owner_key: ownerKey });
     const first = rows[0];
     return first ? toUser(first) : undefined;
@@ -154,10 +158,11 @@ export class LedgerStore {
     await this.#model(ENTRY_TABLE).delete().where({ owner_key: ownerKey, seq });
   }
 
-  async setReport(ownerKey: string, enabled: boolean, target: DeliveryTarget | undefined, lastReportDate: string): Promise<void> {
+  async setReport(ownerKey: string, enabled: boolean, target: DeliveryTarget | undefined, lastReportDate: string, locale?: Locale): Promise<void> {
     await this.#ensureUser(ownerKey);
     await this.#model(USER_TABLE).update({
       report_enabled: enabled ? 1 : 0,
+      ...(enabled ? { report_locale: resolveLocale(locale) } : {}),
       report_target: target ? JSON.stringify(target) : '',
       last_report_date: lastReportDate,
     }).where({ owner_key: ownerKey });
@@ -184,7 +189,7 @@ export class LedgerStore {
 
   async listReportSubscribers(): Promise<LedgerUserRecord[]> {
     const rows = await this.#model(USER_TABLE)
-      .select('owner_key', 'next_seq', 'report_enabled', 'report_target', 'last_report_date')
+      .select('owner_key', 'next_seq', 'report_enabled', 'report_locale', 'report_target', 'last_report_date')
       .where({ report_enabled: 1 });
     return rows.map(toUser);
   }

package/src/tool-caller.ts

@@ -0,0 +1,101 @@
+import { resolveLocale, type Locale } from 'zhin.js/i18n';
+import { createDeliveryTarget, type DeliveryTarget } from 'zhin.js';
+import { adapterFeatureId, type AdapterIndex } from 'zhin.js/adapter';
+import { messages as t } from './i18n.js';
+import { LedgerInputError, ledgerOwnerKey, type LedgerCaller } from './identity.js';
+
+export type LedgerToolOrigin =
+  | Readonly<{
+      kind: 'im';
+      platform: string;
+      endpoint: string;
+      scope: 'private' | 'group' | 'channel';
+      sceneId: string;
+      messageId?: string;
+      threadId?: string;
+      conversation?: DeliveryTarget & Readonly<{ name?: string }>;
+    }>
+  | Readonly<{ kind: Exclude<string, 'im'>; [key: string]: unknown }>;
+
+export interface LedgerToolCallerContext {
+  readonly origin: LedgerToolOrigin;
+  readonly locale?: Locale;
+  readonly senderId?: string;
+  readonly principal?: Readonly<{ subjectId: string; roles: readonly string[] }>;
+  project?<T>(feature: typeof adapterFeatureId): T;
+}
+
+function isImOrigin(
+  origin: LedgerToolOrigin,
+): origin is Extract<LedgerToolOrigin, { readonly kind: 'im' }> {
+  return origin.kind === 'im';
+}
+
+function resolveToolConversation(context: LedgerToolCallerContext, locale: Locale): DeliveryTarget {
+  const origin = context.origin;
+  if (!isImOrigin(origin)) {
+    throw new LedgerInputError(t(locale, 'actor'));
+  }
+  let endpointId = origin.conversation?.endpoint.id ?? origin.endpoint;
+  if (typeof context.project === 'function') {
+    try {
+      const index = context.project<AdapterIndex>(adapterFeatureId);
+      if (index && typeof index.describe === 'function') {
+        const matches = index
+          .describe()
+          .filter(
+            (endpoint) =>
+              (String(endpoint.id) === origin.endpoint || endpoint.name === origin.endpoint) &&
+              index.clientAdapter(endpoint.id) === origin.platform,
+          );
+        if (matches.length === 1) {
+          endpointId = String(matches[0]!.id);
+        }
+      }
+    } catch {
+      // Fall back to origin endpoint when AdapterIndex projection is unavailable in lightweight contexts.
+    }
+  }
+  if (!endpointId) {
+    throw new LedgerInputError(t(locale, 'actor'));
+  }
+  if (origin.conversation) {
+    return createDeliveryTarget({
+      conversation: {
+        ...origin.conversation,
+        endpoint: { id: endpointId, adapter: origin.platform },
+      },
+    });
+  }
+  return createDeliveryTarget({
+    conversation: {
+      endpoint: { id: endpointId, adapter: origin.platform },
+      kind: origin.scope,
+      id: origin.sceneId,
+      ...(origin.threadId !== undefined ? { threadId: origin.threadId } : {}),
+    },
+  });
+}
+
+/** Builds a LedgerCaller from an Agent Tool execution context. */
+export function ledgerCallerFromTool(context: LedgerToolCallerContext): LedgerCaller {
+  const locale = resolveLocale(context.locale);
+  const senderId = (context.principal?.subjectId ?? context.senderId)?.trim();
+  if (!senderId) {
+    throw new LedgerInputError(t(locale, 'actor'));
+  }
+  const conversation = resolveToolConversation(context, locale);
+  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,
+    locale,
+    conversation,
+    privateTarget,
+    isPrivate,
+  };
+}