@firstlovecenter/ai-chat 0.1.0

package/dist/types-DNwFvL-C.d.ts

@@ -0,0 +1,268 @@
+import { GoogleAuth } from 'google-auth-library';
+
+/**
+ * Tool typing for the agent loop.
+ *
+ * `ToolContext<S>` is the per-request "session" handed to every tool. It
+ * carries the resolved Scope (so tools can inject scope filters without
+ * trusting their own arguments) and a per-session view suffix (so SQL-ish
+ * tools can point the LLM at session-scoped views). The Scope shape itself
+ * is opaque to this package — `S` is whatever the host configures.
+ *
+ * `ToolDefinition` is what we hand to the model adapter plus the function
+ * that backs the tool name. The agent loop dispatches on `name` and calls
+ * `execute(input, ctx)`; the result is JSON-serialised back to the model.
+ */
+type ToolContext<S = unknown> = {
+    /** Host-supplied scope (RBAC / tenancy). The package never inspects the shape. */
+    scope: S;
+    /** Stable per-conversation id (string). Tools may use this for session-scoped views. */
+    sessionId: string;
+    /** Short human label for diagnostics — e.g. "Ghana", "all 8 countries". */
+    scopeSummary: string;
+    /** Number of structured tool calls made before `present` was invoked. */
+    toolCallCount: number;
+};
+type ToolSchema = {
+    name: string;
+    description: string;
+    /** JSON Schema. The package's Vertex Gemini adapter normalises this; the Vercel adapter converts to Zod. */
+    input_schema: Record<string, unknown>;
+};
+type ToolResult = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+type ToolDefinition<I = unknown, S = unknown> = {
+    schema: ToolSchema;
+    execute(input: I, ctx: ToolContext<S>): Promise<ToolResult>;
+};
+/** The terminal tool that closes the agent loop. The host's tool registry MUST include it. */
+declare const TERMINAL_TOOL_NAME = "present";
+declare function ok(data: unknown): ToolResult;
+declare function err(code: string, message: string): ToolResult;
+type ChartSpec = {
+    type: 'line' | 'bar' | 'stacked_bar' | 'pie';
+    x: string;
+    y: string | string[];
+    series?: string;
+};
+type Block = {
+    kind: 'paragraph_brief';
+    topic: string;
+    key_facts: string[];
+} | {
+    kind: 'list';
+    style: 'bullet' | 'numbered';
+    items: string[];
+    title?: string;
+} | {
+    kind: 'chart';
+    title: string;
+    spec: ChartSpec;
+    data: Array<Record<string, unknown>>;
+} | {
+    kind: 'table';
+    title: string;
+    columns: string[];
+    rows: unknown[][];
+} | {
+    kind: 'callout';
+    tone: 'info' | 'warn' | 'success';
+    text: string;
+};
+type PresentPayload = {
+    blocks: Block[];
+    raw_numbers: Record<string, number | string>;
+};
+type SystemBlock = {
+    text: string;
+    /**
+     * Mark for ephemeral prompt caching where the provider supports it.
+     * Anthropic translates this to `cache_control: ephemeral`; Gemini ignores
+     * it (Vertex auto-caches stable prefixes). Both still see the same text.
+     */
+    cached?: boolean;
+};
+
+/**
+ * Ports — the contract between this package and any host that consumes it.
+ *
+ * Every project-specific concern (auth, scope, persistence, tools, credentials)
+ * crosses the boundary as a typed port the host implements and passes into
+ * `configureAiChat({...})`. The package itself has zero knowledge of the
+ * host's database, RBAC model, or environment.
+ *
+ * Domain types (ChatSession, ChatMessage, AiSettings, PresentPayload, Block)
+ * are pure TS — no ORM coupling. The Drizzle and Prisma adapters each map
+ * their respective row types into these shapes so callers see one contract
+ * regardless of the chosen ORM.
+ */
+
+type ChatSession = {
+    id: number;
+    userId: number;
+    title: string;
+    createdAt: Date;
+    updatedAt: Date;
+};
+type ChatMessageRole = 'user' | 'assistant';
+/**
+ * One message turn. For 'user' rows, `question` carries the raw question text.
+ * For 'assistant' rows, `blocks` holds the structured PresentPayload and
+ * `prose` holds any paragraph_brief prose collected from the streamed
+ * narrator. `errorJson` is set when an assistant turn failed mid-stream.
+ */
+type ChatMessage = {
+    id: number;
+    sessionId: number;
+    role: ChatMessageRole;
+    question: string | null;
+    blocks: unknown | null;
+    prose: unknown | null;
+    errorJson: unknown | null;
+    createdAt: Date;
+};
+/**
+ * Singleton row controlling the active tool-calling provider, the Vertex
+ * region, and which chat UI (Custom vs. Vercel) renders globally. All three
+ * fields are validated at runtime against the registries the host configures
+ * — they are not enums in the package's types so consumers can register
+ * additional providers / interfaces without a schema change.
+ */
+type AiSettings = {
+    toolProvider: string;
+    gcpLocation: string;
+    chatInterface: string;
+    updatedAt: Date | null;
+    updatedByUserId: number | null;
+};
+/**
+ * The host's resolved Scope (org/tenant/RBAC shape) is opaque to the package.
+ * `S` is whatever the host wants — typically a discriminated union with at
+ * least `userId: number` plus role/tenancy fields.
+ */
+type AuthOk<S> = {
+    ok: true;
+    scope: S;
+    userId: number;
+};
+type AuthFail = {
+    ok: false;
+    response: Response;
+};
+type AuthResult<S> = AuthOk<S> | AuthFail;
+type AuthPort<S = unknown> = {
+    /**
+     * Resolve the calling user from the request. Returning `{ ok: false }`
+     * lets the route hand back the prepared 401/403 response untouched.
+     */
+    requireAuth(req: Request): Promise<AuthResult<S>>;
+    /**
+     * Predicate the admin-settings route uses to gate writes. Hosts that
+     * don't model admins can return `() => true` if they trust their own
+     * routing layer.
+     */
+    isSuperAdmin(scope: S): boolean;
+};
+type ScopePort<S = unknown> = {
+    /** Short label rendered in the chat UI (e.g. "Ghana", "All countries"). */
+    resolveScopeLabel(scope: S): Promise<string>;
+    /** Longer narrative the system prompt uses to describe the data slice. */
+    buildScopeSummary(scope: S): Promise<string>;
+};
+type ToolsPort = {
+    /**
+     * Map of tool name → definition. Keys must match `definition.schema.name`.
+     * Must include the terminal `present` tool — the agent loop refuses to
+     * end a turn without it.
+     */
+    tools: Record<string, ToolDefinition>;
+    /**
+     * Build the ordered list of system blocks for one agent run. The host
+     * decides how much of the prompt is project-specific (schema doc,
+     * semantic-layer doc, scope summary, etc.). Blocks marked `cached: true`
+     * become Anthropic ephemeral cache markers and Vertex prefix-cache hints.
+     */
+    buildSystemBlocks(ctx: ToolContext): Promise<SystemBlock[]>;
+};
+type VertexPort = {
+    projectId: string;
+    /** e.g. 'us-east5' or 'global' — used unless `aiSettings.gcpLocation` overrides per-request. */
+    defaultLocation: string;
+    /**
+     * A constructed `GoogleAuth` instance. Any auth scheme that yields one
+     * works (ADC, Workload Identity Federation, split-key env vars,
+     * Secret Manager, etc.). The package never reads `process.env.GCP_*`.
+     */
+    auth: GoogleAuth;
+    /** Vertex model IDs pinned by the host (orgs pin their own versions). */
+    modelIds: {
+        claude: string;
+        gemini: string;
+    };
+};
+type LoggerPort = {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+};
+type CreateSessionInput = {
+    userId: number;
+    title: string;
+};
+type AppendMessageInput = {
+    sessionId: number;
+    role: ChatMessageRole;
+    question?: string | null;
+    blocks?: unknown | null;
+    prose?: unknown | null;
+    errorJson?: unknown | null;
+};
+type ListSessionsOpts = {
+    limit?: number;
+};
+type AiSettingsPatch = {
+    toolProvider?: string;
+    gcpLocation?: string;
+    chatInterface?: string;
+};
+/**
+ * The whole reason this package is ORM-agnostic. Implemented by:
+ *   - createDrizzlePersistence (src/adapters/drizzle/)
+ *   - createPrismaPersistence  (src/adapters/prisma/)
+ *   - createMemoryPersistence  (src/adapters/memory/, internal test use)
+ *
+ * Routes, agent loop, and UI never touch ORMs directly — they only call
+ * methods on this port. A parameterized contract test runs the same
+ * assertions against all three adapters to keep them in sync.
+ */
+type PersistencePort = {
+    createSession(input: CreateSessionInput): Promise<ChatSession>;
+    /** Returns null when the session doesn't exist OR doesn't belong to this user. */
+    getSession(id: number, userId: number): Promise<ChatSession | null>;
+    listSessionsForUser(userId: number, opts?: ListSessionsOpts): Promise<ChatSession[]>;
+    /** No-op when session doesn't exist or doesn't belong to user — caller asserted authorisation. */
+    updateSession(id: number, userId: number, patch: {
+        title?: string;
+    }): Promise<void>;
+    deleteSession(id: number, userId: number): Promise<void>;
+    appendMessage(input: AppendMessageInput): Promise<ChatMessage>;
+    listMessagesForSession(sessionId: number, userId: number): Promise<ChatMessage[]>;
+    /** Returns the singleton row, applying defaults if it's never been written. */
+    getAiSettings(): Promise<AiSettings>;
+    /**
+     * Upsert. Validates `toolProvider` and `chatInterface` against the runtime
+     * registries before writing — invalid values throw before SQL is issued.
+     */
+    updateAiSettings(patch: AiSettingsPatch, byUserId: number): Promise<AiSettings>;
+};
+
+export { type AuthPort as A, type Block as B, type ChartSpec as C, type LoggerPort as L, type PresentPayload as P, type SystemBlock as S, type ToolSchema as T, type VertexPort as V, type ToolContext as a, type ToolDefinition as b, type PersistencePort as c, type ScopePort as d, type ToolsPort as e, type AiSettings as f, type AiSettingsPatch as g, type AppendMessageInput as h, type AuthFail as i, type AuthOk as j, type AuthResult as k, type ChatMessage as l, type ChatMessageRole as m, type ChatSession as n, type CreateSessionInput as o, type ListSessionsOpts as p, TERMINAL_TOOL_NAME as q, type ToolResult as r, err as s, ok as t };