@arcote.tech/arc-chat 0.5.1 → 0.5.5

package/src/chat-builder.ts

@@ -1,99 +1,292 @@
-import { context, type ArcContextElement, type ArcId } from "@arcote.tech/arc";
+import {
+  context,
+  arcFunction,
+  type ArcContextElement,
+  type ArcId,
+  type ArcFunction,
+  type DefaultFunctionData,
+  type Merge,
+  type $type,
+} from "@arcote.tech/arc";
 import type { AccountId, Token } from "@arcote.tech/arc-auth";
-import type { AIConfig } from "@arcote.tech/arc-ai";
-import type { ArcToolAny, ToolContext } from "@arcote.tech/arc-ai";
+import type { AIConfig, ArcToolAny } from "@arcote.tech/arc-ai";
+import { tool as createToolFactory } from "@arcote.tech/arc-ai";
+import type { ArcTokenAny } from "@arcote.tech/arc";
+import type { FnProtection, FnProtectionCheck } from "@arcote.tech/arc";
 import { createMessageId, createMessageAggregate } from "./aggregates/message";
-import { createAiGenerationListener } from "./listeners/ai-generation-listener";
+import { createAiGenerationListener, createAiResumeListener } from "./listeners/ai-generation-listener";
 import { createChatStreamRoute } from "./routes/chat-stream-route";
-import { createToolResultsRoute } from "./routes/tool-results-route";
+import { createChatComponent } from "./react/chat-component";
+import type { ChatLabels } from "@arcote.tech/arc-ds";
+import type { ComponentType, ReactNode } from "react";
 
-// ─── Prepare Callback ───────────────────────────────────────────
-
-export interface PrepareContext {
-  query: (element: ArcContextElement<any>) => any;
-  mutate: (element: ArcContextElement<any>) => any;
+export interface ChatReactComponentOptions {
+  /** Show the model selector dropdown in ChatInput. Default true. */
+  showModelSelector?: boolean;
+  /** Show the web search toggle in ChatInput. Default true. */
+  showWebSearch?: boolean;
+  /**
+   * Render slot for ChatInput's send button. Receives `onClick` and
+   * `disabled` — caller renders its own button (e.g. branded with a logo).
+   */
+  renderSendButton?: (props: {
+    onClick: () => void;
+    disabled: boolean;
+  }) => ReactNode;
+  /** Partial overrides for chat i18n labels. Falls back to English defaults. */
+  labels?: Partial<ChatLabels>;
 }
 
-export interface PrepareParams {
-  content: string;
-  identifyBy: string;
-  model: string;
-}
+// ─── Chat Data ──────────────────────────────────────────────────
 
-export interface PrepareResult {
-  instructions: string;
-  tools?: ArcToolAny[];
-  clientTools?: ArcToolAny[];
+export interface ArcChatData {
+  name: string;
+  identifyBy: ArcId<any> | null;
+  accountId: AccountId | null;
+  userToken: Token | null;
+  protectBy: Token | null;
+  protectByCheck: ((p: any) => any) | null;
+  ai: AIConfig | null;
+  instruction: ArcFunction<any> | null;
+  tools: ArcToolAny[];
+  maxExecutionCount: number;
+  toolChoice: "auto" | "required" | { type: "function"; name: string };
 }
 
-// ─── Chat Factory ───────────────────────────────────────────────
+const defaultChatData = {
+  name: "",
+  identifyBy: null,
+  accountId: null,
+  userToken: null,
+  protectBy: null,
+  protectByCheck: null,
+  ai: null,
+  instruction: null,
+  tools: [],
+  maxExecutionCount: 10,
+  toolChoice: "auto" as const,
+} as const satisfies ArcChatData;
 
-export function chat(config: {
-  name: string;
-  identifyBy: ArcId<any>;
-  accountId: AccountId;
-  userToken: Token;
-  ai: AIConfig;
-  tools?: ArcToolAny[];
-  clientTools?: ArcToolAny[];
-  prepare?: ((ctx: PrepareContext, params: PrepareParams) => Promise<PrepareResult>) | false;
-  maxExecutionCount?: number;
-}) {
-  const messageId = createMessageId({ name: config.name });
-
-  const Message = createMessageAggregate({
-    name: config.name,
-    messageId,
-    scopeId: config.identifyBy,
-    accountId: config.accountId,
-    userToken: config.userToken,
-  });
-
-  // Collect all mutation elements from server tools for listener registration
-  const allTools = config.tools ?? [];
-  const allMutationElements: ArcContextElement<any>[] = [];
-  for (const tool of allTools) {
-    for (const el of tool.mutationElements) {
-      if (!allMutationElements.includes(el)) {
-        allMutationElements.push(el);
+type DefaultChatData = typeof defaultChatData;
+
+// ─── ArcChat Builder ────────────────────────────────────────────
+
+export class ArcChat<const Data extends ArcChatData = DefaultChatData> {
+  readonly data: Data;
+
+  constructor(data: Data) {
+    this.data = data;
+  }
+
+  identifyBy<Id extends ArcId<any>>(id: Id) {
+    return new ArcChat<Merge<Data, { identifyBy: Id }>>({
+      ...this.data,
+      identifyBy: id,
+    } as any);
+  }
+
+  accountId(id: AccountId) {
+    return new ArcChat<Merge<Data, { accountId: typeof id }>>({
+      ...this.data,
+      accountId: id,
+    } as any);
+  }
+
+  userToken(token: Token) {
+    return new ArcChat<Merge<Data, { userToken: typeof token }>>({
+      ...this.data,
+      userToken: token,
+    } as any);
+  }
+
+  protectBy<T extends ArcTokenAny>(token: T, check: FnProtectionCheck<T>) {
+    return new ArcChat<Merge<Data, { protectBy: T; protectByCheck: typeof check }>>({
+      ...this.data,
+      protectBy: token,
+      protectByCheck: check,
+    } as any);
+  }
+
+  ai(config: AIConfig) {
+    return new ArcChat<Merge<Data, { ai: AIConfig }>>({
+      ...this.data,
+      ai: config,
+    } as any);
+  }
+
+  instruction(
+    configure: (fn: ArcFunction<DefaultFunctionData>) => ArcFunction<any>,
+  ) {
+    const instructionFn = configure(arcFunction());
+    return new ArcChat<Merge<Data, { instruction: typeof instructionFn }>>({
+      ...this.data,
+      instruction: instructionFn,
+    } as any);
+  }
+
+  maxExecutionCount(count: number) {
+    return new ArcChat<Merge<Data, { maxExecutionCount: typeof count }>>({
+      ...this.data,
+      maxExecutionCount: count,
+    } as any);
+  }
+
+  toolChoice(choice: "auto" | "required" | { type: "function"; name: string }) {
+    return new ArcChat<Merge<Data, { toolChoice: typeof choice }>>({
+      ...this.data,
+      toolChoice: choice,
+    } as any);
+  }
+
+  createTool<const N extends string>(name: N) {
+    type IdType = Data["identifyBy"] extends ArcId<any>
+      ? $type<Data["identifyBy"]>
+      : string;
+    const t = createToolFactory(name);
+    if (this.data.identifyBy) {
+      return t.identifyBy(this.data.identifyBy) as any as ReturnType<typeof t.identifyBy> & { __brand: IdType };
+    }
+    return t as any;
+  }
+
+  useTools<Tools extends ArcToolAny[]>(tools: Tools) {
+    return new ArcChat<Merge<Data, { tools: Tools }>>({
+      ...this.data,
+      tools,
+    } as any);
+  }
+
+  build() {
+    const {
+      name,
+      identifyBy,
+      accountId,
+      userToken,
+      protectBy: protectByToken,
+      protectByCheck,
+      ai: aiConfig,
+      instruction: instructionFn,
+      tools,
+      maxExecutionCount,
+      toolChoice,
+    } = this.data;
+
+    if (!name) throw new Error("ArcChat: name is required");
+    if (!identifyBy) throw new Error("ArcChat: identifyBy is required");
+    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");
+
+    const messageId = createMessageId({ name });
+
+    const Message = createMessageAggregate({
+      name,
+      messageId,
+      scopeId: identifyBy,
+      accountId,
+      userToken: protectByToken ?? userToken,
+      // Forward consumer's protectBy check so chats with non-workspace
+      // identifyBy (e.g. `contentTopicId`) can supply a custom scope
+      // restriction instead of inheriting the default
+      // `{ scopeId: p.workspaceId }` which only makes sense for
+      // workspace-scoped chats.
+      protectCheck: protectByCheck as
+        | ((p: any) => Record<string, unknown>)
+        | undefined
+        ?? undefined,
+    });
+
+    // Collect query/mutate from instruction + tools
+    const allQueryElements: ArcContextElement<any>[] = [];
+    const allMutationElements: ArcContextElement<any>[] = [];
+
+    if (instructionFn) {
+      for (const el of instructionFn.data.queryElements || []) {
+        if (!allQueryElements.includes(el)) allQueryElements.push(el);
+      }
+    }
+
+    for (const t of tools) {
+      for (const el of t.queryElements) {
+        if (!allQueryElements.includes(el)) allQueryElements.push(el);
+      }
+      for (const el of t.mutationElements) {
+        if (!allMutationElements.includes(el)) allMutationElements.push(el);
       }
     }
+
+    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) {
+        if (!allMutationElements.includes(el)) allMutationElements.push(el);
+        if (!allQueryElements.includes(el)) allQueryElements.push(el);
+        billingElements.push(el);
+      }
+    }
+
+    const listenerConfig = {
+      name,
+      messageElement: Message,
+      resolveProvider: aiConfig.resolveProvider,
+      instruction: instructionFn ?? undefined,
+      serverTools,
+      interactiveTools,
+      allQueryElements,
+      allMutationElements,
+      maxExecutionCount,
+      toolChoice: toolChoice !== "auto" ? toolChoice : undefined,
+    };
+
+    const aiListener = createAiGenerationListener(listenerConfig);
+    const aiResumeListener = createAiResumeListener(listenerConfig);
+
+    const streamRoute = createChatStreamRoute({
+      name,
+      userToken,
+    });
+
+    const elements: ArcContextElement<any>[] = [
+      Message,
+      aiListener,
+      aiResumeListener,
+      streamRoute,
+    ];
+
+    function toReactComponent(
+      options: ChatReactComponentOptions = {},
+    ): ComponentType<{ scope: any; identifyBy: string }> {
+      return createChatComponent({
+        chatName: name,
+        tools,
+        messageElementName: `${name}Messages`,
+        showModelSelector: options.showModelSelector,
+        showWebSearch: options.showWebSearch,
+        renderSendButton: options.renderSendButton,
+        labels: options.labels,
+      });
+    }
+
+    return {
+      context: context(elements),
+      elements,
+      messageId,
+      Message,
+      toReactComponent,
+    };
   }
+}
+
+// ─── Factory ────────────────────────────────────────────────────
 
-  const aiListener = createAiGenerationListener({
-    name: config.name,
-    messageElement: Message,
-    resolveProvider: config.ai.resolveProvider,
-    prepare: config.prepare || undefined,
-    tools: allTools,
-    clientTools: config.clientTools ?? [],
-    toolMutationElements: allMutationElements,
-    maxExecutionCount: config.maxExecutionCount ?? 10,
-  });
-
-  const streamRoute = createChatStreamRoute({
-    name: config.name,
-    userToken: config.userToken,
-  });
-
-  const toolResultsRoute = createToolResultsRoute({
-    name: config.name,
-    userToken: config.userToken,
-  });
-
-  const elements: ArcContextElement<any>[] = [
-    Message,
-    aiListener,
-    streamRoute,
-    toolResultsRoute,
-  ];
-
-  return {
-    context: context(elements),
-    elements,
-    messageId,
-    Message,
-  };
+export function chat<const Name extends string>(name: Name) {
+  return new ArcChat<Merge<DefaultChatData, { name: Name }>>({
+    ...defaultChatData,
+    name,
+  } as any);
 }
 
-export type ChatConfig = ReturnType<typeof chat>;
+export type ChatConfig = ReturnType<ArcChat<any>["build"]>;

package/src/index.ts

@@ -1,6 +1,6 @@
 // --- Builder API ---
-export { chat } from "./chat-builder";
-export type { ChatConfig, PrepareContext, PrepareParams, PrepareResult } from "./chat-builder";
+export { chat, ArcChat } from "./chat-builder";
+export type { ChatConfig, ArcChatData, ChatReactComponentOptions } from "./chat-builder";
 
 // --- Aggregate factories & types ---
 export { createMessageAggregate, createMessageId } from "./aggregates/message";
@@ -20,24 +20,6 @@ export type { AiGenerationListenerConfig } from "./listeners/ai-generation-liste
 
 // --- Routes ---
 export { createChatStreamRoute } from "./routes/chat-stream-route";
-export { createToolResultsRoute } from "./routes/tool-results-route";
 
-// --- React components & hooks ---
-export {
-  Chat,
-  ChatMessage,
-  ChatInput,
-  QuestionTabs,
-  ToolUseBlock,
-  useChat,
-} from "./react";
-export type {
-  ChatMessageData,
-  ChatModel,
-  SendMessageOptions,
-  ToolUse,
-  Question,
-  QuestionAnswers,
-  UseChatConfig,
-  UseChatReturn,
-} from "./react";
+// --- Reusable tools ---
+export { askQuestions } from "./tools/ask-questions";