@epistola.app/valtimo-plugin 0.9.4 → 0.10.0

package/lib/components/download-document-configuration/download-document-config.util.d.ts

@@ -0,0 +1,15 @@
+import { DownloadDocumentConfig } from '../../models';
+/**
+ * Pure helpers for the download-document configurator, extracted so they can be unit-tested
+ * without the Angular component (mirrors the process-link-selector util pattern). See
+ * `docs/adr/0001-download-document-content-storage.md`.
+ */
+export type StorageTarget = 'TEMPORARY_RESOURCE' | 'PROCESS_VARIABLE';
+export declare const DEFAULT_STORAGE_TARGET: StorageTarget;
+/** Normalize a (possibly undefined) storageTarget to a concrete target, applying the default. */
+export declare function resolveStorageTarget(target?: string): StorageTarget;
+/**
+ * A config is valid when the input variable and the output variable that matches the chosen
+ * storage target are both set.
+ */
+export declare function isDownloadDocumentConfigValid(config: Partial<DownloadDocumentConfig> | null | undefined): boolean;

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

@@ -1,6 +1,6 @@
 import { EventEmitter, OnDestroy, OnInit } from '@angular/core';
 import { FunctionConfigurationComponent } from '@valtimo/plugin';
-import { FormOutput } from '@valtimo/components';
+import { FormOutput, SelectItem } from '@valtimo/components';
 import { BehaviorSubject, Observable } from 'rxjs';
 import { DownloadDocumentConfig } from '../../models';
 import * as i0 from "@angular/core";
@@ -22,6 +22,15 @@ export declare class DownloadDocumentConfigurationComponent implements FunctionC
     resolvedPrefill: Partial<DownloadDocumentConfig>;
     readonly prefillResolved$: BehaviorSubject<boolean>;
     safeDisabled$: Observable<boolean>;
+    /**
+     * Static option set for the storage target. Values match the backend
+     * {@code DocumentStorageTarget} enum constants; labels are explained further via the
+     * translated field title/tooltip.
+     */
+    readonly storageTargetOptions: SelectItem[];
+    readonly defaultStorageTarget: import("./download-document-config.util").StorageTarget;
+    /** Drives which output-variable field is shown (resource id vs inline content). */
+    readonly selectedTarget$: BehaviorSubject<string>;
     ngOnInit(): void;
     ngOnDestroy(): void;
     formValueChange(formOutput: FormOutput): 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 { BpmnValidationViolation, ChangelogRelease, ClasspathCatalog, PendingJob, PluginUsageEntry } from '../../models';
+import { BpmnValidationReport, BpmnValidationViolation, ChangelogRelease, ClasspathCatalog, FormCarrierIssue, PendingJob, PluginUsageEntry } from '../../models';
 import * as i0 from "@angular/core";
 /**
  * Combined view model for a single plugin configuration card.
@@ -26,12 +26,12 @@ export declare class EpistolaAdminPageComponent implements OnInit {
     cards: ConfigurationCard[];
     selectedCard: ConfigurationCard | null;
     activeTab: 'actions' | 'pending' | 'catalogs';
-    overviewTab: 'configurations' | 'validations' | 'changelog';
+    overviewTab: 'configurations' | 'validations' | 'changelog' | 'forms';
     loading: boolean;
     pluginVersion: string | null;
     changelog: ChangelogRelease[] | null;
     changelogLoading: boolean;
-    validationViolations: BpmnValidationViolation[];
+    validationReport: BpmnValidationReport | null;
     reconcilingExecutionIds: Set<string>;
     reconcileFeedback: {
         executionId: string;
@@ -46,6 +46,15 @@ export declare class EpistolaAdminPageComponent implements OnInit {
         type: 'success' | 'error';
         message: string;
     } | null;
+    formIssues: FormCarrierIssue[] | null;
+    formIssuesLoading: boolean;
+    repairingFormIds: Set<string>;
+    repairingAll: boolean;
+    formFeedback: {
+        formId: string;
+        type: 'success' | 'error';
+        message: string;
+    } | null;
     private connectionStatuses;
     private usageEntries;
     private pendingJobs;
@@ -54,11 +63,19 @@ export declare class EpistolaAdminPageComponent implements OnInit {
     private pendingLoaded;
     private deepLinkConfigId;
     constructor(adminService: EpistolaAdminService, route: ActivatedRoute, router: Router);
+    /** Violations from the latest report (empty when healthy or not yet loaded). */
+    get validationViolations(): BpmnValidationViolation[];
+    /** Scan cadence in whole minutes, for the "refreshes every N min" note. */
+    get refreshIntervalMinutes(): number;
     ngOnInit(): void;
     selectConfiguration(card: ConfigurationCard): void;
     backToOverview(): void;
     setActiveTab(tab: 'actions' | 'pending' | 'catalogs'): void;
-    setOverviewTab(tab: 'configurations' | 'validations' | 'changelog'): void;
+    setOverviewTab(tab: 'configurations' | 'validations' | 'changelog' | 'forms'): void;
+    private loadFormIssues;
+    isRepairingForm(issue: FormCarrierIssue): boolean;
+    repairForm(issue: FormCarrierIssue): void;
+    repairAllForms(): void;
     private loadChangelog;
     refresh(): void;
     exportProcessLink(entry: PluginUsageEntry): void;

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

@@ -1,7 +1,7 @@
-import { ChangeDetectorRef, EventEmitter, OnDestroy, OnInit } from '@angular/core';
+import { ChangeDetectorRef, EventEmitter, OnChanges, OnDestroy, SimpleChanges } from '@angular/core';
 import { DomSanitizer, SafeResourceUrl } from '@angular/platform-browser';
 import { FormioCustomComponent, FormIoStateService } from '@valtimo/components';
-import { EpistolaPluginService, EpistolaTaskContextService } from '../../services';
+import { EpistolaPluginService } from '../../services';
 import * as i0 from "@angular/core";
 export type EpistolaDocumentDisplay = 'inline' | 'button' | 'both';
 /**
@@ -20,11 +20,10 @@ export type EpistolaDocumentDisplay = 'inline' | 'button' | 'both';
  * <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 {
+export declare class EpistolaDocumentComponent implements FormioCustomComponent<unknown>, OnChanges, OnDestroy {
     private readonly epistolaPluginService;
     private readonly sanitizer;
     private readonly formIoStateService;
-    private readonly taskContext;
     private readonly cdr;
     value: unknown;
     valueChange: EventEmitter<unknown>;
@@ -45,6 +44,11 @@ export declare class EpistolaDocumentComponent implements FormioCustomComponent<
     tenantIdVariable: string;
     /** Filename used for the download disposition. */
     filename: string;
+    /**
+     * Task id forwarded by the Formio wrapper from the server-prefilled form
+     * ({@code epistola:taskId} value resolver), populated in every Valtimo task-open flow.
+     */
+    taskInstanceId?: string | null;
     loading: boolean;
     downloading: boolean;
     error: string | null;
@@ -52,8 +56,8 @@ export declare class EpistolaDocumentComponent implements FormioCustomComponent<
     private currentBlobUrl;
     private subscription?;
     get designMode(): boolean;
-    constructor(epistolaPluginService: EpistolaPluginService, sanitizer: DomSanitizer, formIoStateService: FormIoStateService, taskContext: EpistolaTaskContextService, cdr: ChangeDetectorRef);
-    ngOnInit(): void;
+    constructor(epistolaPluginService: EpistolaPluginService, sanitizer: DomSanitizer, formIoStateService: FormIoStateService, cdr: ChangeDetectorRef);
+    ngOnChanges(changes: SimpleChanges): void;
     ngOnDestroy(): void;
     refresh(): void;
     download(): void;
@@ -61,5 +65,5 @@ export declare class EpistolaDocumentComponent implements FormioCustomComponent<
     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>;
+    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; }; "taskInstanceId": { "alias": "taskInstanceId"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
 }

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

@@ -1,14 +1,13 @@
 import { ChangeDetectorRef, EventEmitter, OnChanges, OnDestroy, SimpleChanges } from '@angular/core';
 import { DomSanitizer, SafeResourceUrl } from '@angular/platform-browser';
 import { FormioCustomComponent, FormIoStateService } from '@valtimo/components';
-import { EpistolaPluginService, EpistolaTaskContextService } from '../../services';
+import { EpistolaPluginService } 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 sanitizer;
     private readonly formIoStateService;
     private readonly cdr;
-    private readonly taskContext;
     value: Record<string, any> | null;
     valueChange: EventEmitter<Record<string, any>>;
     disabled: boolean;
@@ -16,6 +15,11 @@ export declare class EpistolaDocumentPreviewComponent implements FormioCustomCom
     processDefinitionKey?: string;
     sourceActivityId?: string;
     overrideMapping?: Record<string, any>;
+    /**
+     * Task id forwarded by the Formio wrapper from the server-prefilled form
+     * ({@code epistola:taskId} value resolver), populated in every Valtimo task-open flow.
+     */
+    taskInstanceId?: string | null;
     loading: boolean;
     error: string | null;
     previewUrl: SafeResourceUrl | null;
@@ -23,11 +27,11 @@ export declare class EpistolaDocumentPreviewComponent implements FormioCustomCom
     private initialized;
     private currentBlobUrl;
     private previewSubscription?;
-    constructor(epistolaPluginService: EpistolaPluginService, sanitizer: DomSanitizer, formIoStateService: FormIoStateService, cdr: ChangeDetectorRef, taskContext: EpistolaTaskContextService);
+    constructor(epistolaPluginService: EpistolaPluginService, sanitizer: DomSanitizer, formIoStateService: FormIoStateService, cdr: ChangeDetectorRef);
     /**
-     * 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).
+     * The active task id, forwarded by the Formio wrapper from the server-prefilled
+     * form ({@code epistola:taskId} value resolver). Null outside a task context
+     * (e.g. Formio builder), in which case the component fails closed.
      */
     private get currentTaskId();
     get overrideMappingScopes(): string[];
@@ -38,6 +42,14 @@ export declare class EpistolaDocumentPreviewComponent implements FormioCustomCom
     ngOnChanges(changes: SimpleChanges): void;
     ngOnDestroy(): void;
     refresh(): void;
+    /**
+     * Load the preview only when there is enough data for it. Override-driven
+     * previews (those with an override mapping) wait until the mapped form data
+     * has been computed; until then they show a placeholder rather than firing a
+     * request that Epistola would reject with a 400 for missing required fields.
+     */
+    private triggerPreview;
+    private showWaitingForInput;
     /**
      * Preview using the explicitly configured process link + input overrides.
      * Requires a runtime task context — the backend authorizes the request against
@@ -48,5 +60,5 @@ export declare class EpistolaDocumentPreviewComponent implements FormioCustomCom
     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; }; "processDefinitionKey": { "alias": "processDefinitionKey"; "required": false; }; "sourceActivityId": { "alias": "sourceActivityId"; "required": false; }; "overrideMapping": { "alias": "overrideMapping"; "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; }; "taskInstanceId": { "alias": "taskInstanceId"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
 }

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

@@ -10,6 +10,28 @@ export declare function isExpression(value: string): boolean;
  * e.g. { "beslissing.tekst": "value" } -> { beslissing: { tekst: "value" } }
  */
 export declare function expandDotNotation(flat: Record<string, any>): Record<string, any>;
+/**
+ * A preview is "override-driven" when it has a non-empty override mapping: its
+ * input data comes from the form via the mapping, so it must wait for that data
+ * before it can render. Previews without a mapping load straight from the base
+ * doc/case data.
+ */
+export declare function isOverrideDriven(mapping?: OverrideMapping | null): boolean;
+/**
+ * Whether the computed input overrides carry any usable data yet.
+ */
+export declare function hasUsableOverrides(overrides?: Record<string, any> | null): boolean;
+/**
+ * Decide whether a preview request should fire given the configured override
+ * mapping and the currently computed overrides.
+ *
+ * - Override-driven previews only load once the mapped form data is present;
+ *   before that they show a "complete the form" placeholder and fire nothing
+ *   (avoids a doomed request that Epistola rejects with a 400 for missing
+ *   required fields).
+ * - Previews without a mapping always load (base data is the whole input).
+ */
+export declare function shouldLoadPreview(mapping?: OverrideMapping | null, overrides?: Record<string, any> | null): boolean;
 /**
  * Given an override mapping (scope -> { inputPath -> "form:<componentKey>" })
  * and form data, produce the inputOverrides object for the backend.

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

@@ -1,19 +1,22 @@
 import { ChangeDetectorRef, EventEmitter, OnChanges, OnDestroy, SimpleChanges } from '@angular/core';
 import { DomSanitizer, SafeResourceUrl } from '@angular/platform-browser';
-import { FormioCustomComponent, FormIoStateService } from '@valtimo/components';
-import { EpistolaPluginService, EpistolaTaskContextService } from '../../services';
+import { FormioCustomComponent } from '@valtimo/components';
+import { EpistolaPluginService } 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 sanitizer;
-    private readonly taskContext;
     value: string;
     valueChange: EventEmitter<string>;
     disabled: boolean;
     label: string;
     sourceActivityId?: string;
+    /**
+     * Task id forwarded by the Formio wrapper from the server-prefilled form
+     * ({@code epistola:taskId} value resolver), populated in every Valtimo task-open flow.
+     */
+    taskInstanceId?: string | null;
     formDefinition: any;
     submission: any;
     loading: boolean;
@@ -28,9 +31,8 @@ export declare class EpistolaRetryFormComponent implements FormioCustomComponent
     private previewSubject;
     private currentBlobUrl;
     private resolvedSourceActivityId?;
-    private processDefinitionKey?;
     formOptions: any;
-    constructor(epistolaPluginService: EpistolaPluginService, formIoStateService: FormIoStateService, cdr: ChangeDetectorRef, sanitizer: DomSanitizer, taskContext: EpistolaTaskContextService);
+    constructor(epistolaPluginService: EpistolaPluginService, cdr: ChangeDetectorRef, sanitizer: DomSanitizer);
     ngOnChanges(changes: SimpleChanges): void;
     ngOnDestroy(): void;
     togglePreview(): void;
@@ -38,5 +40,5 @@ export declare class EpistolaRetryFormComponent implements FormioCustomComponent
     private loadPreview;
     private loadForm;
     static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaRetryFormComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaRetryFormComponent, "epistola-retry-form-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "sourceActivityId": { "alias": "sourceActivityId"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaRetryFormComponent, "epistola-retry-form-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "sourceActivityId": { "alias": "sourceActivityId"; "required": false; }; "taskInstanceId": { "alias": "taskInstanceId"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
 }

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

@@ -0,0 +1,14 @@
+/**
+ * Hides a registered custom Formio component from the builder's component palette,
+ * while keeping it fully usable inside other components' `editForm`s and at runtime.
+ *
+ * Formio's `WebformBuilder` only adds a component to the palette when
+ * `component.builderInfo && component.builderInfo.schema` is truthy. Overriding the
+ * registered class's static `builderInfo` getter to `false` therefore removes it from
+ * the palette. Runtime instantiation and editForm usage don't consult `builderInfo`,
+ * so they are unaffected.
+ *
+ * Call this AFTER the component is registered (and after any `setComponent` re-registration),
+ * so it targets the final class in `Formio.Components.components[type]`.
+ */
+export declare function hideFormioComponentFromBuilder(type: string): void;

package/lib/models/admin.d.ts

@@ -119,3 +119,41 @@ export interface BpmnValidationViolation {
     code: string;
     message: string;
 }
+/**
+ * The BPMN race-safety validation report from `GET /admin/validations`.
+ * `lastCheckedAt` is an ISO-8601 timestamp of the last completed scan, or `null`
+ * if no scan has run yet. `refreshIntervalMs` is the validator's scan cadence, used
+ * to tell the operator how often the result refreshes. Only the latest deployed
+ * version of each process definition is inspected.
+ */
+export interface BpmnValidationReport {
+    lastCheckedAt: string | null;
+    refreshIntervalMs: number;
+    violations: BpmnValidationViolation[];
+}
+/**
+ * TEMPORARY (removed in 1.0.0). A form whose Epistola components are missing the
+ * task-id carrier field — surfaced on the admin page so it can be repaired.
+ * `readOnly` flags classpath-deployed forms (a repair there is reverted on the next
+ * boot; fix the source instead).
+ */
+export interface FormCarrierIssue {
+    formId: string;
+    name: string;
+    missingComponents: number;
+    readOnly: boolean;
+}
+/** TEMPORARY (removed in 1.0.0). Outcome of repairing one form's carrier. */
+export interface FormCarrierRepairResult {
+    formId: string;
+    name: string | null;
+    success: boolean;
+    componentsPatched: number;
+    errorMessage: string | null;
+}
+/** TEMPORARY (removed in 1.0.0). Aggregate outcome of repairing all flagged forms. */
+export interface FormCarrierRepairSummary {
+    formsRepaired: number;
+    componentsPatched: number;
+    failed: number;
+}

package/lib/models/config.d.ts

@@ -62,7 +62,22 @@ export interface DownloadDocumentConfig {
      * updated by the result collector). The action extracts the document id.
      */
     documentVariable: string;
-    contentVariable: string;
+    /**
+     * Where the downloaded PDF is materialized (see
+     * `docs/adr/0001-download-document-content-storage.md`). Defaults to `TEMPORARY_RESOURCE`. The
+     * output variable used depends on this choice: `resourceIdVariable` or `contentVariable`.
+     */
+    storageTarget?: 'TEMPORARY_RESOURCE' | 'PROCESS_VARIABLE';
+    /**
+     * Output for `TEMPORARY_RESOURCE`: the process variable that receives the temporary resource id
+     * (ready to hand to `documenten-api:store-temp-document`).
+     */
+    resourceIdVariable?: string;
+    /**
+     * Output for `PROCESS_VARIABLE`: the process variable that receives the raw PDF bytes inline
+     * (best for small, non-sensitive documents).
+     */
+    contentVariable?: string;
 }
 export interface VariableSuggestions {
     doc: 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 { BpmnValidationViolation, CatalogRedeployResult, ChangelogRelease, ClasspathCatalog, ConnectionStatus, PendingJob, PluginUsageEntry, ReconcileResult, VersionInfo } from '../models';
+import { BpmnValidationReport, CatalogRedeployResult, ChangelogRelease, ClasspathCatalog, ConnectionStatus, FormCarrierIssue, FormCarrierRepairResult, FormCarrierRepairSummary, PendingJob, PluginUsageEntry, ReconcileResult, VersionInfo } from '../models';
 import * as i0 from "@angular/core";
 /**
  * Service for Epistola plugin administrative operations.
@@ -37,10 +37,11 @@ export declare class EpistolaAdminService {
      */
     reconcilePending(executionId: string): Observable<ReconcileResult>;
     /**
-     * Get the latest BPMN race-safety validation violations across deployed
-     * process definitions. Empty list = healthy.
+     * Get the latest BPMN race-safety validation report across deployed process
+     * definitions: the violations (empty = healthy) plus when it was last checked
+     * and how often it refreshes.
      */
-    getValidationViolations(): Observable<BpmnValidationViolation[]>;
+    getValidationReport(): Observable<BpmnValidationReport>;
     /**
      * List the classpath catalogs available to manually redeploy for a plugin
      * configuration, each annotated with the version last deployed in this
@@ -63,6 +64,12 @@ export declare class EpistolaAdminService {
      * Export a single process link as a .process-link.json file.
      */
     exportProcessLink(processLinkId: string): Observable<Blob>;
+    /** Forms whose Epistola components are missing the task-id carrier. */
+    getFormCarrierIssues(): Observable<FormCarrierIssue[]>;
+    /** Inject the task-id carrier into a single form's Epistola components. */
+    repairFormCarrier(formId: string): Observable<FormCarrierRepairResult>;
+    /** Repair every flagged form. */
+    repairAllFormCarriers(): Observable<FormCarrierRepairSummary>;
     static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaAdminService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<EpistolaAdminService>;
 }

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

@@ -5,18 +5,15 @@ import { AttributeDefinition, CatalogInfo, EnvironmentInfo, ExpressionFunctionIn
 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.
+ * backend {@code PreviewRequest} record. The backend derives the process
+ * instance and case document from the authorized task, so only {@code taskId}
+ * and {@code sourceActivityId} (which identifies the {@code generate-document}
+ * process link) are sent; {@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;
 }
@@ -82,9 +79,12 @@ export declare class EpistolaPluginService {
     /**
      * Get a dynamically generated Formio form for retrying a failed document generation.
      *
+     * The backend derives the process instance and case document from the authorized task,
+     * so only the task id (and optionally the source activity) is sent.
+     *
      * @param taskId Operaton user task id (required — backend authorizes via OperatonTask:VIEW)
      */
-    getRetryForm(taskId: string, processInstanceId: string, documentId?: string, sourceActivityId?: string): Observable<any>;
+    getRetryForm(taskId: string, sourceActivityId?: string): Observable<any>;
     /**
      * List all available expression functions for expr: data mapping values.
      */

package/lib/services/index.d.ts

@@ -1,5 +1,4 @@
 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';
+export * from './prefilled-task-id';

package/lib/services/prefilled-task-id.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Helpers for reading the active user task's id out of a Valtimo task form that was
+ * prefilled server-side by the {@code epistola:} value resolver (see the backend
+ * {@code EpistolaTaskValueResolverFactory}).
+ *
+ * <p>Background: the Epistola Formio components need the id of the user task whose form
+ * they're rendered in, to authorize their backend requests ({@code OperatonTask:VIEW}).
+ * Valtimo exposes no service that carries the task id to a custom Formio component at
+ * runtime, and earlier URL-sniffing only worked in the direct task-open flow (the
+ * task-list / case-detail flow bulk-fetches process links and never fires the per-task
+ * call).
+ *
+ * <p>Form prefill, however, runs server-side in every flow. A form field with
+ * {@code properties.sourceKey = "epistola:taskId"} is filled with the task id at prefill
+ * time (by the backend {@code EpistolaTaskValueResolverFactory}); this helper reads it back
+ * from the Formio root — robustly, regardless of how the task was opened.
+ */
+/** The value-resolver source key that yields the current task id at prefill time. */
+export declare const PREFILLED_TASK_ID_SOURCE_KEY = "epistola:taskId";
+/** Conventional key of the hidden carrier field that holds the prefilled task id. */
+export declare const PREFILLED_TASK_ID_DATA_KEY = "epistolaTaskId";
+/**
+ * Hidden Formio child component that carries the prefilled task id. It is embedded as a
+ * nested component inside each Epistola task component's schema, so dropping that component
+ * brings the carrier with it — the form author never adds a separate field. Valtimo's
+ * server-side prefill fills its {@code defaultValue} from the {@code epistola:taskId}
+ * value resolver; {@link readPrefilledTaskId} reads it back from the form definition.
+ *
+ * {@code persistent: false} keeps the value out of the submission, so the task id never
+ * lands in the case document / process variables.
+ */
+export declare const PREFILLED_TASK_ID_CARRIER: {
+    type: string;
+    key: string;
+    input: boolean;
+    persistent: boolean;
+    label: string;
+    properties: {
+        sourceKey: string;
+    };
+};
+/**
+ * Reads the prefilled task id from a Formio webform/wizard root, or null when absent.
+ *
+ * Looks in two places, in order:
+ *  1. The (prefilled) form definition — any component whose {@code properties.sourceKey}
+ *     is {@code epistola:taskId} carries the task id in its {@code defaultValue}. This works
+ *     even when the carrier is a hidden field that Formio doesn't surface into submission data.
+ *  2. The submission data under {@link PREFILLED_TASK_ID_DATA_KEY}, for a rendered sibling
+ *     hidden field whose value Formio copied into {@code root.data}.
+ */
+export declare function readPrefilledTaskId(root: any): string | null;

package/package.json

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