@fluxo-dev/api-client-base 26.2.5 → 26.3.1

package/src/lib/ai/models/index.d.ts

@@ -1,12 +1,566 @@
-export * from './create-llm-settings';
-export * from './llm-settings';
-export * from './update-llm-settings';
-export * from './agent';
-export * from './create-agent';
-export * from './update-agent';
-export * from './orchestration';
-export * from './create-orchestration';
-export * from './update-orchestration';
-export * from './mcp-server';
-export * from './create-mcp-server';
-export * from './update-mcp-server';
+export declare enum LlmProvider {
+    OpenAI = 1,
+    AzureOpenAI = 2,
+    Anthropic = 3,
+    Google = 4,
+    Ollama = 5,
+    Custom = 99
+}
+export declare enum WorkflowPattern {
+    Sequential = 1,
+    Concurrent = 2,
+    Handoff = 3,
+    GroupChat = 4,
+    Magentic = 5,
+    Custom = 99
+}
+export declare enum ChatMessageRole {
+    User = 1,
+    Assistant = 2,
+    System = 3,
+    Tool = 4
+}
+export type ChatTargetType = 'agent' | 'workflow';
+export interface LlmConfigDto {
+    id: number;
+    name: string;
+    provider: LlmProvider;
+    model: string;
+    apiKeyMasked?: string;
+    endpointUrl?: string | null;
+    additionalParameters?: string | null;
+    isDefault: boolean;
+    createdAt: string;
+    /** USD per 1M input tokens — optional; drives the chat cost popover. */
+    inputCostPer1MTokens?: number | null;
+    /** USD per 1M output tokens — optional. */
+    outputCostPer1MTokens?: number | null;
+}
+export interface CreateLlmConfigCommand {
+    name: string;
+    provider: LlmProvider;
+    model: string;
+    apiKey?: string | null;
+    endpointUrl?: string | null;
+    additionalParameters?: string | null;
+    isDefault?: boolean;
+    inputCostPer1MTokens?: number | null;
+    outputCostPer1MTokens?: number | null;
+}
+export interface UpdateLlmConfigCommand {
+    name: string;
+    provider: LlmProvider;
+    model: string;
+    apiKey?: string | null;
+    endpointUrl?: string | null;
+    additionalParameters?: string | null;
+    isDefault?: boolean;
+    inputCostPer1MTokens?: number | null;
+    outputCostPer1MTokens?: number | null;
+}
+export interface AiAgentDto {
+    id: number;
+    name: string;
+    description?: string | null;
+    systemPrompt?: string | null;
+    llmConfigurationId: number;
+    llmConfigurationName?: string;
+    maxIterations: number;
+    isPublic: boolean;
+    createdAt: string;
+    enabledToolIds: string[];
+    /** Ids of McpServerConfiguration linked to this agent. */
+    enabledMcpServerIds: number[];
+    /** Ids of AiSkill linked to this agent. */
+    enabledSkillIds: number[];
+}
+export interface CreateAgentCommand {
+    name: string;
+    description?: string | null;
+    systemPrompt?: string | null;
+    llmConfigurationId: number;
+    maxIterations?: number;
+    isPublic?: boolean;
+}
+export interface UpdateAgentCommand extends CreateAgentCommand {
+}
+export interface UpdateAgentToolsCommand {
+    toolIds: string[];
+}
+export interface UpdateAgentMcpServersCommand {
+    mcpServerIds: number[];
+}
+export interface UpdateAgentSkillsCommand {
+    skillIds: number[];
+}
+export interface AiToolDto {
+    id: string;
+    name: string;
+    description: string;
+    category?: string | null;
+    parametersSchema?: string | null;
+}
+export interface AiWorkflowAgentEntry {
+    agentConfigurationId: number;
+    order: number;
+    role?: string | null;
+    /** Handoff/Magentic: marks the orchestrator/manager slot. Exactly one per workflow. */
+    isRouter?: boolean;
+    /** Handoff: natural-language hint shown to the router LLM so it knows when to delegate. */
+    handoffDescription?: string | null;
+}
+export interface AiWorkflowDto {
+    id: number;
+    name: string;
+    description?: string | null;
+    pattern: WorkflowPattern;
+    /** Upper bound on loop iterations (GroupChat / Magentic / Handoff back-references). */
+    maxIterations: number;
+    /** Optional system prompt for patterns with a manager LLM (GroupChat selector, Magentic). */
+    managerSystemPrompt?: string | null;
+    isPublic: boolean;
+    createdAt: string;
+    updatedAt: string;
+    agents: AiWorkflowAgentEntry[];
+}
+export interface CreateAiWorkflowCommand {
+    name: string;
+    description?: string | null;
+    pattern?: WorkflowPattern;
+    maxIterations?: number;
+    managerSystemPrompt?: string | null;
+    isPublic?: boolean;
+}
+export interface UpdateAiWorkflowCommand extends CreateAiWorkflowCommand {
+}
+export interface UpdateAiWorkflowAgentsCommand {
+    agents: AiWorkflowAgentEntry[];
+}
+/**
+ * Multimodal input profile for a chat target. Drives the paperclip UI: the frontend hides
+ * it entirely on targets that don't accept any attachments, and uses the MIME whitelist /
+ * size cap to validate before hitting the network.
+ */
+export interface AiChatCapabilitiesDto {
+    supportsImages: boolean;
+    supportsPdf: boolean;
+    maxAttachmentBytes: number;
+    /**
+     * Full set of MIME types accepted by the file picker. May include skill-staging
+     * types (e.g. .pptx/.docx) on agents with skills linked — those don't go to the
+     * LLM as content blocks (the bridge stages them in the script's cwd instead).
+     */
+    acceptedMimeTypes: string[];
+    /**
+     * Strict subset of `acceptedMimeTypes` the LLM consumes inline as content blocks.
+     * Currently the FE doesn't need to consult this list (the BE filters at dispatch
+     * time), but it's exposed for future UI hints (e.g. "this PDF will be read by the
+     * model" vs "this .pptx will be passed to a skill script").
+     */
+    llmInlineMimeTypes: string[];
+}
+export interface ChatTargetDto {
+    id: number;
+    type: ChatTargetType;
+    name: string;
+    description: string | null;
+    /** URL AG-UI da usare come runtimeUrl in CopilotKit (relativo, es. `/ai/agui/agent/1`) */
+    aguiUrl: string;
+    capabilities: AiChatCapabilitiesDto;
+}
+export interface StartConversationCommand {
+    /** Esattamente uno tra agentId e workflowId deve essere valorizzato */
+    agentId?: number | null;
+    workflowId?: number | null;
+}
+export interface StartConversationResult {
+    /** GUID — passare a CopilotKit come threadId */
+    threadId: string;
+    /** Passare a CopilotKit come runtimeUrl */
+    aguiUrl: string;
+}
+export interface ChatConversationSummaryDto {
+    id: string;
+    title: string | null;
+    targetName: string | null;
+    targetType: ChatTargetType;
+    agentId: number | null;
+    workflowId: number | null;
+    messageCount: number;
+    createdAt: string;
+    updatedAt: string;
+    /** User-assigned tags. Empty array when none. Lowercased server-side. */
+    tags?: string[];
+}
+export interface ChatConversationDetailDto {
+    id: string;
+    title: string | null;
+    targetName: string | null;
+    targetType: ChatTargetType;
+    agentId: number | null;
+    workflowId: number | null;
+    /** URL AG-UI per riprendere la sessione */
+    aguiUrl: string;
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * ExternalId of the currently-active leaf in the conversation tree. The frontend uses it
+     * to populate `lastAssistantMessageIdRef` on load AND to drive "you're on branch X" UI.
+     * Null only on empty conversations.
+     */
+    activeLeafExternalId: string | null;
+    /** Multimodal capability profile of the target backing this conversation. */
+    capabilities: AiChatCapabilitiesDto;
+    /**
+     * LLM model id used by the conversation's target (e.g. "claude-haiku-4-5-20251001").
+     * Null for workflows (they aggregate multiple agents, each with its own model).
+     */
+    model?: string | null;
+    /** LLM provider (e.g. "Anthropic", "OpenAI"). Pairs with `model`. */
+    provider?: string | null;
+    /**
+     * USD per 1 000 000 input tokens — configured server-side on the LlmConfiguration.
+     * Null when the admin hasn't set a price; the frontend then hides the cost row.
+     */
+    inputCostPer1MTokens?: number | null;
+    /** USD per 1 000 000 output tokens. See `inputCostPer1MTokens`. */
+    outputCostPer1MTokens?: number | null;
+    /** Lifetime token usage for this conversation, used for the cost-transparency UI. */
+    usage?: AiChatUsageDto;
+    /**
+     * The active-branch chain (root → leaf), each entry carrying sibling metadata for the
+     * branch navigator. NOT paginated — a single chain is bounded by definition.
+     */
+    messages: AiChatMessageDto[];
+}
+/** Per-conversation token-usage summary. Cost computation is client-side. */
+export interface AiChatUsageDto {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens?: number;
+}
+export interface RenameConversationCommand {
+    title: string;
+}
+/** Body of `PUT /chat/conversation/{id}/tags`. Replaces ALL tags atomically. */
+export interface UpdateConversationTagsCommand {
+    tags: string[];
+}
+/**
+ * Body of `PUT /chat/conversation/{id}/active-leaf`. Pass the ExternalId of the message you
+ * want to make the active "tip" of the conversation. The backend persists this; the next
+ * `getConversation` returns the chain walked from that ExternalId back to the root.
+ */
+export interface SetActiveLeafCommand {
+    externalId: string;
+}
+export interface AiChatMessageDto {
+    id: number;
+    /** Stable UUID pre-generated by the client; the API uses this as the message identity. */
+    externalId: string;
+    /** ExternalId of the parent message in the conversation tree; null for the first message. */
+    parentExternalId?: string | null;
+    conversationId: string;
+    role: ChatMessageRole;
+    content: string;
+    /** Valorizzato per tool_use / tool_result — collega il risultato alla call originaria. */
+    toolCallId?: string | null;
+    /** Valorizzato solo per i messaggi tool */
+    toolName?: string | null;
+    /** JSON serializzato degli argomenti al tool */
+    toolArguments?: string | null;
+    /**
+     * Sub-agent name that produced this assistant row in a workflow chat (e.g. "Router",
+     * "Assistente vendite"). Drives the per-bubble header label. Null for single-agent chats
+     * and non-assistant rows.
+     */
+    authorName?: string | null;
+    createdAt: string;
+    /**
+     * ExternalIds of every message that shares this message's parent (including itself),
+     * ordered by CreatedAt. Lets the UI render a branch navigator (< n/N >) on messages that
+     * have edit-siblings. Empty list when the message has no siblings (root row, or only
+     * child of its parent).
+     */
+    siblingExternalIds: string[];
+    /** Zero-based index of this message within `siblingExternalIds`. */
+    siblingIndex: number;
+    /**
+     * Binary attachments bound to this message (only meaningful for user role). Empty when
+     * the message has no attachments. Each entry carries metadata + a relative ContentUrl
+     * the frontend uses for thumbnails / downloads.
+     */
+    attachments: AiChatAttachmentDto[];
+}
+/**
+ * Persisted attachment metadata. The bytes live in the application's IFluxoBlobStore
+ * implementation; this object only carries identity, MIME, and a resolvable URL.
+ */
+/**
+ * Origin of an attachment. Mirrors the C# enum <c>AiChatAttachmentSource</c>.
+ * The chat UI's attachments drawer surfaces this as a small badge so users
+ * know whether they uploaded the file themselves or whether a skill script
+ * produced it.
+ */
+export declare enum AiChatAttachmentSource {
+    User = 0,
+    SkillOutput = 1
+}
+export interface AiChatAttachmentDto {
+    /** DB id used to reference the row in the attachment-ids header at send time. */
+    id: number;
+    /** ExternalId of the bound user message. Null for orphan (uploaded but never sent). */
+    messageExternalId: string | null;
+    fileName: string;
+    mimeType: string;
+    sizeBytes: number;
+    /** Server-relative URL (`/ai/chat/conversation/{id}/attachments/{id}/content`). */
+    contentUrl: string;
+    createdAt: string;
+    /** Provenance — drives the badge / icon shown in the drawer. */
+    source: AiChatAttachmentSource;
+    /** When source=SkillOutput, the name of the script that produced this file. Null otherwise. */
+    producedByScriptName: string | null;
+    /**
+     * LLM-supplied tool_call id (matches `ToolCallChatMessage.toolCallId`) of the
+     * tool_call whose execution produced this file. Used by the chat UI to attribute
+     * the file chip to its specific tool_call card with O(1) deterministic equality.
+     * Null on user uploads or on harvests run outside an LLM tool-call context.
+     */
+    producedByToolCallId: string | null;
+}
+export interface PagedResult<T> {
+    items: T[];
+    totalCount: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+export interface AiPromptTemplateDto {
+    id: number;
+    title: string;
+    body: string;
+    tags: string[];
+    /**
+     * Agents this template is scoped to. Empty = global (visible to every chat).
+     * Non-empty = visible only when the active conversation's `agentId` matches one
+     * of these ids. Workflow conversations (no single agentId) only see globals.
+     */
+    agentIds: number[];
+    /** FluxoUser.Id of the original author. Audit-only — does not gate edit/delete. */
+    createdByUserId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateAiPromptTemplateCommand {
+    title: string;
+    body: string;
+    tags?: string[];
+    /** Empty / undefined = global. */
+    agentIds?: number[];
+}
+export interface UpdateAiPromptTemplateCommand {
+    title: string;
+    body: string;
+    tags?: string[];
+    agentIds?: number[];
+}
+/**
+ * Transport protocol of an MCP server. Values match the C# enum
+ * <c>McpServerTransport</c> on the BE (Stdio=1, Sse=2).
+ */
+export declare enum McpServerTransport {
+    Stdio = 1,
+    Sse = 2
+}
+/**
+ * Authentication scheme applied to MCP transport requests. Values match the
+ * C# enum <c>McpServerAuthType</c>. OAuth (=4) reserved for future use.
+ */
+export declare enum McpServerAuthType {
+    None = 1,
+    ApiKey = 2,
+    Bearer = 3
+}
+export interface McpServerConfigurationDto {
+    id: number;
+    name: string;
+    description?: string | null;
+    transport: McpServerTransport;
+    /** Stdio: executable name. Null for other transports. */
+    command?: string | null;
+    /** Stdio: argv. Empty for other transports. */
+    arguments: string[];
+    /** Sse: server URL. Null for other transports. */
+    endpoint?: string | null;
+    authType: McpServerAuthType;
+    /** `***xxxx` mask of the encrypted secret, or null when no auth is set. */
+    authSecretMasked?: string | null;
+    authHeaderName?: string | null;
+    requireApproval: boolean;
+    toolListCacheTtlMinutes: number;
+    isEnabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateMcpServerCommand {
+    name: string;
+    description?: string | null;
+    transport: McpServerTransport;
+    command?: string | null;
+    arguments?: string[];
+    endpoint?: string | null;
+    authType: McpServerAuthType;
+    /** Plaintext — encrypted server-side. */
+    authSecret?: string | null;
+    authHeaderName?: string | null;
+    requireApproval: boolean;
+    toolListCacheTtlMinutes: number;
+    isEnabled: boolean;
+}
+export interface UpdateMcpServerCommand extends CreateMcpServerCommand {
+}
+export interface McpServerTestResultDto {
+    success: boolean;
+    toolNames: string[];
+    error?: string | null;
+    durationMs?: number | null;
+}
+/**
+ * One tool the agent has access to at runtime. Returned by
+ * `GET /agent/{id}/available-tools` for both native (server-registered) and
+ * MCP (pulled from a linked MCP server's pool) tools. The FE uses `source` to
+ * tag the tool_call card and group the /tools modal.
+ */
+export interface AvailableToolDto {
+    name: string;
+    description?: string | null;
+    /** `'native'` or `'mcp:<server-name>'`. */
+    source: string;
+    requiresApproval: boolean;
+}
+/**
+ * One skill currently linked to the agent. Returned by
+ * `GET /agent/{id}/available-skills`. The FE uses `name` to match the
+ * `skillName` argument carried by the synthetic skill tool_calls
+ * (`load_skill`, `read_skill_resource`, `run_skill_script`) and attribute
+ * the call back to a row in the chat UI / `/tools` modal.
+ */
+export interface AvailableSkillDto {
+    id: number;
+    name: string;
+    description: string;
+    resourceCount: number;
+    scriptCount: number;
+    /** Number of supporting files attached via the tree-faithful import path. */
+    fileCount: number;
+    /** Mirrors the global per-skill flag. Stored but not enforced in v1. */
+    requireApproval: boolean;
+}
+/** Maps 1:1 to the C# enum AiSkillScriptLanguage. */
+export declare enum AiSkillScriptLanguage {
+    Python = 1,
+    JavaScript = 2,
+    Bash = 3
+}
+/**
+ * Maps 1:1 to the C# enum AiSkillScriptRunner. `Wasm` is reserved for v2 (the
+ * Wasmtime-based sandbox runner) — picking it today returns an error from the
+ * registry lookup since no Wasm runner is registered in v1.
+ */
+export declare enum AiSkillScriptRunner {
+    Subprocess = 1,
+    Wasm = 2
+}
+export interface AiSkillDto {
+    id: number;
+    name: string;
+    description: string;
+    instructions: string;
+    requireApproval: boolean;
+    createdByUserId: string;
+    createdAt: string;
+    updatedAt: string;
+    resources: AiSkillResourceDto[];
+    scripts: AiSkillScriptDto[];
+    /**
+     * Supporting files (tree-faithful import path). Metadata only — fetch the
+     * bytes on demand via `GET /ai/skill/{skillId}/files/{fileId}/content`. Empty
+     * for hand-authored skills that rely on resources + scripts.
+     */
+    files: AiSkillFileDto[];
+}
+export interface AiSkillFileDto {
+    id: number;
+    /** Forward-slash, relative to skill root. E.g. `"scripts/office/helpers/merge_runs.py"`. */
+    relativePath: string;
+    mimeType: string;
+    sizeBytes: number;
+    createdAt: string;
+}
+/** Content-fetch payload for a single file. Content is base64-encoded by ASP.NET's
+ *  System.Text.Json byte[] serialiser. Decode client-side when rendering. */
+export interface AiSkillFileContentDto {
+    id: number;
+    relativePath: string;
+    mimeType: string;
+    sizeBytes: number;
+    /** Base64-encoded raw bytes. */
+    content: string;
+}
+export interface AiSkillResourceDto {
+    id: number;
+    name: string;
+    description?: string | null;
+    content: string;
+}
+export interface AiSkillScriptDto {
+    id: number;
+    name: string;
+    description?: string | null;
+    parametersSchema: string;
+    language: AiSkillScriptLanguage;
+    runner: AiSkillScriptRunner;
+    body: string;
+}
+/**
+ * Create/update commands carry the same shape. Nested rows: include `id` for
+ * existing rows to preserve identity through the BE diff; omit / null for new
+ * rows; rows in the DB but absent from the command list get deleted.
+ */
+export interface CreateAiSkillCommand {
+    name: string;
+    description: string;
+    instructions: string;
+    requireApproval: boolean;
+    resources: AiSkillResourceCommand[];
+    scripts: AiSkillScriptCommand[];
+}
+export type UpdateAiSkillCommand = CreateAiSkillCommand;
+export interface AiSkillResourceCommand {
+    /** Existing row id when editing, null/undefined when creating fresh. */
+    id?: number | null;
+    name: string;
+    description?: string | null;
+    content: string;
+}
+export interface AiSkillScriptCommand {
+    id?: number | null;
+    name: string;
+    description?: string | null;
+    parametersSchema: string;
+    language: AiSkillScriptLanguage;
+    runner: AiSkillScriptRunner;
+    body: string;
+}
+export interface TestSkillScriptCommand {
+    argsJson: string;
+    timeoutSeconds?: number | null;
+}
+export interface AiSkillScriptTestResultDto {
+    success: boolean;
+    output?: string | null;
+    error?: string | null;
+    durationMs?: number | null;
+    exitCode?: number | null;
+}

package/src/lib/communication/mail-template/email-template.service.d.ts

@@ -1,6 +1,8 @@
 import { BaseCommonService } from '../../infrastructure';
-import { EmailTemplate, EmailTemplateType, EmailTemplateVariableDescription } from './models';
+import { EmailTemplate, EmailTemplateCatalogEntry, EmailTemplateType, EmailTemplateVariableDescription } from './models';
 export declare class EmailTemplateService extends BaseCommonService<EmailTemplate> {
     constructor();
+    getCatalog(): Promise<EmailTemplateCatalogEntry[]>;
     getVariablesDescription(type: EmailTemplateType): Promise<EmailTemplateVariableDescription[]>;
+    getVariablesDescriptionForCustomTemplate(slug: string): Promise<EmailTemplateVariableDescription[]>;
 }

package/src/lib/communication/mail-template/models/email-template-catalog-entry.d.ts

@@ -0,0 +1,9 @@
+import { EmailTemplate } from './email-template';
+import { EmailTemplateType } from './email-template-type';
+export interface EmailTemplateCatalogEntry {
+    typeId: EmailTemplateType;
+    slug: string | null;
+    displayName: string;
+    group: string;
+    templates: EmailTemplate[];
+}

package/src/lib/communication/mail-template/models/email-template-type.d.ts

@@ -4,5 +4,6 @@ export declare enum EmailTemplateType {
     WelcomeWithCredentialsAndAccessLinkForExternalUser = 3,
     WelcomeWithCredentialsForExternalUser = 4,
     PasswordReset = 5,
-    PasswordRecovery = 6
+    PasswordRecovery = 6,
+    Custom = 999
 }

package/src/lib/communication/mail-template/models/email-template.d.ts

@@ -7,4 +7,7 @@ export interface EmailTemplate {
     isDefault: boolean;
     subject: string;
     body: string;
+    slug?: string | null;
+    group?: string | null;
+    displayName?: string | null;
 }

package/src/lib/communication/mail-template/models/index.d.ts

@@ -1,3 +1,4 @@
 export * from './email-template';
+export * from './email-template-catalog-entry';
 export * from './email-template-type';
 export * from './email-template-variable-description';

package/src/lib/configuration/configuration.service.d.ts

@@ -6,7 +6,7 @@ import { DomainRole } from "../security/domain-role/index";
 import { Permission } from "../security/permission/index";
 import { AppMenu } from "./app-menu";
 import { AppMenuCreateCommand } from "./app-menu-create-command";
-import { WebMenuExport } from './models';
+import { WebMenuExport, ModuleVariableGroupDto } from './models';
 export type InitialConfiguration = {
     apps: FluxoApp[];
     menu: AppMenuItem[];
@@ -28,6 +28,10 @@ export type SystemSettings = {
     allowExternalUsers: boolean;
     twoFactorEnabled: boolean;
     isWorkflowEnabled: boolean;
+    isAIEnabled: boolean;
+    moduleVariables: {
+        [id: string]: string;
+    };
 };
 export declare enum FluxoACLMode {
     DomainRole = 1,
@@ -56,4 +60,6 @@ export declare class ConfigurationService {
         domainRoleId: number;
         frontends: string[];
     }[]>;
+    getModuleVariables(scope?: string, moduleName?: string): Promise<ModuleVariableGroupDto[]>;
+    updateModuleVariableValue(compositeId: string, value?: string): Promise<void>;
 }

package/src/lib/configuration/models/index.d.ts

@@ -3,3 +3,4 @@ export * from './feature';
 export * from './feature-list';
 export * from './update-routes-command';
 export * from './web-menu-export';
+export * from './module-variable';

package/src/lib/configuration/models/module-variable.d.ts

@@ -0,0 +1,23 @@
+export interface ModuleVariableGroupDto {
+    scope: string;
+    moduleName: string;
+    description: string;
+    variables: ModuleVariableDto[];
+}
+export interface ModuleVariableDto {
+    id: string;
+    compositeId: string;
+    name: string;
+    description?: string;
+    type: 'String' | 'Boolean' | 'Int' | 'Decimal' | 'Select' | 'Secret';
+    defaultValue?: string;
+    value?: string;
+    effectiveValue?: string;
+    options?: string;
+    group?: string;
+    visibleWhenVariableId?: string;
+    visibleWhenValue?: string;
+}
+export interface UpdateModuleVariableValueCommand {
+    value?: string;
+}