@epistola.app/valtimo-plugin 0.7.0 → 0.9.0

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, ChangelogRelease, ClasspathCatalog, PendingJob, PluginUsageEntry } from '../../models';
 import * as i0 from "@angular/core";
 /**
  * Combined view model for a single plugin configuration card.
@@ -25,9 +25,27 @@ export declare class EpistolaAdminPageComponent implements OnInit {
     private readonly router;
     cards: ConfigurationCard[];
     selectedCard: ConfigurationCard | null;
-    activeTab: 'actions' | 'pending';
+    activeTab: 'actions' | 'pending' | 'catalogs';
+    overviewTab: 'configurations' | 'validations' | 'changelog';
     loading: boolean;
     pluginVersion: string | null;
+    changelog: ChangelogRelease[] | null;
+    changelogLoading: boolean;
+    validationViolations: BpmnValidationViolation[];
+    reconcilingExecutionIds: Set<string>;
+    reconcileFeedback: {
+        executionId: string;
+        type: 'success' | 'pending' | 'error';
+        message: string;
+    } | null;
+    catalogs: ClasspathCatalog[];
+    catalogsLoading: boolean;
+    redeployingSlugs: Set<string>;
+    catalogFeedback: {
+        slug: string;
+        type: 'success' | 'error';
+        message: string;
+    } | null;
     private connectionStatuses;
     private usageEntries;
     private pendingJobs;
@@ -39,9 +57,32 @@ export declare class EpistolaAdminPageComponent implements OnInit {
     ngOnInit(): void;
     selectConfiguration(card: ConfigurationCard): void;
     backToOverview(): void;
-    setActiveTab(tab: 'actions' | 'pending'): void;
+    setActiveTab(tab: 'actions' | 'pending' | 'catalogs'): void;
+    setOverviewTab(tab: 'configurations' | 'validations' | 'changelog'): void;
+    private loadChangelog;
     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;
+    /**
+     * Load the classpath catalogs available to (re)deploy for the given
+     * configuration. Lazy — only called when a configuration is opened, not for
+     * every card in the overview.
+     */
+    private loadCatalogs;
+    /**
+     * Force-redeploy a single classpath catalog to the selected configuration's
+     * Epistola installation. Explicit operator action — the backend bypasses the
+     * templateSyncEnabled gate and the version-skip check. Reloads the catalog
+     * list on success so the deployed version / up-to-date hint refreshes.
+     */
+    redeployCatalog(catalog: ClasspathCatalog): void;
+    isRedeploying(catalog: ClasspathCatalog): 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,18 +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 { PreviewSource } from '../../models';
-import { EpistolaPluginService } from '../../services';
+import { EpistolaPluginService, EpistolaTaskContextService } from '../../services';
 import * as i0 from "@angular/core";
 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;
+    private readonly taskContext;
     value: Record<string, any> | null;
     valueChange: EventEmitter<Record<string, any>>;
     disabled: boolean;
@@ -20,21 +16,20 @@ export declare class EpistolaDocumentPreviewComponent implements FormioCustomCom
     processDefinitionKey?: string;
     sourceActivityId?: string;
     overrideMapping?: Record<string, any>;
-    sources: PreviewSource[];
-    selectedIndex: number;
-    discovering: boolean;
     loading: boolean;
     error: string | null;
     previewUrl: SafeResourceUrl | null;
     designMode: boolean;
     private initialized;
     private currentBlobUrl;
-    private discoverSubscription?;
     private previewSubscription?;
-    private readonly apiEndpoint;
-    /** Whether the component is in configured mode (explicit process link) vs auto-discover mode */
-    private get configuredMode();
-    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;
@@ -42,20 +37,13 @@ export declare class EpistolaDocumentPreviewComponent implements FormioCustomCom
     }[];
     ngOnChanges(changes: SimpleChanges): void;
     ngOnDestroy(): void;
-    onSourceChange(event: Event): void;
     refresh(): void;
     /**
-     * Configured mode: preview using the explicitly configured process link + input overrides.
-     */
-    private loadConfiguredPreview;
-    /**
-     * Auto-discover mode: discover sources from running process instances.
-     */
-    private discoverSources;
-    /**
-     * Auto-discover mode: load preview for the selected discovered source.
+     * 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 loadDiscoveredPreview;
+    private loadPreview;
     private handlePreviewSuccess;
     private handlePreviewError;
     private revokeBlobUrl;

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/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,75 @@ 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 catalog discovered on the application classpath, with whether it currently
+ * exists in the connected Epistola installation. `status` is resolved live by
+ * querying Epistola at request time:
+ * - `IN_EPISTOLA` — a catalog with this slug exists in Epistola.
+ * - `NOT_IN_EPISTOLA` — Epistola was reached and has no such catalog (redeploy it).
+ * - `UNKNOWN` — Epistola could not be reached, so existence is undetermined.
+ */
+export interface ClasspathCatalog {
+    slug: string;
+    version: string;
+    status: 'IN_EPISTOLA' | 'NOT_IN_EPISTOLA' | 'UNKNOWN';
+}
+/**
+ * Outcome of a manual single-catalog redeploy. `success=false` carries the
+ * reason in `errorMessage`; the backend returns HTTP 502 in that case.
+ */
+export interface CatalogRedeployResult {
+    slug: string;
+    version: string;
+    success: boolean;
+    catalogKey: string | null;
+    installed: number;
+    updated: number;
+    failed: number;
+    total: number;
+    errorMessage: string | null;
+}
+/**
+ * A "Keep a Changelog" section within a release (e.g. "Added") and its items.
+ */
+export interface ChangelogSection {
+    title: string;
+    items: string[];
+}
+/**
+ * One release block from the bundled CHANGELOG, parsed server-side (newest
+ * first). `date` is null for the Unreleased block.
+ */
+export interface ChangelogRelease {
+    version: string;
+    date: string | null;
+    sections: ChangelogSection[];
+}
+/**
+ * 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

@@ -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[];

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, CatalogRedeployResult, ChangelogRelease, ClasspathCatalog, ConnectionStatus, PendingJob, PluginUsageEntry, ReconcileResult, VersionInfo } from '../models';
 import * as i0 from "@angular/core";
 /**
  * Service for Epistola plugin administrative operations.
@@ -28,6 +28,37 @@ 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[]>;
+    /**
+     * List the classpath catalogs available to manually redeploy for a plugin
+     * configuration, each annotated with the version last deployed in this
+     * backend process.
+     */
+    getClasspathCatalogs(configurationId: string): Observable<ClasspathCatalog[]>;
+    /**
+     * Force-redeploy a single classpath catalog to the configuration's Epistola
+     * installation. Explicit operator action — bypasses the templateSyncEnabled
+     * gate and the version-skip check. Returns 200 with per-resource counts on
+     * success, or 502 (error callback, body carries `errorMessage`) on failure.
+     */
+    redeployCatalog(configurationId: string, slug: string): Observable<CatalogRedeployResult>;
+    /**
+     * Get the plugin CHANGELOG parsed (server-side) into structured releases for
+     * the admin Changelog tab — no markdown renderer needed on the client.
+     */
+    getChangelog(): Observable<ChangelogRelease[]>;
     /**
      * Export a single process link as a .process-link.json file.
      */

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

@@ -1,8 +1,38 @@
 import { HttpClient } from '@angular/common/http';
 import { ConfigService } from '@valtimo/shared';
 import { Observable } from 'rxjs';
-import { AttributeDefinition, CatalogInfo, EnvironmentInfo, ExpressionFunctionInfo, JsonataValidationResult, PreviewSource, TemplateDetails, TemplateInfo, EvaluationResult, ValidateJsonataRequest, VariableSuggestions, VariantInfo } from '../models';
+import { AttributeDefinition, CatalogInfo, EnvironmentInfo, ExpressionFunctionInfo, JsonataValidationResult, TemplateDetails, TemplateInfo, EvaluationResult, ValidateJsonataRequest, VariableSuggestions, VariantInfo } from '../models';
 import * as i0 from "@angular/core";
+/**
+ * Body of a {@link EpistolaPluginService.previewToBlob} call. Mirrors the
+ * backend {@code PreviewRequest} record. {@code processInstanceId},
+ * {@code processDefinitionKey} and {@code sourceActivityId} together identify
+ * the {@code generate-document} process link being previewed; {@code overrides}
+ * and {@code inputOverrides} let the caller substitute data before the
+ * JSONata mapping runs.
+ */
+export interface PreviewBlobRequest {
+    taskId: string;
+    documentId: string;
+    processDefinitionKey?: string | null;
+    sourceActivityId?: string | null;
+    processInstanceId?: string | null;
+    inputOverrides?: Record<string, unknown> | null;
+    overrides?: Record<string, unknown> | null;
+}
+/**
+ * Query-string parameters for {@link EpistolaPluginService.downloadDocumentBlob}.
+ * The backend resolves the Epistola PDF id and tenant id from the named process
+ * variables on the caller's task — no raw PDF id is sent on the wire.
+ */
+export interface DownloadDocumentRequest {
+    taskId: string;
+    caseDocumentId: string;
+    documentVariable: string;
+    tenantIdVariable: string;
+    filename: string;
+    disposition: 'attachment' | 'inline';
+}
 /**
  * Service for interacting with Epistola plugin API endpoints.
  * Provides methods to fetch templates, environments, variants,
@@ -51,8 +81,10 @@ export declare class EpistolaPluginService {
     evaluateMapping(expression: string, documentId: string, processInstanceId?: string): Observable<EvaluationResult>;
     /**
      * Get a dynamically generated Formio form for retrying a failed document generation.
+     *
+     * @param taskId Operaton user task id (required — backend authorizes via OperatonTask:VIEW)
      */
-    getRetryForm(processInstanceId: string, documentId?: string, sourceActivityId?: string): Observable<any>;
+    getRetryForm(taskId: string, processInstanceId: string, documentId?: string, sourceActivityId?: string): Observable<any>;
     /**
      * List all available expression functions for expr: data mapping values.
      */
@@ -63,14 +95,21 @@ export declare class EpistolaPluginService {
      */
     validateJsonata(request: ValidateJsonataRequest): Observable<JsonataValidationResult>;
     /**
-     * Discover all previewable document sources for a given Valtimo document.
+     * Preview a document by dry-running the {@code generate-document} process
+     * link. Returns the rendered PDF as a {@link Blob}.
+     *
+     * <p>The {@code X-Skip-Interceptor: 422} header tells the global Valtimo
+     * error interceptor to skip its toast for validation failures so the
+     * caller can render an inline error message.
      */
-    getPreviewSources(documentId: string): Observable<PreviewSource[]>;
+    previewToBlob(request: PreviewBlobRequest): Observable<Blob>;
     /**
-     * Preview a document by dry-running the generate-document process link.
-     * Returns the resolved data as a mock preview (Phase 1).
+     * Stream an already-generated Epistola PDF for the caller's task. The
+     * backend resolves the Epistola document id and tenant id from the named
+     * process variables on the task's process instance, so the wire never
+     * carries a raw PDF id.
      */
-    previewDocument(documentId: string, processDefinitionKey: string, sourceActivityId: string, processInstanceId?: string, overrides?: Record<string, any>): Observable<any>;
+    downloadDocumentBlob(request: DownloadDocumentRequest): Observable<Blob>;
     static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaPluginService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<EpistolaPluginService>;
 }

package/lib/services/epistola-task-context.interceptor.d.ts

@@ -0,0 +1,29 @@
+import { HttpEvent, HttpHandler, HttpInterceptor, HttpRequest } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import { EpistolaTaskContextService } from './epistola-task-context.service';
+import * as i0 from "@angular/core";
+/**
+ * Sniffs Valtimo's task-open signal and pushes the active taskInstanceId into
+ * {@link EpistolaTaskContextService}. The signal is the canonical
+ * {@code GET /api/v2/process-link/task/{taskId}} call that
+ * {@code TaskDetailContentComponent.loadTaskDetails(...)} fires unconditionally
+ * before any task form is rendered (see @valtimo/task internals).
+ *
+ * <p>This interceptor does <b>not</b> modify the outgoing request. It only
+ * captures the taskId from the URL.
+ *
+ * <p>Workaround for Valtimo 13.21 not exposing taskInstanceId through any
+ * injectable service. Remove once upstream adds e.g.
+ * {@code FormIoStateService.setTaskInstanceId(...)}.
+ *
+ * <p>The actual URL-matching logic lives in
+ * {@link extractTaskInstanceIdFromUrl} so it can be unit-tested without an
+ * Angular harness.
+ */
+export declare class EpistolaTaskContextInterceptor implements HttpInterceptor {
+    private readonly taskContext;
+    constructor(taskContext: EpistolaTaskContextService);
+    intercept(request: HttpRequest<unknown>, next: HttpHandler): Observable<HttpEvent<unknown>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaTaskContextInterceptor, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<EpistolaTaskContextInterceptor>;
+}

package/lib/services/epistola-task-context.matcher.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pure helpers for {@link EpistolaTaskContextInterceptor}, extracted so they
+ * can be unit-tested without pulling in {@code @angular/core} (which ts-jest
+ * cannot transform without {@code jest-preset-angular}).
+ */
+/**
+ * Pattern Valtimo uses for the canonical task-open call:
+ * {@code GET /api/v2/process-link/task/{taskInstanceId}}.
+ *
+ * Captures the {@code taskInstanceId} (UUID v4-style 36-character hyphenated
+ * hex string). Anchored at the end of the URL or at a query-string delimiter
+ * so we don't accidentally match a longer trailing segment.
+ */
+export declare const TASK_PROCESS_LINK_PATTERN: RegExp;
+/**
+ * Returns the captured {@code taskInstanceId} from a Valtimo task-open
+ * request URL, or {@code null} if the request does not match.
+ */
+export declare function extractTaskInstanceIdFromUrl(method: string, url: string): string | null;

package/lib/services/epistola-task-context.service.d.ts

@@ -0,0 +1,26 @@
+import { Observable } from 'rxjs';
+import * as i0 from "@angular/core";
+/**
+ * Holds the currently-open Operaton user task instance id so that custom
+ * Formio components rendered inside a Valtimo task form (preview, download,
+ * retry-form) can include it in backend requests for PBAC.
+ *
+ * Populated by {@link EpistolaTaskContextInterceptor}, which sniffs Valtimo's
+ * canonical "load process link for task" GET (`/api/v2/process-link/task/{taskId}`)
+ * — the request always fires when a task opens, before the form renders.
+ *
+ * <p><b>Why this exists:</b> Valtimo 13.21 does not expose the active task
+ * instance id through any service that custom Formio components can inject
+ * (`FormIoStateService` carries documentId and processInstanceId only;
+ * `TaskDetailContentComponent.taskInstanceId$` is private to that component
+ * and Formio elements live in their own injector tree). This service is a
+ * workaround until upstream exposes `taskInstanceId` via `FormIoStateService`.
+ */
+export declare class EpistolaTaskContextService {
+    private readonly _taskInstanceId$;
+    readonly taskInstanceId$: Observable<string | null>;
+    get taskInstanceId(): string | null;
+    setTaskInstanceId(id: string | null): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaTaskContextService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<EpistolaTaskContextService>;
+}

package/lib/services/index.d.ts

@@ -1,3 +1,5 @@
 export * from './epistola-admin.service';
 export * from './epistola-menu.service';
 export * from './epistola-plugin.service';
+export * from './epistola-task-context.service';
+export * from './epistola-task-context.interceptor';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epistola.app/valtimo-plugin",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Epistola document generation plugin for Valtimo",
   "license": "EUPL-1.2",
   "repository": {