@27works/chat-core 0.1.0

package/dist/server/index.d.ts

@@ -0,0 +1,227 @@
+import { ToolSet, UIMessageStreamWriter, Tool, ToolExecutionOptions } from 'ai';
+import { Ratelimit } from '@upstash/ratelimit';
+import * as _supabase_supabase_js from '@supabase/supabase-js';
+
+/**
+ * Fetch a chat session and validate ownership in one call.
+ *
+ * @param {string} chatId
+ * @param {Object} options
+ * @param {string} options.select - Columns to select (default: '*')
+ * @param {string} options.accessMode - 'owner-only' | 'owner-or-public' | 'none'
+ * @param {string} options.forbiddenMessage - Custom 403 message
+ * @returns {{ chat: Object, ownership: Object }}
+ */
+declare function fetchChatWithOwnership(chatId: string, options?: {
+    select: string;
+    accessMode: string;
+    forbiddenMessage: string;
+}): {
+    chat: any;
+    ownership: any;
+};
+
+declare function createRagHandler({ model, embeddingModel, systemPrompt, tools, toolHandlers, useCache, ragOptions }: {
+    model: any;
+    embeddingModel: any;
+    systemPrompt: any;
+    tools: any;
+    toolHandlers?: {};
+    useCache?: boolean;
+    ragOptions?: {};
+}): {
+    POST: (req: any) => Promise<Response>;
+};
+
+/**
+ * Creates a POST handler that proxies link-click beacons from the browser
+ * to Caruuto, server-to-server, with the project's API key — sendBeacon
+ * can't carry custom headers, so the browser can't call Caruuto directly.
+ * Mirrors createRagHandler's factory shape so every consuming app gets the
+ * same proxy with no per-app logic.
+ *
+ * Always responds 204: sendBeacon discards the response, and a tracking
+ * failure must never surface to the user — errors are logged and swallowed.
+ */
+declare function createLinkClickHandler(): {
+    POST: (req: any) => Promise<Response>;
+};
+
+declare function handleAPIError(error: any): Response;
+declare namespace apiErrors {
+    function rateLimit(retryAfter?: number): {
+        message: string;
+        code: string;
+        statusCode: number;
+        retryAfter: number;
+    };
+    function notFound(resource?: string): {
+        message: string;
+        code: string;
+        statusCode: number;
+    };
+    function validation(message: any): {
+        message: any;
+        code: string;
+        statusCode: number;
+    };
+    function unauthorized(): {
+        message: string;
+        code: string;
+        statusCode: number;
+    };
+    function forbidden(message?: string): {
+        message: string;
+        code: string;
+        statusCode: number;
+    };
+    function openai(_originalError: any): {
+        message: string;
+        code: string;
+        statusCode: number;
+    };
+    function database(_originalError: any): {
+        message: string;
+        code: string;
+        statusCode: number;
+    };
+}
+
+/**
+ * Normalize question text for consistent caching.
+ */
+declare function normalizeQuestion(text: any): string;
+/**
+ * Create SHA-256 hash of normalized question + model ID.
+ * modelId must be supplied by the caller (no hardcoded default).
+ */
+declare function hashQuestion(normalizedText: any, modelId: any): any;
+/**
+ * Check if a message is the first user question in a conversation.
+ */
+declare function isFirstQuestion(messages: any): boolean;
+
+/**
+ * Create a new chat session in the database.
+ */
+declare function createChatSession({ chatId, projectId, messages, ownerId, forkedFrom }: {
+    chatId: any;
+    projectId: any;
+    messages: any;
+    ownerId: any;
+    forkedFrom?: any;
+}): Promise<any>;
+/**
+ * Save or update a chat session in the database.
+ * Handles usage token array accumulation and owner/visibility defaults for new chats.
+ */
+declare function saveChat({ chatId, messages, usage, ownerId, projectId }: {
+    chatId: any;
+    messages: any;
+    usage: any;
+    ownerId: any;
+    projectId: any;
+}): Promise<any>;
+
+type HumanInTheLoopUIMessage = any;
+/**
+ * Process tool calls that required human confirmation on the client.
+ * Executes the tool's server-side function when the user approved.
+ */
+declare function processToolCalls<Tools extends ToolSet, ExecutableTools extends {
+    [Tool in keyof Tools as Tools[Tool] extends {
+        execute: Function;
+    } ? never : Tool]: Tools[Tool];
+}>({ writer, messages }: {
+    tools: Tools;
+    writer: UIMessageStreamWriter;
+    messages: HumanInTheLoopUIMessage[];
+}, executeFunctions: {
+    [K in keyof Tools & keyof ExecutableTools]?: (args: ExecutableTools[K] extends Tool<infer P> ? P : never, context: ToolExecutionOptions) => Promise<any>;
+}): Promise<HumanInTheLoopUIMessage[]>;
+/**
+ * Sanitize messages before saving to database.
+ * Strips PII from emailCapture tool outputs — the owner sees the personalized
+ * confirmation in real-time, but the database only stores a generic message.
+ */
+declare const sanitizeMessagesForStorage: (messages: any[]) => any[];
+
+declare function getOwnerId(): Promise<any>;
+declare function getOwnerIdIfExists(): Promise<string>;
+/**
+ * Validate ownership of a chat by comparing the browser cookie with the DB value.
+ */
+declare function validateOwnership(chatId: any, dbOwnerId: any): Promise<{
+    isOwner: boolean;
+    reason: string;
+}>;
+
+declare const chatRateLimit: Ratelimit;
+declare function checkRateLimit(req: any, rateLimiter: any): Promise<Response>;
+
+/**
+ * Inject pre-built service clients into chat-core.
+ *
+ * Call this once at app startup (e.g. in lib/server/services.js) before any
+ * chat-core server functions run. If not called, the package falls back to
+ * the SUPABASE_URL / SUPABASE_SERVICE_ROLE_KEY / CARUUTO_URL / CARUUTO_API_KEY
+ * environment variables — existing apps work without any changes.
+ *
+ * @param {object} clients
+ * @param {import('@supabase/supabase-js').SupabaseClient} [clients.supabase]
+ * @param {import('@caruuto/caruuto-js').CaruutoClient}    [clients.caruuto]
+ */
+declare function configure({ supabase, caruuto }?: {
+    supabase?: _supabase_supabase_js.SupabaseClient;
+    caruuto?: any;
+}): void;
+declare const supabaseAdmin: {};
+declare const caruutoAdmin: {};
+
+/**
+ * Resolve the project_id for the current tenant from the CARUUTO_PROJECT env var.
+ */
+declare function getProjectId(): Promise<any>;
+/**
+ * Extract media items with metadata from a document's properties.
+ * Handles parallel arrays format (images + imageMetadata) and legacy formats.
+ */
+declare function extractMediaWithMetadata(imagesField: any, imageMetadataField?: any[]): ({
+    mediaId: any;
+    url: string;
+    metadata: {
+        caption?: undefined;
+        altText?: undefined;
+        credit?: undefined;
+        tags?: undefined;
+    };
+} | {
+    mediaId: any;
+    metadata: {
+        caption: any;
+        altText: any;
+        credit: any;
+        tags: any;
+    };
+    url?: undefined;
+})[];
+/**
+ * Resolve media URLs and merge with metadata from documents.
+ */
+declare function resolveMediaUrls(mediaItems: any): Promise<Map<any, any>>;
+/**
+ * Fetch parent documents by content IDs.
+ */
+declare function getParentDocuments(sourceContentIds: any): Promise<Map<any, any>>;
+/**
+ * Split a full name string into firstName and lastName.
+ */
+declare function splitName(fullName: any): {
+    firstName: any;
+    lastName: any;
+};
+
+declare function createCachedResponseStream(cachedAnswer: any, questionId: any, chatId: any, originalMessages: any, ownerId: any, projectId: any): Promise<Response>;
+declare function createStaticErrorStream(errorMessage: any): Response;
+
+export { apiErrors, caruutoAdmin, chatRateLimit, checkRateLimit, configure, createCachedResponseStream, createChatSession, createLinkClickHandler, createRagHandler, createStaticErrorStream, extractMediaWithMetadata, fetchChatWithOwnership, getOwnerId, getOwnerIdIfExists, getParentDocuments, getProjectId, handleAPIError, hashQuestion, isFirstQuestion, normalizeQuestion, processToolCalls, resolveMediaUrls, sanitizeMessagesForStorage, saveChat, splitName, supabaseAdmin, validateOwnership };