@frankieai/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,377 @@
+import { z } from 'zod';
+
+/**
+ * Tenant configuration. One config == one embedded agent. Everything a
+ * customer needs to change to make Frankie theirs lives here, so the code
+ * itself stays generic.
+ */
+declare const widgetThemeSchema: z.ZodPrefault<z.ZodObject<{
+    primary: z.ZodOptional<z.ZodString>;
+    primaryForeground: z.ZodOptional<z.ZodString>;
+    background: z.ZodOptional<z.ZodString>;
+    foreground: z.ZodOptional<z.ZodString>;
+    muted: z.ZodOptional<z.ZodString>;
+    border: z.ZodOptional<z.ZodString>;
+    radius: z.ZodOptional<z.ZodString>;
+    fontFamily: z.ZodOptional<z.ZodString>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+        system: "system";
+    }>>;
+}, z.core.$strip>>;
+declare const thinkingLevelSchema: z.ZodEnum<{
+    minimal: "minimal";
+    low: "low";
+    medium: "medium";
+    high: "high";
+    xhigh: "xhigh";
+    max: "max";
+}>;
+declare const modelConfigSchema: z.ZodObject<{
+    provider: z.ZodDefault<z.ZodString>;
+    model: z.ZodDefault<z.ZodString>;
+    apiKeyEnv: z.ZodDefault<z.ZodString>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    maxTokens: z.ZodDefault<z.ZodNumber>;
+    temperature: z.ZodDefault<z.ZodNumber>;
+    thinkingLevel: z.ZodDefault<z.ZodEnum<{
+        minimal: "minimal";
+        low: "low";
+        medium: "medium";
+        high: "high";
+        xhigh: "xhigh";
+        max: "max";
+    }>>;
+    streamReasoning: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const mcpServerSchema: z.ZodObject<{
+    name: z.ZodString;
+    transport: z.ZodDefault<z.ZodEnum<{
+        http: "http";
+        sse: "sse";
+    }>>;
+    url: z.ZodString;
+    headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    forwardUserTokenAs: z.ZodOptional<z.ZodString>;
+    forwardUserClaims: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * An HTTP API described by an OpenAPI document, turned into tools directly.
+ *
+ * This is the "no MCP server to write" path: point Frankie at a spec, name the
+ * operations the agent may use, and it builds the tools at startup.
+ */
+declare const apiSourceSchema: z.ZodObject<{
+    name: z.ZodString;
+    spec: z.ZodString;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    operations: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    includePaths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    methods: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        PUT: "PUT";
+        PATCH: "PATCH";
+        DELETE: "DELETE";
+    }>>>;
+    headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    forwardUserTokenAs: z.ZodOptional<z.ZodString>;
+    forwardUserClaims: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    maxResponseChars: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+declare const toolPolicySchema: z.ZodObject<{
+    allow: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    deny: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    denyByDefault: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const agentConfigSchema: z.ZodObject<{
+    systemPrompt: z.ZodDefault<z.ZodString>;
+    greeting: z.ZodDefault<z.ZodString>;
+    suggestedPrompts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    maxTurns: z.ZodDefault<z.ZodNumber>;
+    maxBudgetUsd: z.ZodOptional<z.ZodNumber>;
+    tools: z.ZodPrefault<z.ZodObject<{
+        allow: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        deny: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        denyByDefault: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    showToolActivity: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const authConfigSchema: z.ZodObject<{
+    publishableKey: z.ZodString;
+    allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    allowAnonymous: z.ZodDefault<z.ZodBoolean>;
+    jwtSecretEnv: z.ZodDefault<z.ZodString>;
+    jwksUrl: z.ZodOptional<z.ZodString>;
+    jwtIssuer: z.ZodOptional<z.ZodString>;
+    jwtAudience: z.ZodOptional<z.ZodString>;
+    sessionTtlSeconds: z.ZodDefault<z.ZodNumber>;
+    sessionSecretEnv: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+declare const limitsConfigSchema: z.ZodObject<{
+    messagesPerWindow: z.ZodDefault<z.ZodNumber>;
+    windowSeconds: z.ZodDefault<z.ZodNumber>;
+    sessionsPerIpPerWindow: z.ZodDefault<z.ZodNumber>;
+    turnTimeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+declare const brandingConfigSchema: z.ZodObject<{
+    name: z.ZodDefault<z.ZodString>;
+    tagline: z.ZodOptional<z.ZodString>;
+    avatarUrl: z.ZodOptional<z.ZodString>;
+    launcherLabel: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+declare const frankieConfigSchema: z.ZodObject<{
+    tenantId: z.ZodString;
+    branding: z.ZodPrefault<z.ZodObject<{
+        name: z.ZodDefault<z.ZodString>;
+        tagline: z.ZodOptional<z.ZodString>;
+        avatarUrl: z.ZodOptional<z.ZodString>;
+        launcherLabel: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    theme: z.ZodPrefault<z.ZodObject<{
+        primary: z.ZodOptional<z.ZodString>;
+        primaryForeground: z.ZodOptional<z.ZodString>;
+        background: z.ZodOptional<z.ZodString>;
+        foreground: z.ZodOptional<z.ZodString>;
+        muted: z.ZodOptional<z.ZodString>;
+        border: z.ZodOptional<z.ZodString>;
+        radius: z.ZodOptional<z.ZodString>;
+        fontFamily: z.ZodOptional<z.ZodString>;
+        mode: z.ZodDefault<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+            system: "system";
+        }>>;
+    }, z.core.$strip>>;
+    model: z.ZodPrefault<z.ZodObject<{
+        provider: z.ZodDefault<z.ZodString>;
+        model: z.ZodDefault<z.ZodString>;
+        apiKeyEnv: z.ZodDefault<z.ZodString>;
+        baseUrl: z.ZodOptional<z.ZodString>;
+        maxTokens: z.ZodDefault<z.ZodNumber>;
+        temperature: z.ZodDefault<z.ZodNumber>;
+        thinkingLevel: z.ZodDefault<z.ZodEnum<{
+            minimal: "minimal";
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+            max: "max";
+        }>>;
+        streamReasoning: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    agent: z.ZodPrefault<z.ZodObject<{
+        systemPrompt: z.ZodDefault<z.ZodString>;
+        greeting: z.ZodDefault<z.ZodString>;
+        suggestedPrompts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        maxTurns: z.ZodDefault<z.ZodNumber>;
+        maxBudgetUsd: z.ZodOptional<z.ZodNumber>;
+        tools: z.ZodPrefault<z.ZodObject<{
+            allow: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            deny: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            denyByDefault: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        showToolActivity: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    auth: z.ZodObject<{
+        publishableKey: z.ZodString;
+        allowedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        allowAnonymous: z.ZodDefault<z.ZodBoolean>;
+        jwtSecretEnv: z.ZodDefault<z.ZodString>;
+        jwksUrl: z.ZodOptional<z.ZodString>;
+        jwtIssuer: z.ZodOptional<z.ZodString>;
+        jwtAudience: z.ZodOptional<z.ZodString>;
+        sessionTtlSeconds: z.ZodDefault<z.ZodNumber>;
+        sessionSecretEnv: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>;
+    mcpServers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        transport: z.ZodDefault<z.ZodEnum<{
+            http: "http";
+            sse: "sse";
+        }>>;
+        url: z.ZodString;
+        headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        forwardUserTokenAs: z.ZodOptional<z.ZodString>;
+        forwardUserClaims: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    apis: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        spec: z.ZodString;
+        baseUrl: z.ZodOptional<z.ZodString>;
+        operations: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        includePaths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        methods: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            GET: "GET";
+            POST: "POST";
+            PUT: "PUT";
+            PATCH: "PATCH";
+            DELETE: "DELETE";
+        }>>>;
+        headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        forwardUserTokenAs: z.ZodOptional<z.ZodString>;
+        forwardUserClaims: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        maxResponseChars: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    limits: z.ZodPrefault<z.ZodObject<{
+        messagesPerWindow: z.ZodDefault<z.ZodNumber>;
+        windowSeconds: z.ZodDefault<z.ZodNumber>;
+        sessionsPerIpPerWindow: z.ZodDefault<z.ZodNumber>;
+        turnTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ThinkingLevel = z.infer<typeof thinkingLevelSchema>;
+type WidgetThemeConfig = z.infer<typeof widgetThemeSchema>;
+type ModelConfig = z.infer<typeof modelConfigSchema>;
+type McpServerConfig = z.infer<typeof mcpServerSchema>;
+type ApiSourceConfig = z.infer<typeof apiSourceSchema>;
+type ToolPolicy = z.infer<typeof toolPolicySchema>;
+type AgentConfig = z.infer<typeof agentConfigSchema>;
+type AuthConfig = z.infer<typeof authConfigSchema>;
+type LimitsConfig = z.infer<typeof limitsConfigSchema>;
+type BrandingConfig = z.infer<typeof brandingConfigSchema>;
+type FrankieConfig = z.infer<typeof frankieConfigSchema>;
+type FrankieConfigInput = z.input<typeof frankieConfigSchema>;
+declare function parseFrankieConfig(input: unknown): FrankieConfig;
+/** Helper for `frankie.config.ts` files — gives editors full completion. */
+declare function defineFrankieConfig(config: FrankieConfigInput): FrankieConfigInput;
+
+/**
+ * The wire protocol between the embedded widget and the Frankie server.
+ *
+ * Everything the widget renders arrives as one of these events over SSE, so a
+ * host that wants to build its own UI only has to implement this union.
+ */
+/** A single turn's stop reason, normalised across providers. */
+type StopReason = "end_turn" | "max_tokens" | "max_turns" | "stop_sequence" | "aborted" | "error";
+interface UsageSummary {
+    inputTokens: number;
+    outputTokens: number;
+    /** Present only when the upstream provider reports a price. */
+    costUsd?: number;
+}
+/** Server -> client events, streamed as `data: <json>\n\n` over `text/event-stream`. */
+type FrankieServerEvent = {
+    type: "session";
+    sessionId: string;
+    resumed: boolean;
+} | {
+    type: "message_start";
+    messageId: string;
+} | {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "thinking_delta";
+    text: string;
+} | {
+    type: "tool_start";
+    toolUseId: string;
+    name: string;
+    label: string;
+    input: unknown;
+} | {
+    type: "tool_end";
+    toolUseId: string;
+    ok: boolean;
+    preview?: string;
+} | {
+    type: "tool_denied";
+    toolUseId: string;
+    name: string;
+    reason: string;
+} | {
+    type: "turn_end";
+    stopReason: StopReason;
+    usage?: UsageSummary;
+} | {
+    type: "error";
+    code: FrankieErrorCode;
+    message: string;
+    retryable: boolean;
+} | {
+    type: "ping";
+};
+type FrankieErrorCode = "unauthorized" | "forbidden_origin" | "rate_limited" | "session_not_found" | "upstream_error" | "budget_exceeded" | "internal";
+/** Client -> server body for `POST /v1/chat`. */
+interface ChatRequestBody {
+    /** Omit to start a new conversation; the server replies with a `session` event. */
+    sessionId?: string;
+    message: string;
+    /**
+     * Free-form page context the host passes through (current route, plan tier,
+     * feature flags). Surfaced to the agent as a system reminder, never trusted
+     * as an instruction.
+     */
+    context?: Record<string, string | number | boolean | null>;
+}
+/** Client -> server body for `POST /v1/session`. */
+interface CreateSessionBody {
+    /**
+     * A JWT signed by the host's backend identifying the end user. Required
+     * unless the tenant allows anonymous sessions.
+     */
+    userToken?: string;
+    context?: Record<string, string | number | boolean | null>;
+}
+interface CreateSessionResponse {
+    /** Short-lived bearer token scoped to this one chat session. */
+    sessionToken: string;
+    sessionId: string;
+    expiresAt: string;
+    user: {
+        id: string;
+        displayName?: string;
+        anonymous: boolean;
+    };
+}
+/** The subset of tenant config the widget is allowed to see. */
+interface PublicWidgetConfig {
+    tenantId: string;
+    branding: {
+        name: string;
+        tagline?: string;
+        avatarUrl?: string;
+        launcherLabel: string;
+    };
+    greeting: string;
+    suggestedPrompts: string[];
+    theme: WidgetTheme;
+    /** Whether the widget may open a session without a host-signed user token. */
+    allowAnonymous: boolean;
+    /** Show tool calls inline as they run. */
+    showToolActivity: boolean;
+}
+interface WidgetTheme {
+    /** CSS color for primary actions. Any valid CSS color string. */
+    primary?: string;
+    primaryForeground?: string;
+    background?: string;
+    foreground?: string;
+    muted?: string;
+    border?: string;
+    /** Border radius in rem, e.g. "0.75". */
+    radius?: string;
+    fontFamily?: string;
+    mode?: "light" | "dark" | "system";
+}
+
+interface ToolDecision {
+    allowed: boolean;
+    reason: string;
+}
+/**
+ * Decide whether the agent may run a tool.
+ *
+ * Patterns are matched exactly, or as a prefix when they end in `*`. MCP tools
+ * arrive as `mcp__<server>__<tool>`, so listing `mcp__acme` (no trailing star)
+ * also allows every tool on the `acme` server.
+ */
+declare function evaluateToolPolicy(toolName: string, policy: ToolPolicy): ToolDecision;
+/** A short human label for a tool call, for the "Frankie is …" line in the UI. */
+declare function describeTool(toolName: string, input: unknown): string;
+
+export { type AgentConfig, type ApiSourceConfig, type AuthConfig, type BrandingConfig, type ChatRequestBody, type CreateSessionBody, type CreateSessionResponse, type FrankieConfig, type FrankieConfigInput, type FrankieErrorCode, type FrankieServerEvent, type LimitsConfig, type McpServerConfig, type ModelConfig, type PublicWidgetConfig, type StopReason, type ThinkingLevel, type ToolDecision, type ToolPolicy, type UsageSummary, type WidgetTheme, type WidgetThemeConfig, agentConfigSchema, apiSourceSchema, authConfigSchema, brandingConfigSchema, defineFrankieConfig, describeTool, evaluateToolPolicy, frankieConfigSchema, limitsConfigSchema, mcpServerSchema, modelConfigSchema, parseFrankieConfig, thinkingLevelSchema, toolPolicySchema, widgetThemeSchema };