@arcote.tech/arc-chat 0.7.11 → 0.7.12

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arcote.tech/arc-chat",
   "type": "module",
-  "version": "0.7.11",
+  "version": "0.7.12",
   "private": false,
   "description": "Chat module with AI integration for Arc framework",
   "main": "./src/index.ts",
@@ -10,12 +10,12 @@
     "type-check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@arcote.tech/arc": "^0.7.11",
-    "@arcote.tech/arc-ai": "^0.7.11",
-    "@arcote.tech/arc-ai-voice": "^0.7.11",
-    "@arcote.tech/arc-auth": "^0.7.11",
-    "@arcote.tech/arc-ds": "^0.7.11",
-    "@arcote.tech/platform": "^0.7.11",
+    "@arcote.tech/arc": "^0.7.12",
+    "@arcote.tech/arc-ai": "^0.7.12",
+    "@arcote.tech/arc-ai-voice": "^0.7.12",
+    "@arcote.tech/arc-auth": "^0.7.12",
+    "@arcote.tech/arc-ds": "^0.7.12",
+    "@arcote.tech/platform": "^0.7.12",
     "lucide-react": ">=0.400.0",
     "react": ">=18.0.0",
     "typescript": "^5.0.0"

package/src/chat-builder.ts

@@ -55,6 +55,22 @@ export interface ChatReactComponentOptions {
 
 // ─── Chat Data ──────────────────────────────────────────────────
 
+/**
+ * Map snapshot token params (decoded payload of the token that protects this
+ * chat) to the scopeId we charge for an AI call. Consumers wire this via
+ * `.billTo(fn)`. Examples for typical setups:
+ *
+ *   .billTo(p => p.accountId)    // per-user billing
+ *   .billTo(p => p.workspaceId)  // per-workspace billing
+ *
+ * Called inside the ai-generation-listener with `ctx.$auth.params` (which
+ * is the decoded payload of the token snapshotted at `messageSent` emit
+ * time — i.e. whatever token the chat's `.protectBy(...)` is configured
+ * with). The returned string becomes the `_id` of the ledger row that gets
+ * debited.
+ */
+export type BillToFn = (tokenParams: Record<string, any>) => string;
+
 export interface ArcChatData {
   name: string;
   identifyBy: ArcId<any> | null;
@@ -67,6 +83,8 @@ export interface ArcChatData {
   tools: ArcToolAny[];
   maxExecutionCount: number;
   toolChoice: "auto" | "required" | { type: "function"; name: string };
+  alias: string | null;
+  billTo: BillToFn | null;
 }
 
 const defaultChatData = {
@@ -81,6 +99,8 @@ const defaultChatData = {
   tools: [],
   maxExecutionCount: 10,
   toolChoice: "auto" as const,
+  alias: null,
+  billTo: null,
 } as const satisfies ArcChatData;
 
 type DefaultChatData = typeof defaultChatData;
@@ -164,6 +184,41 @@ export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
     } as any);
   }
 
+  /**
+   * Billing alias for this chat — written to the `usageRecorded` event
+   * payload (see `@arcote.tech/arc-ai`). Defaults to chat `name`. Override
+   * when you want consistent reporting across renames or to group multiple
+   * chats under one alias for admin SQL reports.
+   *
+   *   chat("identityConsultation").alias("chat-identity")...
+   */
+  alias<const A extends string>(alias: A) {
+    return new ArcChat<Merge<Data, { alias: A }>>({
+      ...this.data,
+      alias,
+    } as any);
+  }
+
+  /**
+   * Decide which scopeId to bill for an AI call made from this chat.
+   *
+   * Called with the decoded params of the token snapshotted at `messageSent`
+   * emit time (i.e. the token used in `.protectBy(...)`). The returned string
+   * becomes the `_id` of the row in `creditLedger` that gets debited.
+   *
+   *   .billTo(p => p.accountId)    // per-user billing
+   *   .billTo(p => p.workspaceId)  // per-workspace billing
+   *
+   * Required when `.ai(...)` config has billing wired — `build()` throws
+   * otherwise. Without billing, this method is a no-op.
+   */
+  billTo(fn: BillToFn) {
+    return new ArcChat<Merge<Data, { billTo: BillToFn }>>({
+      ...this.data,
+      billTo: fn,
+    } as any);
+  }
+
   createTool<const N extends string>(name: N) {
     type IdType = Data["identifyBy"] extends ArcId<any>
       ? $type<Data["identifyBy"]>
@@ -195,6 +250,8 @@ export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
       tools,
       maxExecutionCount,
       toolChoice,
+      alias: aliasOverride,
+      billTo,
     } = this.data;
 
     if (!name) throw new Error("ArcChat: name is required");
@@ -202,6 +259,13 @@ export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
     if (!accountId) throw new Error("ArcChat: accountId is required");
     if (!userToken) throw new Error("ArcChat: userToken is required");
     if (!aiConfig) throw new Error("ArcChat: ai is required");
+    // Billing wired but no `.billTo(...)` would silently skip recordUsage —
+    // forbid that. Consumer must explicitly decide which scopeId to charge.
+    if (aiConfig.recordUsage && !billTo) {
+      throw new Error(
+        `ArcChat "${name}": ai() factory has billing wired but chat is missing .billTo(...) — declare how to map snapshot token params to a billing scope, e.g. .billTo(p => p.accountId).`,
+      );
+    }
 
     const messageId = createMessageId({ name });
 
@@ -244,13 +308,14 @@ export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
     const serverTools = tools.filter((t) => t.isServerTool);
     const interactiveTools = tools.filter((t) => t.isInteractiveTool);
 
-    // Add ledger element to mutation deps if billing configured
-    const billingElements: ArcContextElement<any>[] = [];
-    if (aiConfig.billing) {
-      for (const el of aiConfig.billing.ledger.elements) {
+    // Add usage-registry aggregate to listener mutate deps so `recordUsage`
+    // (which calls `ctx.mutate(registry).recordUsage(...)`) compiles and runs.
+    // Ledger view is a read-only projection — consumer queries it from React,
+    // listener never writes to it directly.
+    if (aiConfig.usageRegistry) {
+      for (const el of aiConfig.usageRegistry.elements) {
         if (!allMutationElements.includes(el)) allMutationElements.push(el);
         if (!allQueryElements.includes(el)) allQueryElements.push(el);
-        billingElements.push(el);
       }
     }
 
@@ -265,6 +330,9 @@ export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
       allMutationElements,
       maxExecutionCount,
       toolChoice: toolChoice !== "auto" ? toolChoice : undefined,
+      alias: aliasOverride ?? name,
+      recordUsage: aiConfig.recordUsage,
+      billTo: billTo ?? undefined,
     };
 
     const aiListener = createAiGenerationListener(listenerConfig);

package/src/listeners/ai-generation-listener.ts

@@ -28,6 +28,37 @@ export interface AiGenerationListenerConfig {
   allMutationElements: ArcContextElement<any>[];
   maxExecutionCount: number;
   toolChoice?: "auto" | "required" | { type: "function"; name: string };
+  /**
+   * Billing alias for this chat — written to the `usageRecorded` event
+   * payload so admin reports can attribute cost back to which chat (e.g.
+   * `"chat-identity"`, `"chat-create-content"`). Defaults to `name` if the
+   * builder didn't override via `.alias(...)`.
+   */
+  alias?: string;
+  /**
+   * Optional billing hook from `ai()` factory. Called after every
+   * `completeAssistantTurn` (each turn, including those that close with
+   * tool calls) so the credit ledger view sees consistent usage events.
+   * No-op when undefined (ai() built without `billing` config).
+   */
+  recordUsage?: (
+    ctx: any,
+    params: {
+      scopeId: string;
+      alias: string;
+      model: string;
+      usage: import("@arcote.tech/arc-ai").TokenUsage;
+      metadata?: Record<string, unknown>;
+    },
+  ) => Promise<void>;
+  /**
+   * Consumer-supplied function from chat-builder's `.billTo(...)` — maps
+   * decoded params of the chat's protection token (snapshotted at
+   * `messageSent` emit time) to the ledger scopeId we charge. Required when
+   * `recordUsage` is set (chat-builder enforces this at build time), so the
+   * listener can treat the pair as always-present in the call site.
+   */
+  billTo?: (tokenParams: Record<string, any>) => string;
 }
 
 // ─── History reconstruction ─────────────────────────────────────
@@ -195,6 +226,13 @@ interface RunLoopConfig {
    *  lecieć. Następne iteracje (multi-turn po server tool exec) tworzą fresh
    *  rows. */
   preCreatedAssistantMessageId?: string;
+  /** Billing alias — written to `usageRecorded` event payload. Optional;
+   *  no-op when paired `recordUsage` is undefined. */
+  alias?: string;
+  /** Billing hook — see `AiGenerationListenerConfig.recordUsage`. */
+  recordUsage?: AiGenerationListenerConfig["recordUsage"];
+  /** Token-params → scopeId mapper from chat-builder `.billTo(...)`. */
+  billTo?: AiGenerationListenerConfig["billTo"];
 }
 
 async function runGenerationLoop(config: RunLoopConfig) {
@@ -339,15 +377,46 @@ async function runGenerationLoop(config: RunLoopConfig) {
 
       // Close the turn row — same row that was opened above. Final blocks
       // are the SINGLE persistent write of message content in this turn.
-      // Intermediate turns (gdy mamy tool calls) carry blocks + responseId;
-      // ostatni turn nosi też usage.
+      // Usage zapisywane ZAWSZE (intermediate tool turns też zużywają tokeny
+      // i muszą być rozliczone w `recordUsage` poniżej; klient dostaje pełen
+      // history of cost per turn from message rows).
       await ctx.mutate(messageElement).completeAssistantTurn({
         messageId: currentTurnId!,
         blocks: JSON.stringify(result.blocks),
         previousResponseId: result.responseId,
-        usage: hasToolCalls ? undefined : JSON.stringify(result.usage),
+        usage: JSON.stringify(result.usage),
       });
 
+      // Billing hook — emit usageRecorded event for the credit ledger view.
+      // Called after `completeAssistantTurn` so the message row exists in DB
+      // before its cost is attributed.
+      //
+      // chat-builder enforces `.billTo()` is present whenever `recordUsage`
+      // is wired, so the only legitimate "skip" path is "billing not
+      // configured at all" — both undefined. We still guard defensively.
+      if (config.recordUsage && config.alias && config.billTo) {
+        const billingScopeId = config.billTo(
+          ((ctx as any).$auth?.params as Record<string, any>) ?? {},
+        );
+        try {
+          await config.recordUsage(ctx, {
+            scopeId: billingScopeId,
+            alias: config.alias,
+            model,
+            usage: result.usage,
+            metadata: {
+              messageId: currentTurnId!,
+              sessionId,
+              turnIndex: executionCount,
+              chatScopeId: scopeId,
+            },
+          });
+        } catch (err) {
+          // Best-effort: billing failure shouldn't break generation.
+          console.error("[arc-chat] recordUsage failed:", err);
+        }
+      }
+
       // Tear down the in-memory stream: broadcast `done` do subscriberów,
       // close controllery, drop registry entry po grace window. Klient z
       // `done` flippuje isStreaming=false i renderuje final blocks z DB.
@@ -516,6 +585,9 @@ export function createAiGenerationListener(config: AiGenerationListenerConfig) {
         maxExecutionCount,
         toolChoice: config.toolChoice,
         instruction,
+        alias: config.alias,
+        recordUsage: config.recordUsage,
+        billTo: config.billTo,
         preCreatedAssistantMessageId: (
           event.payload as { assistantMessageId?: string }
         ).assistantMessageId,
@@ -596,6 +668,9 @@ export function createAiResumeListener(config: AiGenerationListenerConfig) {
         maxExecutionCount,
         toolChoice: config.toolChoice,
         instruction,
+        alias: config.alias,
+        recordUsage: config.recordUsage,
+        billTo: config.billTo,
         preCreatedAssistantMessageId: (
           event.payload as { assistantMessageId?: string }
         ).assistantMessageId,
@@ -688,6 +763,9 @@ export function createAiRetryListener(config: AiGenerationListenerConfig) {
         maxExecutionCount,
         toolChoice: config.toolChoice,
         instruction,
+        alias: config.alias,
+        recordUsage: config.recordUsage,
+        billTo: config.billTo,
         preCreatedAssistantMessageId: assistantMsgId,
       });
     });