@aginies/webuikit 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,965 @@
+import * as react from 'react';
+import { ButtonHTMLAttributes, HTMLAttributes, InputHTMLAttributes, TextareaHTMLAttributes, ReactNode } from 'react';
+
+/**
+ * Thin browser client for the Aginies platform: activation handshake, hosted-chat
+ * configuration and streaming chat turns. No framework dependency; the React layer
+ * wraps it.
+ */
+interface AginiesConfig {
+    /** Platform origin, e.g. `https://app.example.com`. No trailing slash. */
+    baseUrl: string;
+    /** Activation token issued for the deployment. Without it nothing renders. */
+    token: string;
+    /** UI language. Defaults to the document language, then English. */
+    locale?: 'tr' | 'en';
+    /** Fetch implementation override (tests, SSR). */
+    fetch?: typeof fetch;
+}
+interface ActivationConfig {
+    apiBase: string;
+    brand: {
+        name: string;
+        logoUrl: string | null;
+    };
+    theme: Record<string, string | undefined> | null;
+    /** Widget modules the activation unlocks; empty means all. */
+    modules?: string[];
+    /** The tenant a tenant key belongs to. Absent for a static activation key. */
+    tenant?: {
+        id: string;
+        name: string;
+    };
+}
+/**
+ * The session a tenant key buys: a short-lived bearer the client sends on every
+ * platform call and renews by re-activating when it is refused.
+ */
+interface ActivationSession {
+    token: string;
+    /** Unix seconds. */
+    expiresAt: number;
+}
+type ActivationState = {
+    status: 'idle';
+} | {
+    status: 'activating';
+} | {
+    status: 'active';
+    config: ActivationConfig;
+} | {
+    status: 'rejected';
+    reason: string;
+};
+interface ChatConfig {
+    id: string;
+    title: string;
+    description: string;
+    customizations: {
+        primaryColor?: string;
+        welcomeMessage?: string;
+        imageUrl?: string;
+        logoUrl?: string;
+        headerText?: string;
+    };
+    authType: 'public' | 'password' | 'email' | 'sso';
+    outputConfigs?: Array<{
+        blockId: string;
+        path?: string;
+    }>;
+}
+interface ChatAuthRequired {
+    authRequired: ChatConfig['authType'];
+    title?: string;
+    description?: string;
+}
+interface ChatFilePayload {
+    name: string;
+    type: string;
+    size: number;
+    data: string;
+    lastModified?: number;
+}
+interface SendMessageInput {
+    input?: string;
+    conversationId?: string;
+    password?: string;
+    email?: string;
+    files?: ChatFilePayload[];
+}
+/** One server-sent event from a chat turn, already decoded. */
+type ChatStreamEvent = {
+    type: 'chunk';
+    blockId?: string;
+    text: string;
+} | {
+    type: 'final';
+    data: unknown;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'done';
+};
+declare class AginiesError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    constructor(message: string, status: number, code?: string);
+}
+declare class AginiesClient {
+    readonly baseUrl: string;
+    readonly token: string;
+    readonly locale: 'tr' | 'en';
+    private readonly fetchImpl;
+    private state;
+    private listeners;
+    private activation;
+    private session;
+    constructor(config: AginiesConfig);
+    getState(): ActivationState;
+    subscribe(listener: (s: ActivationState) => void): () => void;
+    private setState;
+    /**
+     * Runs the activation handshake once and caches the outcome. Components render only
+     * while the state is `active`; a rejected activation is final for this client.
+     */
+    activate(): Promise<ActivationState>;
+    private assertActive;
+    /** The current tenant session, if the activation issued one. */
+    getSession(): ActivationSession | null;
+    /** Whether `module` may render under this activation. */
+    hasModule(module: string): boolean;
+    /**
+     * Re-runs the handshake to obtain a fresh session. Used when a call is refused with
+     * an expired bearer; the activation state stays `active` unless the platform now
+     * rejects the key.
+     */
+    private renewSession;
+    private withSession;
+    /**
+     * A platform request carrying cookies and, when a tenant session exists, its bearer.
+     * A 401/403 on a session that has expired triggers one renewal and one retry.
+     */
+    private request;
+    /** A raw request against the platform for endpoints the client does not wrap. */
+    fetchRaw(path: string, init?: RequestInit): Promise<Response>;
+    /** Hosted-chat configuration. Resolves to an auth requirement instead of throwing on 401. */
+    getChat(identifier: string): Promise<ChatConfig | ChatAuthRequired>;
+    /**
+     * Sends one turn and yields the streamed events. Authentication for password / e-mail
+     * chats travels in the same body on the first call; the platform then sets a cookie.
+     */
+    sendMessage(identifier: string, input: SendMessageInput, signal?: AbortSignal): AsyncGenerator<ChatStreamEvent>;
+}
+/** Parses an SSE body into chat events. Exported for tests. */
+declare function parseSSE(stream: ReadableStream<Uint8Array>): AsyncGenerator<ChatStreamEvent>;
+
+/**
+ * Human-in-the-loop approvals. A run that reaches a "Human in the Loop" block pauses;
+ * the platform stores its state and hands out a resume link. This module reads the
+ * paused execution (`GET /api/resume/:workflowId/:executionId[/:contextId]`) and resumes
+ * it with the approver's input (`POST …/:contextId`), through the activated client so a
+ * tenant session travels along.
+ */
+
+type ResumeStatus = 'paused' | 'resumed' | 'failed' | 'queued' | 'resuming';
+interface ResumeQueueEntry {
+    id: string;
+    contextId: string;
+    status: string;
+    queuedAt: string | null;
+    claimedAt: string | null;
+    completedAt: string | null;
+    failureReason: string | null;
+    newExecutionId: string;
+    resumeInput: unknown;
+}
+interface PausePoint {
+    contextId: string;
+    triggerBlockId: string;
+    /** The block's paused output; `data.inputFormat` describes the approver's form. */
+    response: {
+        data?: Record<string, unknown>;
+    } | null;
+    registeredAt: string;
+    resumeStatus: ResumeStatus;
+    snapshotReady: boolean;
+    queuePosition?: number | null;
+    latestResumeEntry?: ResumeQueueEntry | null;
+}
+interface PausedExecution {
+    id: string;
+    workflowId: string;
+    executionId: string;
+    status: string;
+    totalPauseCount: number;
+    resumedCount: number;
+    pausedAt: string | null;
+    updatedAt: string | null;
+    expiresAt: string | null;
+    metadata: Record<string, unknown> | null;
+    pausePoints: PausePoint[];
+    queue?: ResumeQueueEntry[];
+}
+interface PauseContext {
+    execution: PausedExecution;
+    pausePoint: PausePoint;
+    queue: ResumeQueueEntry[];
+    activeResumeEntry?: ResumeQueueEntry | null;
+}
+interface ResumeOutcome {
+    status: 'started' | 'queued';
+    executionId: string;
+    queuePosition?: number | null;
+    message?: string;
+}
+/** One field of the approver's form, as the block author configured it. */
+interface ResumeField {
+    id: string;
+    name: string;
+    label: string;
+    type: string;
+    description?: string;
+    placeholder?: string;
+    value?: unknown;
+    required: boolean;
+    options?: unknown[];
+    rows?: number;
+}
+declare function getPausedExecution(client: AginiesClient, workflowId: string, executionId: string): Promise<PausedExecution>;
+declare function getPauseContext(client: AginiesClient, workflowId: string, executionId: string, contextId: string): Promise<PauseContext>;
+declare function listPausedExecutions(client: AginiesClient, workflowId: string, status?: string): Promise<PausedExecution[]>;
+/** Resumes one pause point with the approver's submission, keyed by field name. */
+declare function resumeExecution(client: AginiesClient, workflowId: string, executionId: string, contextId: string, submission: Record<string, unknown> | null): Promise<ResumeOutcome>;
+/** Reads the approver's form out of a pause point, tolerating partial definitions. */
+declare function fieldsOf(point: PausePoint | null | undefined): ResumeField[];
+/** The paused output shown to the approver: everything in `data` except form plumbing. */
+declare function outputOf(point: PausePoint | null | undefined): Record<string, unknown>;
+/** Formats a stored value for an input of this field's type. */
+declare function formatFieldValue(field: ResumeField, value: unknown): string;
+/** Parses an input's text back into the field's type; `error` names what went wrong. */
+declare function parseFieldValue(field: ResumeField, raw: string): {
+    value?: unknown;
+    error?: 'number' | 'json';
+};
+/** Initial input text per field, from the block's defaults. */
+declare function initialValues(fields: ResumeField[]): Record<string, string>;
+/**
+ * Builds the submission from the inputs, or reports the fields that are missing or
+ * malformed. Empty optional fields are left out of the submission.
+ */
+declare function buildSubmission(fields: ResumeField[], values: Record<string, string>): {
+    submission: Record<string, unknown>;
+    errors: Record<string, 'required' | 'number' | 'json'>;
+};
+
+type ApprovalStatus = 'loading' | 'ready' | 'submitting' | 'resumed' | 'queued' | 'not-found' | 'error';
+/**
+ * State for one paused run: which pause point is selected, the approver's form, the
+ * outcome of resuming. `ApprovalPanel` renders it; use the hook for a custom UI.
+ */
+declare function useApproval(workflowId: string, executionId: string, contextId?: string): {
+    status: ApprovalStatus;
+    execution: PausedExecution | null;
+    pausePoint: PausePoint | null;
+    fields: ResumeField[];
+    values: Record<string, string>;
+    errors: Record<string, string>;
+    error: string | null;
+    outcome: ResumeOutcome | null;
+    select: (nextContextId: string) => void;
+    setValue: (name: string, value: string) => void;
+    submit: () => Promise<void>;
+    reload: () => Promise<void>;
+};
+interface ApprovalPanelProps {
+    /** Id of the agent (workflow) whose run is paused. */
+    workflowId: string;
+    /** The paused execution, from the resume link the approver received. */
+    executionId: string;
+    /** A specific pause point; defaults to the first one still paused. */
+    contextId?: string;
+    title?: string;
+    description?: string;
+    /** Label of the resume button; defaults to "Approve and continue". */
+    submitLabel?: string;
+    /** Called after the platform accepted the resume. */
+    onResumed?: (outcome: ResumeOutcome) => void;
+    /** Hide the paused output block. */
+    hideOutput?: boolean;
+    className?: string;
+}
+declare function ApprovalPanel({ workflowId, executionId, contextId, title, description, submitLabel, onResumed, hideOutput, className, }: ApprovalPanelProps): react.JSX.Element | null;
+
+/**
+ * Structured replies: an agent may answer with a JSON document of items (text, buttons,
+ * table, cards, pie, image) instead of prose. This mirrors the contract the platform's
+ * hosted chat renders, so a workflow tuned for one renders identically in the widget.
+ */
+interface StructuredButton {
+    label: string;
+    action: string;
+}
+interface StructuredTable {
+    headers: string[];
+    rows: string[][];
+}
+interface StructuredCard {
+    title: string;
+    subtitle: string;
+    body: string;
+    image: string;
+}
+interface StructuredPie {
+    labels: string[];
+    data: number[];
+}
+interface StructuredImage {
+    url: string;
+    caption: string;
+}
+interface StructuredItem {
+    text: {
+        content: string;
+    };
+    buttons: StructuredButton[];
+    table: StructuredTable;
+    cards: StructuredCard[];
+    pie: StructuredPie;
+    image: StructuredImage;
+}
+interface StructuredResponse {
+    items: StructuredItem[];
+}
+/** Parses a reply into a structured response, or null when it is ordinary prose. */
+declare function parseStructured(raw: string): StructuredResponse | null;
+interface StructuredUIProps {
+    response: StructuredResponse;
+    /** Called with the button's action text; the widget sends it as the next message. */
+    onAction?: (action: string) => void;
+}
+declare function StructuredUI({ response, onAction }: StructuredUIProps): react.JSX.Element;
+
+/** A file the visitor attached to a message, as shown in the transcript. */
+interface ChatAttachment {
+    name: string;
+    type: string;
+    size: number;
+}
+interface ChatMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    attachments?: ChatAttachment[];
+    structured?: StructuredResponse | null;
+    streaming?: boolean;
+    error?: boolean;
+}
+/** Outcome of asking the platform to e-mail a verification code. */
+type CodeRequestResult = 'sent' | 'unauthorized' | 'error';
+/** Per-file and per-message limits for attachments; the platform rejects larger uploads. */
+declare const ATTACHMENT_LIMITS: {
+    readonly maxFiles: 5;
+    readonly maxBytes: number;
+};
+type AuthNeed = 'password' | 'email' | 'sso' | null;
+/**
+ * Chat state for one hosted-chat deployment: configuration, authentication, messages and
+ * the streaming turn in flight. `ChatWidget` renders it; use the hook directly for a custom UI.
+ */
+declare function useChat(identifier: string, enabled?: boolean): {
+    config: ChatConfig | null;
+    authNeed: AuthNeed;
+    authTitle: string | undefined;
+    loadError: string | null;
+    messages: ChatMessage[];
+    busy: boolean;
+    send: (text: string, files?: ChatFilePayload[]) => Promise<void>;
+    stop: () => void;
+    authenticate: ({ password }: {
+        password: string;
+    }) => Promise<boolean>;
+    requestCode: (email: string) => Promise<CodeRequestResult>;
+    verifyCode: (email: string, otp: string) => Promise<boolean>;
+    reload: () => Promise<void>;
+};
+interface ChatWidgetProps {
+    /** Identifier of the deployed chat, the last segment of its hosted URL. */
+    identifier: string;
+    /** `bubble` floats a launcher in a corner; `inline` fills its container; `full` fills the viewport. */
+    mode?: 'bubble' | 'inline' | 'full';
+    /** Corner for `bubble` mode. */
+    position?: 'right' | 'left';
+    /** Text on the launcher; defaults to the chat title. */
+    launcherLabel?: string;
+    /** Start open (bubble mode). */
+    defaultOpen?: boolean;
+    /** Theme for the widget subtree; `auto` follows the host page. */
+    theme?: 'dark' | 'light' | 'auto';
+    className?: string;
+}
+declare function ChatWidget({ identifier, mode, position, launcherLabel, defaultOpen, theme, className, }: ChatWidgetProps): react.JSX.Element | null;
+
+/**
+ * Small Markdown renderer for agent replies. It builds React elements directly, so nothing
+ * from the model reaches the DOM as HTML. Covers what agents actually write: paragraphs,
+ * headings, emphasis, inline and fenced code, links, lists, blockquotes, tables and rules.
+ */
+declare function Markdown({ text, className }: {
+    text: string;
+    className?: string;
+}): react.JSX.Element;
+
+/** Joins class names, dropping falsy entries. */
+declare function cx(...parts: Array<string | false | null | undefined>): string;
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /** `primary` is the text fill, `signal` the accent fill, `outline` the quiet default. */
+    variant?: 'primary' | 'signal' | 'outline' | 'ghost' | 'destructive';
+    size?: 'sm' | 'md' | 'lg';
+}
+declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
+interface TagProps extends HTMLAttributes<HTMLSpanElement> {
+    tone?: 'default' | 'signal' | 'ok' | 'warn' | 'bad';
+}
+declare function Tag({ tone, className, ...props }: TagProps): react.JSX.Element;
+interface ChipProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    pressed?: boolean;
+}
+declare function Chip({ pressed, className, type, ...props }: ChipProps): react.JSX.Element;
+interface PanelProps extends HTMLAttributes<HTMLDivElement> {
+    level?: 1 | 2;
+}
+declare function Panel({ level, className, ...props }: PanelProps): react.JSX.Element;
+declare function Eyebrow({ className, quiet, ...props }: HTMLAttributes<HTMLParagraphElement> & {
+    quiet?: boolean;
+}): react.JSX.Element;
+interface StatProps extends HTMLAttributes<HTMLDivElement> {
+    value: string;
+    label: string;
+}
+declare function Stat({ value, label, className, ...props }: StatProps): react.JSX.Element;
+interface FieldProps extends HTMLAttributes<HTMLLabelElement> {
+    label: string;
+    htmlFor?: string;
+    /** Help text under the control; replaced by `error` when one is set. */
+    hint?: string;
+    error?: string;
+}
+declare function Field({ label, hint, error, className, children, ...props }: FieldProps): react.JSX.Element;
+declare const Input: react.ForwardRefExoticComponent<InputHTMLAttributes<HTMLInputElement> & react.RefAttributes<HTMLInputElement>>;
+declare const Textarea: react.ForwardRefExoticComponent<TextareaHTMLAttributes<HTMLTextAreaElement> & react.RefAttributes<HTMLTextAreaElement>>;
+declare function Spinner({ className, label }: {
+    className?: string;
+    label?: string;
+}): react.JSX.Element;
+
+type Locale = 'tr' | 'en';
+declare const STRINGS: {
+    readonly chat: {
+        readonly open: {
+            readonly tr: "Sohbeti aç";
+            readonly en: "Open chat";
+        };
+        readonly close: {
+            readonly tr: "Kapat";
+            readonly en: "Close";
+        };
+        readonly placeholder: {
+            readonly tr: "Mesajınızı yazın…";
+            readonly en: "Type your message…";
+        };
+        readonly send: {
+            readonly tr: "Gönder";
+            readonly en: "Send";
+        };
+        readonly stop: {
+            readonly tr: "Durdur";
+            readonly en: "Stop";
+        };
+        readonly attach: {
+            readonly tr: "Dosya ekle";
+            readonly en: "Attach file";
+        };
+        readonly attachments: {
+            readonly tr: "Ekler";
+            readonly en: "Attachments";
+        };
+        readonly removeFile: {
+            readonly tr: "Dosyayı kaldır";
+            readonly en: "Remove file";
+        };
+        readonly tooManyFiles: {
+            readonly tr: "En fazla 5 dosya ekleyebilirsiniz.";
+            readonly en: "You can attach up to 5 files.";
+        };
+        readonly fileTooLarge: {
+            readonly tr: "Dosyalar 10 MB'tan küçük olmalı.";
+            readonly en: "Files must be smaller than 10 MB.";
+        };
+        readonly welcome: {
+            readonly tr: "Merhaba! Size nasıl yardımcı olabilirim?";
+            readonly en: "Hi there! How can I help you today?";
+        };
+        readonly thinking: {
+            readonly tr: "Yanıt hazırlanıyor";
+            readonly en: "Working on it";
+        };
+        readonly stopped: {
+            readonly tr: "Yanıt durduruldu.";
+            readonly en: "Response stopped.";
+        };
+        readonly error: {
+            readonly tr: "Bir sorun oluştu. Lütfen tekrar deneyin.";
+            readonly en: "Something went wrong. Please try again.";
+        };
+        readonly unavailable: {
+            readonly tr: "Bu sohbet şu anda kullanılamıyor.";
+            readonly en: "This chat is currently unavailable.";
+        };
+        readonly poweredBy: {
+            readonly tr: "Aginies ile";
+            readonly en: "Powered by Aginies";
+        };
+        readonly you: {
+            readonly tr: "Siz";
+            readonly en: "You";
+        };
+        readonly assistant: {
+            readonly tr: "Ajan";
+            readonly en: "Agent";
+        };
+    };
+    readonly auth: {
+        readonly passwordTitle: {
+            readonly tr: "Bu sohbet parola korumalı";
+            readonly en: "This chat is password protected";
+        };
+        readonly passwordHint: {
+            readonly tr: "Devam etmek için parolayı girin.";
+            readonly en: "Enter the password to continue.";
+        };
+        readonly password: {
+            readonly tr: "Parola";
+            readonly en: "Password";
+        };
+        readonly emailTitle: {
+            readonly tr: "E-posta ile doğrulama";
+            readonly en: "Verify with your e-mail";
+        };
+        readonly emailHint: {
+            readonly tr: "İş e-postanızı girin; size bir kod göndereceğiz.";
+            readonly en: "Enter your work e-mail; we will send you a code.";
+        };
+        readonly email: {
+            readonly tr: "E-posta";
+            readonly en: "E-mail";
+        };
+        readonly code: {
+            readonly tr: "Doğrulama kodu";
+            readonly en: "Verification code";
+        };
+        readonly codeHint: {
+            readonly tr: "E-postanıza gelen 6 haneli kodu girin.";
+            readonly en: "Enter the 6-digit code from your e-mail.";
+        };
+        readonly continue: {
+            readonly tr: "Devam et";
+            readonly en: "Continue";
+        };
+        readonly sendCode: {
+            readonly tr: "Kod gönder";
+            readonly en: "Send code";
+        };
+        readonly verify: {
+            readonly tr: "Doğrula";
+            readonly en: "Verify";
+        };
+        readonly back: {
+            readonly tr: "Geri";
+            readonly en: "Back";
+        };
+        readonly invalidPassword: {
+            readonly tr: "Parola yanlış.";
+            readonly en: "Wrong password.";
+        };
+        readonly invalidEmail: {
+            readonly tr: "Bu e-posta adresi yetkili değil.";
+            readonly en: "This e-mail address is not allowed.";
+        };
+        readonly invalidCode: {
+            readonly tr: "Kod geçersiz veya süresi dolmuş.";
+            readonly en: "The code is invalid or has expired.";
+        };
+        readonly codeSent: {
+            readonly tr: "Kod gönderildi.";
+            readonly en: "Code sent.";
+        };
+        readonly codeError: {
+            readonly tr: "Kod gönderilemedi. Lütfen tekrar deneyin.";
+            readonly en: "The code could not be sent. Please try again.";
+        };
+        readonly resend: {
+            readonly tr: "Kodu yeniden gönder";
+            readonly en: "Resend code";
+        };
+        readonly ssoTitle: {
+            readonly tr: "Kurumsal giriş gerekli";
+            readonly en: "Sign in with your organisation";
+        };
+        readonly ssoHint: {
+            readonly tr: "Bu sohbet kurumsal kimlikle açılır.";
+            readonly en: "This chat opens with your organisation account.";
+        };
+        readonly ssoButton: {
+            readonly tr: "Kurumsal giriş";
+            readonly en: "Sign in";
+        };
+    };
+    readonly run: {
+        readonly submit: {
+            readonly tr: "Çalıştır";
+            readonly en: "Run";
+        };
+        readonly cancel: {
+            readonly tr: "İptal";
+            readonly en: "Cancel";
+        };
+        readonly running: {
+            readonly tr: "Çalışıyor";
+            readonly en: "Running";
+        };
+        readonly done: {
+            readonly tr: "Tamamlandı";
+            readonly en: "Completed";
+        };
+        readonly error: {
+            readonly tr: "Hata";
+            readonly en: "Error";
+        };
+        readonly failed: {
+            readonly tr: "Çalıştırma başarısız oldu.";
+            readonly en: "The run failed.";
+        };
+        readonly unauthorized: {
+            readonly tr: "API anahtarı reddedildi.";
+            readonly en: "The API key was rejected.";
+        };
+        readonly steps: {
+            readonly tr: "Adımlar";
+            readonly en: "Steps";
+        };
+        readonly execution: {
+            readonly tr: "çalıştırma";
+            readonly en: "execution";
+        };
+    };
+    readonly approval: {
+        readonly eyebrow: {
+            readonly tr: "İnsan onayı";
+            readonly en: "Human approval";
+        };
+        readonly title: {
+            readonly tr: "Onay bekleyen adım";
+            readonly en: "A step is waiting for approval";
+        };
+        readonly execution: {
+            readonly tr: "çalıştırma";
+            readonly en: "execution";
+        };
+        readonly pausedAt: {
+            readonly tr: "duraklatıldı";
+            readonly en: "paused";
+        };
+        readonly points: {
+            readonly tr: "Onay noktaları";
+            readonly en: "Approval points";
+        };
+        readonly point: {
+            readonly tr: "Nokta";
+            readonly en: "Point";
+        };
+        readonly output: {
+            readonly tr: "Ajanın önerisi";
+            readonly en: "What the agent proposes";
+        };
+        readonly queuePosition: {
+            readonly tr: "Sıra";
+            readonly en: "Queue position";
+        };
+        readonly submit: {
+            readonly tr: "Onayla ve devam et";
+            readonly en: "Approve and continue";
+        };
+        readonly submitting: {
+            readonly tr: "Gönderiliyor";
+            readonly en: "Submitting";
+        };
+        readonly refresh: {
+            readonly tr: "Yenile";
+            readonly en: "Refresh";
+        };
+        readonly required: {
+            readonly tr: "Bu alan zorunlu.";
+            readonly en: "This field is required.";
+        };
+        readonly notANumber: {
+            readonly tr: "Sayı girin.";
+            readonly en: "Enter a number.";
+        };
+        readonly notJson: {
+            readonly tr: "Geçerli JSON girin.";
+            readonly en: "Enter valid JSON.";
+        };
+        readonly notFound: {
+            readonly tr: "Bu onay bulunamadı; süresi dolmuş veya tamamlanmış olabilir.";
+            readonly en: "This approval could not be found; it may have expired or been completed.";
+        };
+        readonly loadError: {
+            readonly tr: "Onay yüklenemedi.";
+            readonly en: "The approval could not be loaded.";
+        };
+        readonly resumeError: {
+            readonly tr: "Devam ettirilemedi.";
+            readonly en: "The run could not be resumed.";
+        };
+        readonly resumedMessage: {
+            readonly tr: "Ajan kaldığı yerden devam ediyor.";
+            readonly en: "The agent is continuing from where it paused.";
+        };
+        readonly queuedMessage: {
+            readonly tr: "Onay sıraya alındı; önceki devam işlemleri bitince çalışacak.";
+            readonly en: "The approval is queued; it runs after the earlier resumes finish.";
+        };
+        readonly paused: {
+            readonly tr: "Onay bekliyor";
+            readonly en: "Awaiting approval";
+        };
+        readonly queued: {
+            readonly tr: "Sırada";
+            readonly en: "Queued";
+        };
+        readonly resuming: {
+            readonly tr: "Devam ediyor";
+            readonly en: "Resuming";
+        };
+        readonly resumed: {
+            readonly tr: "Devam etti";
+            readonly en: "Resumed";
+        };
+        readonly failed: {
+            readonly tr: "Başarısız";
+            readonly en: "Failed";
+        };
+    };
+    readonly common: {
+        readonly loading: {
+            readonly tr: "Yükleniyor";
+            readonly en: "Loading";
+        };
+        readonly retry: {
+            readonly tr: "Tekrar dene";
+            readonly en: "Retry";
+        };
+        readonly notActivated: {
+            readonly tr: "Aginies UI paketi etkinleştirilmedi.";
+            readonly en: "The Aginies UI package is not activated.";
+        };
+    };
+};
+type Section = keyof typeof STRINGS;
+type Key<S extends Section> = keyof (typeof STRINGS)[S];
+/** Returns a translator bound to a locale: `t('chat', 'send')`. */
+declare function translator(locale: Locale): <S extends Section>(section: S, key: Key<S>) => string;
+type Translator = ReturnType<typeof translator>;
+
+/**
+ * Observability widgets. Data-driven: they render whatever the host passes, so they work
+ * with the platform's log and stats endpoints, a data warehouse or static numbers alike.
+ */
+interface StatItem {
+    value: string;
+    label: string;
+    /** Small trend note, e.g. "+4.2% vs last week". */
+    delta?: string;
+    tone?: 'default' | 'ok' | 'warn' | 'bad';
+}
+declare function StatTiles({ items, className, ...props }: {
+    items: StatItem[];
+} & HTMLAttributes<HTMLDivElement>): react.JSX.Element;
+interface HeatmapRow {
+    label: string;
+    /** Success rates 0–1 per column (e.g. per day or per hour); null for no runs. */
+    values: Array<number | null>;
+}
+interface SuccessHeatmapProps extends HTMLAttributes<HTMLDivElement> {
+    rows: HeatmapRow[];
+    /** Column labels, same length as each row's values. */
+    columns?: string[];
+    /** Below `warn` a cell reads as warning, below `bad` as failure. Defaults 0.95 / 0.85. */
+    thresholds?: {
+        warn: number;
+        bad: number;
+    };
+    /** Formats the tooltip; default "97.2%". */
+    format?: (value: number) => string;
+}
+declare function SuccessHeatmap({ rows, columns, thresholds, format, className, ...props }: SuccessHeatmapProps): react.JSX.Element;
+interface TimelineStep {
+    id: string;
+    name: string;
+    /** Step kind in the platform vocabulary; drives the glyph and colour. */
+    kind?: 'ingest' | 'plan' | 'retrieve' | 'reason' | 'tool' | 'verify' | 'approval' | 'write' | 'notify';
+    status: 'done' | 'running' | 'error' | 'waiting';
+    /** Offset from the run start in ms. */
+    startMs: number;
+    durationMs?: number;
+    tokens?: number;
+    costUsd?: number;
+    detail?: string;
+}
+interface RunTimelineProps extends HTMLAttributes<HTMLOListElement> {
+    steps: TimelineStep[];
+    /** Total run duration for the bar scale; defaults to the last step's end. */
+    totalMs?: number;
+}
+declare function RunTimeline({ steps, totalMs, className, ...props }: RunTimelineProps): react.JSX.Element;
+interface CostBarItem {
+    label: string;
+    value: number;
+    /** Optional right-hand caption, e.g. "1,240 runs". */
+    note?: string;
+}
+interface CostBarsProps extends HTMLAttributes<HTMLDivElement> {
+    items: CostBarItem[];
+    /** Formats the value; default USD with two decimals. */
+    format?: (value: number) => string;
+}
+declare function CostBars({ items, format, className, ...props }: CostBarsProps): react.JSX.Element;
+
+/**
+ * Creates the shared client and starts the activation handshake. Call it once, before
+ * rendering any widget; `AginiesProvider` picks the client up automatically.
+ */
+declare function init(config: AginiesConfig): AginiesClient;
+/** The client created by `init()`, if any. */
+declare function getClient(): AginiesClient | null;
+interface AginiesContextValue {
+    client: AginiesClient;
+    state: ActivationState;
+    locale: Locale;
+    t: Translator;
+}
+/**
+ * Whether the activation unlocks `module` (`chat`, `run`, `observability`, `approval`).
+ * A widget whose module is locked renders nothing and warns once.
+ */
+declare function useModule(module: string): boolean;
+interface AginiesProviderProps {
+    /** A client from `init()` or `new AginiesClient()`. Defaults to the one `init()` made. */
+    client?: AginiesClient;
+    /** Override the client's locale for this subtree. */
+    locale?: Locale;
+    /** Rendered while the activation handshake runs. Defaults to nothing. */
+    fallback?: ReactNode;
+    children: ReactNode;
+}
+/**
+ * Provides the activated client to every widget below it. Children render only once the
+ * activation succeeds; a rejected activation renders nothing and logs one warning, so a
+ * page with a wrong or missing token degrades to plain content.
+ */
+declare function AginiesProvider({ client, locale, fallback, children, }: AginiesProviderProps): react.JSX.Element | null;
+/** Access to the activated client, its configuration and the translator. */
+declare function useAginies(): AginiesContextValue;
+
+interface RunStep {
+    blockId: string;
+    name: string;
+    status: 'running' | 'done' | 'error';
+    durationMs?: number;
+}
+type RunStatus = 'idle' | 'running' | 'done' | 'error';
+/**
+ * State for one deployed agent: run it with structured input, follow the streamed text
+ * and steps, read the final output. `AgentRunner` renders it; use the hook for a custom UI.
+ */
+declare function useAgentRun(workflowId: string, apiKey: string): {
+    status: RunStatus;
+    text: string;
+    steps: RunStep[];
+    output: unknown;
+    error: string | null;
+    executionId: string | undefined;
+    run: (input: unknown) => Promise<void>;
+    cancel: () => void;
+};
+interface RunField {
+    name: string;
+    label: string;
+    type?: 'text' | 'textarea' | 'number' | 'select' | 'boolean';
+    required?: boolean;
+    placeholder?: string;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    defaultValue?: string | number | boolean;
+}
+interface AgentRunnerProps {
+    /** Id of the deployed agent (workflow). */
+    workflowId: string;
+    /** An `execute`-scoped API key for this agent. Visible to the page; never a personal key. */
+    apiKey: string;
+    /** Form fields; their values become the agent's input object. Omit for a single text box. */
+    fields?: RunField[];
+    title?: string;
+    description?: string;
+    submitLabel?: string;
+    /** Called with the final output of a successful run. */
+    onResult?: (output: unknown) => void;
+    className?: string;
+}
+declare function AgentRunner({ workflowId, apiKey, fields, title, description, submitLabel, onResult, className, }: AgentRunnerProps): react.JSX.Element | null;
+
+/**
+ * Runs a deployed agent through `POST /api/workflows/:id/execute` and normalises its
+ * server-sent events. The platform emits two shapes depending on the run mode — the
+ * executor's typed events (`stream:chunk`, `block:completed`, `execution:completed`, …)
+ * and the streaming-response shape shared with chat (`{ blockId, chunk }`, `{ event:
+ * 'final', data }`) — and both are folded into one small event vocabulary here.
+ */
+
+type RunEvent = {
+    type: 'started';
+    executionId?: string;
+} | {
+    type: 'chunk';
+    blockId?: string;
+    text: string;
+} | {
+    type: 'step';
+    blockId: string;
+    name: string;
+    status: 'running' | 'done' | 'error';
+    durationMs?: number;
+} | {
+    type: 'done';
+    output: unknown;
+    success: boolean;
+} | {
+    type: 'error';
+    message: string;
+};
+interface RunOptions {
+    /** An `execute`-scoped API key. It is visible to the browser: scope it to this agent only. */
+    apiKey: string;
+    /** Free-form or structured input for the agent's start block. */
+    input?: unknown;
+    /** Outputs to stream, as `blockId_path` or `Block name.path`. */
+    selectedOutputs?: string[];
+}
+declare function runAgent(client: AginiesClient, workflowId: string, options: RunOptions, signal?: AbortSignal): AsyncGenerator<RunEvent>;
+/** Decodes an execute SSE body into run events. Exported for tests. */
+declare function parseRunSSE(stream: ReadableStream<Uint8Array>): AsyncGenerator<RunEvent>;
+
+export { ATTACHMENT_LIMITS, type ActivationConfig, type ActivationSession, type ActivationState, AgentRunner, type AgentRunnerProps, AginiesClient, type AginiesConfig, AginiesError, AginiesProvider, type AginiesProviderProps, ApprovalPanel, type ApprovalPanelProps, type ApprovalStatus, Button, type ButtonProps, type ChatAttachment, type ChatAuthRequired, type ChatConfig, type ChatFilePayload, type ChatMessage, type ChatStreamEvent, ChatWidget, type ChatWidgetProps, Chip, type CodeRequestResult, type CostBarItem, CostBars, type CostBarsProps, Eyebrow, Field, type HeatmapRow, Input, type Locale, Markdown, Panel, type PauseContext, type PausePoint, type PausedExecution, type ResumeField, type ResumeOutcome, type ResumeQueueEntry, type ResumeStatus, type RunEvent, type RunField, type RunOptions, type RunStatus, type RunStep, RunTimeline, type RunTimelineProps, type SendMessageInput, Spinner, Stat, type StatItem, StatTiles, type StructuredItem, type StructuredResponse, StructuredUI, SuccessHeatmap, type SuccessHeatmapProps, Tag, Textarea, type TimelineStep, buildSubmission, cx, fieldsOf, formatFieldValue, getClient, getPauseContext, getPausedExecution, init, initialValues, listPausedExecutions, outputOf, parseFieldValue, parseRunSSE, parseSSE, parseStructured, resumeExecution, runAgent, translator, useAgentRun, useAginies, useApproval, useChat, useModule };