@epistola.app/valtimo-plugin 0.6.0 → 0.8.0

package/lib/assets/epistola-logo.d.ts

@@ -1 +1 @@
-export declare const EPISTOLA_PLUGIN_LOGO_BASE64 = "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0iIzMzNjZjYyI+PHBhdGggZD0iTTE0IDJINmMtMS4xIDAtMiAuOS0yIDJ2MTZjMCAxLjEuOSAyIDIgMmgxMmMxLjEgMCAyLS45IDItMlY4bC02LTZ6bTQgMThINlY0aDd2NWg1djExeiIvPjxwYXRoIGQ9Ik04IDEyaDh2Mkg4em0wIDRoOHYtMkg4em0wLThWNmg0djJ6Ii8+PC9zdmc+";
+export declare const EPISTOLA_PLUGIN_LOGO_BASE64 = "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMjAgMTIwIiB3aWR0aD0iMTIwIiBoZWlnaHQ9IjEyMCI+CiAgPCEtLSBTdGFjayBiYXNlIC0tPgogIDxyZWN0IHg9IjM2IiB5PSIxNiIgd2lkdGg9IjU0IiBoZWlnaHQ9IjcwIiByeD0iMyIgZmlsbD0iI2U2YzJiMCIgc3Ryb2tlPSIjNGYyZjJiIiBzdHJva2Utd2lkdGg9IjIiIHRyYW5zZm9ybT0icm90YXRlKDUgNjMgNTEpIi8+CiAgPHJlY3QgeD0iMzIiIHk9IjIyIiB3aWR0aD0iNTQiIGhlaWdodD0iNzAiIHJ4PSIzIiBmaWxsPSIjZjBkOGM4IiBzdHJva2U9IiM0ZjJmMmIiIHN0cm9rZS13aWR0aD0iMiIvPgogIDxyZWN0IHg9IjI4IiB5PSIyOCIgd2lkdGg9IjU0IiBoZWlnaHQ9IjcwIiByeD0iMyIgZmlsbD0iI2Y1ZWJlMyIgc3Ryb2tlPSIjNGYyZjJiIiBzdHJva2Utd2lkdGg9IjIuNSIvPgogIDxsaW5lIHgxPSIzOCIgeTE9IjQ0IiB4Mj0iNzIiIHkyPSI0NCIgc3Ryb2tlPSIjYzRhODgyIiBzdHJva2Utd2lkdGg9IjIiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgogIDxsaW5lIHgxPSIzOCIgeTE9IjU0IiB4Mj0iNzIiIHkyPSI1NCIgc3Ryb2tlPSIjYzRhODgyIiBzdHJva2Utd2lkdGg9IjIiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgogIDxsaW5lIHgxPSIzOCIgeTE9IjY0IiB4Mj0iNTgiIHkyPSI2NCIgc3Ryb2tlPSIjYzRhODgyIiBzdHJva2Utd2lkdGg9IjIiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgogIDwhLS0gV2F4IHNlYWwgd2l0aCBjaGVja21hcmsgLS0+CiAgPGNpcmNsZSBjeD0iNTUiIGN5PSI4NCIgcj0iMTUiIGZpbGw9IiNiODVjM2MiIHN0cm9rZT0iIzRmMmYyYiIgc3Ryb2tlLXdpZHRoPSIyIi8+CiAgPGNpcmNsZSBjeD0iNTUiIGN5PSI4NCIgcj0iMTAuNSIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjZDQ4MzZhIiBzdHJva2Utd2lkdGg9IjEiLz4KICA8cG9seWxpbmUgcG9pbnRzPSI0OSw4NCA1Myw4OSA2Miw3OCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjNGYyZjJiIiBzdHJva2Utd2lkdGg9IjIuNSIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIi8+Cjwvc3ZnPgo=";

package/lib/components/check-job-status-configuration/check-job-status-configuration.component.d.ts

@@ -1,7 +1,7 @@
 import { EventEmitter, OnDestroy, OnInit } from '@angular/core';
 import { FunctionConfigurationComponent } from '@valtimo/plugin';
 import { FormOutput } from '@valtimo/components';
-import { Observable } from 'rxjs';
+import { BehaviorSubject, Observable } from 'rxjs';
 import { CheckJobStatusConfig } from '../../models';
 import * as i0 from "@angular/core";
 export declare class CheckJobStatusConfigurationComponent implements FunctionConfigurationComponent, OnInit, OnDestroy {
@@ -14,6 +14,9 @@ export declare class CheckJobStatusConfigurationComponent implements FunctionCon
     private saveSubscription;
     private readonly formValue$;
     private readonly valid$;
+    /** Resolved synchronously before the v-form renders — see download-document-configuration for the why. */
+    resolvedPrefill: Partial<CheckJobStatusConfig>;
+    readonly prefillResolved$: BehaviorSubject<boolean>;
     safeDisabled$: Observable<boolean>;
     ngOnInit(): void;
     ngOnDestroy(): void;

package/lib/components/download-document-configuration/download-document-configuration.component.d.ts

@@ -1,7 +1,7 @@
 import { EventEmitter, OnDestroy, OnInit } from '@angular/core';
 import { FunctionConfigurationComponent } from '@valtimo/plugin';
 import { FormOutput } from '@valtimo/components';
-import { Observable } from 'rxjs';
+import { BehaviorSubject, Observable } from 'rxjs';
 import { DownloadDocumentConfig } from '../../models';
 import * as i0 from "@angular/core";
 export declare class DownloadDocumentConfigurationComponent implements FunctionConfigurationComponent, OnInit, OnDestroy {
@@ -14,6 +14,13 @@ export declare class DownloadDocumentConfigurationComponent implements FunctionC
     private saveSubscription;
     private readonly formValue$;
     private readonly valid$;
+    /**
+     * Resolved prefill — populated synchronously before the v-form renders. Avoids the
+     * v-input `[defaultValue]` async-binding race that otherwise drops one of the
+     * fields when prefill arrives after mount.
+     */
+    resolvedPrefill: Partial<DownloadDocumentConfig>;
+    readonly prefillResolved$: BehaviorSubject<boolean>;
     safeDisabled$: Observable<boolean>;
     ngOnInit(): void;
     ngOnDestroy(): void;

package/lib/components/epistola-admin-page/epistola-admin-page.component.d.ts

@@ -1,7 +1,7 @@
 import { OnInit } from '@angular/core';
 import { ActivatedRoute, Router } from '@angular/router';
 import { EpistolaAdminService } from '../../services/epistola-admin.service';
-import { PendingJob, PluginUsageEntry } from '../../models';
+import { BpmnValidationViolation, PendingJob, PluginUsageEntry } from '../../models';
 import * as i0 from "@angular/core";
 /**
  * Combined view model for a single plugin configuration card.
@@ -26,8 +26,16 @@ export declare class EpistolaAdminPageComponent implements OnInit {
     cards: ConfigurationCard[];
     selectedCard: ConfigurationCard | null;
     activeTab: 'actions' | 'pending';
+    overviewTab: 'configurations' | 'validations';
     loading: boolean;
     pluginVersion: string | null;
+    validationViolations: BpmnValidationViolation[];
+    reconcilingExecutionIds: Set<string>;
+    reconcileFeedback: {
+        executionId: string;
+        type: 'success' | 'pending' | 'error';
+        message: string;
+    } | null;
     private connectionStatuses;
     private usageEntries;
     private pendingJobs;
@@ -40,8 +48,16 @@ export declare class EpistolaAdminPageComponent implements OnInit {
     selectConfiguration(card: ConfigurationCard): void;
     backToOverview(): void;
     setActiveTab(tab: 'actions' | 'pending'): void;
+    setOverviewTab(tab: 'configurations' | 'validations'): void;
     refresh(): void;
     exportProcessLink(entry: PluginUsageEntry): void;
+    /**
+     * Manually reconcile a single stuck catch event. Pulls the current Epistola job
+     * status and re-runs message correlation if the job is in a terminal state.
+     * Refreshes the Pending list on success so the row drops out of the table.
+     */
+    reconcilePending(job: PendingJob): void;
+    isReconciling(job: PendingJob): boolean;
     private updateUrl;
     private loadData;
     private tryBuildCards;

package/lib/components/epistola-document/epistola-document.component.d.ts

@@ -0,0 +1,65 @@
+import { ChangeDetectorRef, EventEmitter, OnDestroy, OnInit } from '@angular/core';
+import { DomSanitizer, SafeResourceUrl } from '@angular/platform-browser';
+import { FormioCustomComponent, FormIoStateService } from '@valtimo/components';
+import { EpistolaPluginService, EpistolaTaskContextService } from '../../services';
+import * as i0 from "@angular/core";
+export type EpistolaDocumentDisplay = 'inline' | 'button' | 'both';
+/**
+ * Unified Formio component for the after-generation Epistola PDF UX. Reads
+ * the PDF id and tenant id from named process variables on the caller's
+ * task via the {@code /documents/download} endpoint.
+ *
+ * <p>Three presentations, all backed by the same backend call:
+ * <ul>
+ *   <li>{@code display="inline"} — render the PDF inline in a panel.</li>
+ *   <li>{@code display="button"} — show a click-to-save download button only.</li>
+ *   <li>{@code display="both"} (default) — inline panel with a download icon
+ *       in the header.</li>
+ * </ul>
+ *
+ * <p>For the dry-run / what-would-be-generated UX use
+ * {@code epistola-document-preview} instead.
+ */
+export declare class EpistolaDocumentComponent implements FormioCustomComponent<unknown>, OnInit, OnDestroy {
+    private readonly epistolaPluginService;
+    private readonly sanitizer;
+    private readonly formIoStateService;
+    private readonly taskContext;
+    private readonly cdr;
+    value: unknown;
+    valueChange: EventEmitter<unknown>;
+    disabled: boolean;
+    label: string;
+    /** How to present the document. `both` (default) shows an inline panel with a download icon. */
+    display: EpistolaDocumentDisplay;
+    /**
+     * Process-variable name holding the Epistola result. Default: `epistolaResult`.
+     *
+     * Type-tolerant on the backend: if the named variable holds a rich result object
+     * (`Map<String, Object>` written by `generate-document` and updated by the result
+     * collector), the backend digs out the `documentId` key. If it holds a plain
+     * String (custom flow that wrote a bare id), the backend uses it as-is.
+     */
+    documentVariable: string;
+    /** Process-variable name holding the Epistola tenant id. Default: `epistolaTenantId`. */
+    tenantIdVariable: string;
+    /** Filename used for the download disposition. */
+    filename: string;
+    loading: boolean;
+    downloading: boolean;
+    error: string | null;
+    previewUrl: SafeResourceUrl | null;
+    private currentBlobUrl;
+    private subscription?;
+    get designMode(): boolean;
+    constructor(epistolaPluginService: EpistolaPluginService, sanitizer: DomSanitizer, formIoStateService: FormIoStateService, taskContext: EpistolaTaskContextService, cdr: ChangeDetectorRef);
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    refresh(): void;
+    download(): void;
+    private loadInline;
+    private buildRequest;
+    private revokeBlobUrl;
+    static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaDocumentComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaDocumentComponent, "epistola-document-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "display": { "alias": "display"; "required": false; }; "documentVariable": { "alias": "documentVariable"; "required": false; }; "tenantIdVariable": { "alias": "tenantIdVariable"; "required": false; }; "filename": { "alias": "filename"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
+}

package/lib/components/{epistola-download/epistola-download.formio.d.ts → epistola-document/epistola-document.formio.d.ts}

@@ -1,4 +1,4 @@
 import { Injector } from '@angular/core';
 import { FormioCustomComponentInfo } from '@valtimo/components';
-export declare const EPISTOLA_DOWNLOAD_OPTIONS: FormioCustomComponentInfo;
-export declare function registerEpistolaDownloadComponent(injector: Injector): void;
+export declare const EPISTOLA_DOCUMENT_OPTIONS: FormioCustomComponentInfo;
+export declare function registerEpistolaDocumentComponent(injector: Injector): void;

package/lib/components/epistola-document-preview/epistola-document-preview.component.d.ts

@@ -1,41 +1,52 @@
 import { ChangeDetectorRef, EventEmitter, OnChanges, OnDestroy, SimpleChanges } from '@angular/core';
-import { HttpClient } from '@angular/common/http';
 import { DomSanitizer, SafeResourceUrl } from '@angular/platform-browser';
 import { FormioCustomComponent, FormIoStateService } from '@valtimo/components';
-import { ConfigService } from '@valtimo/shared';
-import { PreviewSource } from '../../models';
-import { EpistolaPluginService } from '../../services';
+import { EpistolaPluginService, EpistolaTaskContextService } from '../../services';
 import * as i0 from "@angular/core";
-export declare class EpistolaDocumentPreviewComponent implements FormioCustomComponent<null>, OnChanges, OnDestroy {
+export declare class EpistolaDocumentPreviewComponent implements FormioCustomComponent<Record<string, any> | null>, OnChanges, OnDestroy {
     private readonly epistolaPluginService;
-    private readonly http;
     private readonly sanitizer;
-    private readonly configService;
     private readonly formIoStateService;
     private readonly cdr;
-    value: null;
-    valueChange: EventEmitter<null>;
+    private readonly taskContext;
+    value: Record<string, any> | null;
+    valueChange: EventEmitter<Record<string, any>>;
     disabled: boolean;
     label: string;
-    sources: PreviewSource[];
-    selectedIndex: number;
-    discovering: boolean;
+    processDefinitionKey?: string;
+    sourceActivityId?: string;
+    overrideMapping?: Record<string, any>;
     loading: boolean;
     error: string | null;
     previewUrl: SafeResourceUrl | null;
+    designMode: boolean;
     private initialized;
     private currentBlobUrl;
-    private discoverSubscription?;
     private previewSubscription?;
-    private readonly apiEndpoint;
-    constructor(epistolaPluginService: EpistolaPluginService, http: HttpClient, sanitizer: DomSanitizer, configService: ConfigService, formIoStateService: FormIoStateService, cdr: ChangeDetectorRef);
+    constructor(epistolaPluginService: EpistolaPluginService, sanitizer: DomSanitizer, formIoStateService: FormIoStateService, cdr: ChangeDetectorRef, taskContext: EpistolaTaskContextService);
+    /**
+     * Resolve the active task id from {@link EpistolaTaskContextService}, populated
+     * by {@code EpistolaTaskContextInterceptor} on the canonical Valtimo task-open
+     * call. Returns null when used outside a task context (e.g. Formio builder).
+     */
+    private get currentTaskId();
+    get overrideMappingScopes(): string[];
+    overrideMappingEntries(scope: string): {
+        path: string;
+        field: string;
+    }[];
     ngOnChanges(changes: SimpleChanges): void;
     ngOnDestroy(): void;
-    onSourceChange(event: Event): void;
     refresh(): void;
-    private discoverSources;
+    /**
+     * Preview using the explicitly configured process link + input overrides.
+     * Requires a runtime task context — the backend authorizes the request against
+     * the task's process instance and case document, so all three ids must match.
+     */
     private loadPreview;
+    private handlePreviewSuccess;
+    private handlePreviewError;
     private revokeBlobUrl;
     static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaDocumentPreviewComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaDocumentPreviewComponent, "epistola-document-preview-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaDocumentPreviewComponent, "epistola-document-preview-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "processDefinitionKey": { "alias": "processDefinitionKey"; "required": false; }; "sourceActivityId": { "alias": "sourceActivityId"; "required": false; }; "overrideMapping": { "alias": "overrideMapping"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
 }

package/lib/components/epistola-document-preview/preview-utils.d.ts

@@ -0,0 +1,18 @@
+import { OverrideMapping } from '../override-builder/override-builder.component';
+export declare const FORM_REF_PREFIX = "form:";
+/**
+ * Detect if a string value is a JSONata expression (vs a plain literal).
+ * Checks for characters that indicate JSONata operators: $, &, (, {, ?, [
+ */
+export declare function isExpression(value: string): boolean;
+/**
+ * Expand dot-notation keys into nested objects.
+ * e.g. { "beslissing.tekst": "value" } -> { beslissing: { tekst: "value" } }
+ */
+export declare function expandDotNotation(flat: Record<string, any>): Record<string, any>;
+/**
+ * Given an override mapping (scope -> { inputPath -> "form:<componentKey>" })
+ * and form data, produce the inputOverrides object for the backend.
+ * The "form:" prefix identifies form field references; the remainder is the Formio component key.
+ */
+export declare function computeInputOverrides(mapping: OverrideMapping, formData: Record<string, any>): Record<string, any>;

package/lib/components/epistola-retry-form/epistola-retry-form.component.d.ts

@@ -1,17 +1,14 @@
 import { ChangeDetectorRef, EventEmitter, OnChanges, OnDestroy, SimpleChanges } from '@angular/core';
-import { HttpClient } from '@angular/common/http';
 import { DomSanitizer, SafeResourceUrl } from '@angular/platform-browser';
 import { FormioCustomComponent, FormIoStateService } from '@valtimo/components';
-import { ConfigService } from '@valtimo/shared';
-import { EpistolaPluginService } from '../../services';
+import { EpistolaPluginService, EpistolaTaskContextService } from '../../services';
 import * as i0 from "@angular/core";
 export declare class EpistolaRetryFormComponent implements FormioCustomComponent<string>, OnChanges, OnDestroy {
     private readonly epistolaPluginService;
     private readonly formIoStateService;
     private readonly cdr;
-    private readonly http;
     private readonly sanitizer;
-    private readonly configService;
+    private readonly taskContext;
     value: string;
     valueChange: EventEmitter<string>;
     disabled: boolean;
@@ -32,9 +29,8 @@ export declare class EpistolaRetryFormComponent implements FormioCustomComponent
     private currentBlobUrl;
     private resolvedSourceActivityId?;
     private processDefinitionKey?;
-    private readonly apiEndpoint;
     formOptions: any;
-    constructor(epistolaPluginService: EpistolaPluginService, formIoStateService: FormIoStateService, cdr: ChangeDetectorRef, http: HttpClient, sanitizer: DomSanitizer, configService: ConfigService);
+    constructor(epistolaPluginService: EpistolaPluginService, formIoStateService: FormIoStateService, cdr: ChangeDetectorRef, sanitizer: DomSanitizer, taskContext: EpistolaTaskContextService);
     ngOnChanges(changes: SimpleChanges): void;
     ngOnDestroy(): void;
     togglePreview(): void;

package/lib/components/generate-document-configuration/generate-document-configuration.component.d.ts

@@ -4,7 +4,7 @@ import { FormOutput, SelectItem } from '@valtimo/components';
 import { CaseManagementParams, ManagementContext } from '@valtimo/shared';
 import { ProcessLinkStateService } from '@valtimo/process-link';
 import { BehaviorSubject, Observable } from 'rxjs';
-import { AsyncResource, ExpressionFunctionInfo, GenerateDocumentConfig, TemplateField, VariableSuggestions } from '../../models';
+import { AsyncResource, ExpressionFunctionInfo, GenerateDocumentConfig, JsonataFieldError, TemplateField, VariableSuggestions } from '../../models';
 import { EpistolaPluginService } from '../../services';
 import * as i0 from "@angular/core";
 export type VariantSelectionMode = 'explicit' | 'attributes';
@@ -35,11 +35,16 @@ export declare class GenerateDocumentConfigurationComponent implements FunctionC
     readonly selectedTemplateId$: BehaviorSubject<string>;
     readonly selectedVariantId$: BehaviorSubject<string>;
     variantSelectionMode: VariantSelectionMode;
+    variantIdExpressionMode: boolean;
+    variantIdExpression: string;
+    filenameExpressionMode: boolean;
+    filenameExpression: string;
     variantAttributeEntries: {
         key: string;
         value: string;
         required: boolean;
         _customKey?: boolean;
+        _expressionMode?: boolean;
     }[];
     availableAttributeKeys: string[];
     caseDefinitionKey: string | null;
@@ -51,6 +56,7 @@ export declare class GenerateDocumentConfigurationComponent implements FunctionC
         total: number;
     };
     prefillDataMapping: Record<string, any>;
+    validationErrors$: BehaviorSubject<JsonataFieldError[]>;
     private readonly destroy$;
     private saveSubscription;
     private readonly formValue$;
@@ -71,6 +77,8 @@ export declare class GenerateDocumentConfigurationComponent implements FunctionC
     addAttributeEntry(): void;
     removeAttributeEntry(index: number): void;
     onAttributeEntryChange(): void;
+    onVariantIdExpressionChange(): void;
+    onFilenameExpressionChange(): void;
     onKeySelected(entry: {
         key: string;
         value: string;
@@ -109,6 +117,17 @@ export declare class GenerateDocumentConfigurationComponent implements FunctionC
     private loadVariableSuggestions;
     private handleValid;
     private openSaveSubscription;
+    /**
+     * Build a JSONata validation request from the config and call the backend.
+     * Only fields that are JSONata expressions get validated:
+     * - dataMapping is always JSONata
+     * - filename / variantId only when their `fx` toggle is on
+     * - variant attribute values only when isExpression() reports true
+     * On invalid response, surface errors and abort the emit.
+     * If the validator endpoint itself fails (network/server), proceed with the
+     * emit — the validation is a quality-of-life check, not a hard gate.
+     */
+    private validateAndEmit;
     static ɵfac: i0.ɵɵFactoryDeclaration<GenerateDocumentConfigurationComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<GenerateDocumentConfigurationComponent, "epistola-generate-document-configuration", never, { "save$": { "alias": "save$"; "required": false; }; "disabled$": { "alias": "disabled$"; "required": false; }; "pluginId": { "alias": "pluginId"; "required": false; }; "prefillConfiguration$": { "alias": "prefillConfiguration$"; "required": false; }; "selectedPluginConfigurationData$": { "alias": "selectedPluginConfigurationData$"; "required": false; }; "context$": { "alias": "context$"; "required": false; }; }, { "valid": "valid"; "configuration": "configuration"; }, never, never, true, never>;
 }

package/lib/components/override-builder/override-builder.component.d.ts

@@ -0,0 +1,42 @@
+import { ChangeDetectorRef, EventEmitter } from '@angular/core';
+import { FormioCustomComponent } from '@valtimo/components';
+import * as i0 from "@angular/core";
+interface OverrideRow {
+    scope: 'doc' | 'pv';
+    inputPath: string;
+    formFieldKey: string;
+}
+export interface FormFieldOption {
+    key: string;
+    label: string;
+}
+/**
+ * Override mapping format: scope → { inputPath → "form:<componentKey>" }
+ * The "form:" prefix identifies this as a reference to a Formio component.
+ */
+export type OverrideMapping = Record<string, Record<string, string>>;
+export declare class EpistolaOverrideBuilderComponent implements FormioCustomComponent<OverrideMapping | null> {
+    private readonly cdr;
+    value: OverrideMapping | null;
+    valueChange: EventEmitter<OverrideMapping>;
+    disabled: boolean;
+    label: string;
+    availableFields: FormFieldOption[];
+    rows: OverrideRow[];
+    advancedMode: boolean;
+    jsonText: string;
+    jsonError: string | null;
+    private initialized;
+    constructor(cdr: ChangeDetectorRef);
+    ngOnChanges(): void;
+    toggleMode(): void;
+    addRow(): void;
+    removeRow(index: number): void;
+    emitChange(): void;
+    onJsonChange(text: string): void;
+    private rowsToMapping;
+    private mappingToRows;
+    static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaOverrideBuilderComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaOverrideBuilderComponent, "epistola-override-builder-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "availableFields": { "alias": "availableFields"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
+}
+export {};

package/lib/components/override-builder/override-builder.formio.d.ts

@@ -0,0 +1,4 @@
+import { Injector } from '@angular/core';
+import { FormioCustomComponentInfo } from '@valtimo/components';
+export declare const EPISTOLA_OVERRIDE_BUILDER_OPTIONS: FormioCustomComponentInfo;
+export declare function registerEpistolaOverrideBuilderComponent(injector: Injector): void;

package/lib/components/process-link-selector/process-link-selector.component.d.ts

@@ -0,0 +1,31 @@
+import { ChangeDetectorRef, EventEmitter, OnChanges, OnDestroy, SimpleChanges } from '@angular/core';
+import { FormioCustomComponent } from '@valtimo/components';
+import { EpistolaAdminService } from '../../services';
+import { PluginUsageEntry } from '../../models';
+import * as i0 from "@angular/core";
+export interface ProcessLinkSelection {
+    processDefinitionKey: string;
+    sourceActivityId: string;
+}
+export declare class EpistolaProcessLinkSelectorComponent implements FormioCustomComponent<ProcessLinkSelection | null>, OnChanges, OnDestroy {
+    private readonly adminService;
+    private readonly cdr;
+    value: ProcessLinkSelection | null;
+    valueChange: EventEmitter<ProcessLinkSelection>;
+    disabled: boolean;
+    label: string;
+    filteredEntries: PluginUsageEntry[];
+    selectedKey: string;
+    loading: boolean;
+    error: string | null;
+    private initialized;
+    private loadSubscription?;
+    constructor(adminService: EpistolaAdminService, cdr: ChangeDetectorRef);
+    ngOnChanges(changes: SimpleChanges): void;
+    ngOnDestroy(): void;
+    onSelect(key: string): void;
+    entryKey(entry: PluginUsageEntry): string;
+    private loadEntries;
+    static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaProcessLinkSelectorComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaProcessLinkSelectorComponent, "epistola-process-link-selector-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
+}

package/lib/components/process-link-selector/process-link-selector.formio.d.ts

@@ -0,0 +1,4 @@
+import { Injector } from '@angular/core';
+import { FormioCustomComponentInfo } from '@valtimo/components';
+export declare const EPISTOLA_PROCESS_LINK_SELECTOR_OPTIONS: FormioCustomComponentInfo;
+export declare function registerEpistolaProcessLinkSelectorComponent(injector: Injector): void;

package/lib/epistola-enabled.guard.d.ts

@@ -0,0 +1,2 @@
+import { CanActivateFn } from '@angular/router';
+export declare const epistolaEnabledGuard: CanActivateFn;

package/lib/epistola-runtime-config.d.ts

@@ -0,0 +1,28 @@
+export interface EpistolaRuntimeEnv {
+    epistolaEnabled?: boolean | string;
+}
+interface EpistolaRuntimeWindow {
+    env?: EpistolaRuntimeEnv;
+}
+declare global {
+    interface Window extends EpistolaRuntimeWindow {
+    }
+}
+/**
+ * Reads the runtime feature flag that decides whether the Epistola plugin
+ * surfaces (admin menu, /epistola route, plugin specification, Formio
+ * components) should activate in the host Valtimo app.
+ *
+ * The flag is sourced from `window['env']['epistolaEnabled']`, populated at
+ * container start by `envsubst` against `assets/config.template.js` (the
+ * standard Valtimo runtime-config pattern). Defaults to enabled — only the
+ * literal `false` or string `'false'` disables the plugin, matching the
+ * backend's `epistola.enabled` `matchIfMissing = true` semantics.
+ *
+ * Exposed as a runtime helper rather than evaluated directly in `@NgModule`
+ * decorator metadata because Angular's AOT compiler cannot statically resolve
+ * `window` accesses (NG1010). Read from runtime code such as specification
+ * property getters, route guards, or the environment initializer instead.
+ */
+export declare function isEpistolaEnabled(): boolean;
+export {};

package/lib/epistola.module.d.ts

@@ -9,14 +9,13 @@ import * as i6 from "./components/epistola-configuration/epistola-configuration.
 import * as i7 from "./components/generate-document-configuration/generate-document-configuration.component";
 import * as i8 from "./components/check-job-status-configuration/check-job-status-configuration.component";
 import * as i9 from "./components/download-document-configuration/download-document-configuration.component";
-import * as i10 from "./components/epistola-download/epistola-download.component";
+import * as i10 from "./components/epistola-document/epistola-document.component";
 import * as i11 from "./components/epistola-retry-form/epistola-retry-form.component";
-import * as i12 from "./components/epistola-preview-button/epistola-preview-button.component";
-import * as i13 from "./components/epistola-document-preview/epistola-document-preview.component";
-import * as i14 from "./components/epistola-admin-page/epistola-admin-page.component";
+import * as i12 from "./components/epistola-document-preview/epistola-document-preview.component";
+import * as i13 from "./components/epistola-admin-page/epistola-admin-page.component";
 export declare class EpistolaPluginModule {
     static forRoot(): ModuleWithProviders<EpistolaPluginModule>;
     static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaPluginModule, never>;
-    static ɵmod: i0.ɵɵNgModuleDeclaration<EpistolaPluginModule, never, [typeof i1.CommonModule, typeof i2.HttpClientModule, typeof i3.PluginTranslatePipeModule, typeof i4.FormModule, typeof i4.InputModule, typeof i4.SelectModule, typeof i5.EpistolaAdminRoutingModule, typeof i6.EpistolaConfigurationComponent, typeof i7.GenerateDocumentConfigurationComponent, typeof i8.CheckJobStatusConfigurationComponent, typeof i9.DownloadDocumentConfigurationComponent, typeof i10.EpistolaDownloadComponent, typeof i11.EpistolaRetryFormComponent, typeof i12.EpistolaPreviewButtonComponent, typeof i13.EpistolaDocumentPreviewComponent, typeof i14.EpistolaAdminPageComponent], [typeof i6.EpistolaConfigurationComponent, typeof i7.GenerateDocumentConfigurationComponent, typeof i8.CheckJobStatusConfigurationComponent, typeof i9.DownloadDocumentConfigurationComponent, typeof i10.EpistolaDownloadComponent, typeof i11.EpistolaRetryFormComponent, typeof i12.EpistolaPreviewButtonComponent, typeof i13.EpistolaDocumentPreviewComponent, typeof i14.EpistolaAdminPageComponent]>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<EpistolaPluginModule, never, [typeof i1.CommonModule, typeof i2.HttpClientModule, typeof i3.PluginTranslatePipeModule, typeof i4.FormModule, typeof i4.InputModule, typeof i4.SelectModule, typeof i5.EpistolaAdminRoutingModule, typeof i6.EpistolaConfigurationComponent, typeof i7.GenerateDocumentConfigurationComponent, typeof i8.CheckJobStatusConfigurationComponent, typeof i9.DownloadDocumentConfigurationComponent, typeof i10.EpistolaDocumentComponent, typeof i11.EpistolaRetryFormComponent, typeof i12.EpistolaDocumentPreviewComponent, typeof i13.EpistolaAdminPageComponent], [typeof i6.EpistolaConfigurationComponent, typeof i7.GenerateDocumentConfigurationComponent, typeof i8.CheckJobStatusConfigurationComponent, typeof i9.DownloadDocumentConfigurationComponent, typeof i10.EpistolaDocumentComponent, typeof i11.EpistolaRetryFormComponent, typeof i12.EpistolaDocumentPreviewComponent, typeof i13.EpistolaAdminPageComponent]>;
     static ɵinj: i0.ɵɵInjectorDeclaration<EpistolaPluginModule>;
 }

package/lib/models/admin.d.ts

@@ -47,3 +47,31 @@ export interface PluginUsageEntry {
     configurationTitle: string;
     problems: string[];
 }
+/**
+ * Outcome of a manual reconcile attempt for a stuck Epistola catch event.
+ * `correlated=true` means the Epistola job is in a terminal state and message
+ * correlation ran (count = how many process instances received it). `false`
+ * means the job is still PENDING/IN_PROGRESS — the backend returns 409.
+ */
+export interface ReconcileResult {
+    executionId: string;
+    processInstanceId: string;
+    tenantId: string;
+    requestId: string;
+    epistolaStatus: string;
+    correlatedCount: number | null;
+    correlated: boolean;
+}
+/**
+ * A BPMN race-safety violation reported by the backend's deployment validator.
+ * `code` is one of the constants in
+ * `app.epistola.valtimo.web.rest.dto.BpmnValidationViolation` (kept stable so
+ * the UI can render specific remediation copy per code).
+ */
+export interface BpmnValidationViolation {
+    processDefinitionKey: string;
+    processDefinitionName: string;
+    activityId: string;
+    code: string;
+    message: string;
+}

package/lib/models/config.d.ts

@@ -26,7 +26,7 @@ export interface VariantAttributeEntry {
  *
  * Variant selection supports two modes:
  * - Explicit: set variantId directly
- * - By attributes: set variantAttributes with key-value pairs (values can be value resolver expressions)
+ * - By attributes: set variantAttributes with key-value pairs (values can be JSONata expressions)
  */
 export interface GenerateDocumentConfig {
     catalogId: string;
@@ -55,19 +55,15 @@ export interface CheckJobStatusConfig {
  * Specifies which process variables to read from and write to.
  */
 export interface DownloadDocumentConfig {
-    documentIdVariable: string;
+    /**
+     * Name of the process variable that holds the result. May be a plain
+     * String document id (legacy) or a `Map<String, Object>` rich result with
+     * a `documentId` key (canonical, written by `generate-document` and
+     * updated by the result collector). The action extracts the document id.
+     */
+    documentVariable: string;
     contentVariable: string;
 }
-/**
- * A previewable document source discovered from running process instances.
- */
-export interface PreviewSource {
-    processDefinitionKey: string;
-    activityId: string;
-    templateId: string;
-    templateName: string;
-    processInstanceId: string;
-}
 export interface VariableSuggestions {
     doc: string[];
     pv: string[];
@@ -77,3 +73,22 @@ export interface EvaluationResult {
     result: Record<string, any> | null;
     error: string | null;
 }
+/**
+ * Request body for the JSONata save-time validation endpoint.
+ * All fields are optional; null/blank values are skipped.
+ */
+export interface ValidateJsonataRequest {
+    dataMapping?: string | null;
+    filename?: string | null;
+    variantId?: string | null;
+    variantAttributeValues?: Record<string, string> | null;
+}
+export interface JsonataFieldError {
+    field: string;
+    expression: string;
+    message: string;
+}
+export interface JsonataValidationResult {
+    valid: boolean;
+    errors: JsonataFieldError[];
+}

package/lib/services/epistola-admin.service.d.ts

@@ -1,7 +1,7 @@
 import { HttpClient } from '@angular/common/http';
 import { ConfigService } from '@valtimo/shared';
 import { Observable } from 'rxjs';
-import { ConnectionStatus, PendingJob, PluginUsageEntry, VersionInfo } from '../models';
+import { BpmnValidationViolation, ConnectionStatus, PendingJob, PluginUsageEntry, ReconcileResult, VersionInfo } from '../models';
 import * as i0 from "@angular/core";
 /**
  * Service for Epistola plugin administrative operations.
@@ -28,6 +28,19 @@ export declare class EpistolaAdminService {
      * Get all process instances currently waiting for an Epistola document generation result.
      */
     getPendingJobs(): Observable<PendingJob[]>;
+    /**
+     * Manually reconcile a stuck Epistola catch event by querying Epistola for the
+     * job's current status and re-running message correlation. Returns 200 with
+     * `correlated=true` on success, 409 with `correlated=false` when the job is
+     * still in flight, or surfaces a validation error when the execution can't be
+     * recovered (no subscription, missing variable, unknown tenant).
+     */
+    reconcilePending(executionId: string): Observable<ReconcileResult>;
+    /**
+     * Get the latest BPMN race-safety validation violations across deployed
+     * process definitions. Empty list = healthy.
+     */
+    getValidationViolations(): Observable<BpmnValidationViolation[]>;
     /**
      * Export a single process link as a .process-link.json file.
      */