@signstack/cli 0.1.1

package/dist/libs/signstack/base/src/lib/models/workflow.d.ts

@@ -0,0 +1,917 @@
+import { FieldType, FieldWidgetInfo, Input, TemplateFieldInfo, TemplateRole } from './template';
+import { ActorRef, ListResp, LiteralOrExpression } from './base';
+import { NamespaceMode } from './namespace';
+import type { BlueprintResource, BlueprintSpec } from './blueprint';
+import type { TemplateResource } from './template';
+import type { AssetResource } from './asset';
+import type { JsonataFunctionResource } from './jsonata-function';
+import type { SchemaResource } from './schema';
+import { FunctionDependency } from './jsonata-function';
+export declare enum WorkflowStepType {
+    Group = "group",
+    Participant = "participant"
+}
+export declare enum ParticipantActionType {
+    Sign = "sign"
+}
+export declare enum WorkflowStepStatus {
+    Pending = "pending",
+    InProgress = "in_progress",
+    Completed = "completed",
+    Skipped = "skipped",
+    Failed = "failed"
+}
+export declare enum WorkflowStepExecutionMode {
+    Sequential = "sequential",
+    Parallel = "parallel"
+}
+export declare enum WorkflowStepCompletionRule {
+    All = "all",
+    Any = "any",
+    Quorum = "quorum"
+}
+export declare enum ParticipantActionStatus {
+    Pending = "pending",
+    Notified = "notified",
+    /**
+     * The step is active and awaiting the participant, but SignStack did NOT send
+     * a notification (the workflow has `disableParticipantNotifications`). Same
+     * lifecycle position as `Notified` — the difference is who delivers the link.
+     * The caller is responsible for getting the link to the participant.
+     */
+    Ready = "ready",
+    Viewed = "viewed",
+    Signed = "signed",
+    Declined = "declined"
+}
+export declare enum WorkflowEventType {
+    WorkflowCreated = "workflow_created",
+    WorkflowStarted = "workflow_started",
+    WorkflowCompleted = "workflow_completed",
+    WorkflowFailed = "workflow_failed",
+    WorkflowDeclined = "workflow_declined",
+    WorkflowVoided = "workflow_voided",
+    StepCreated = "step_created",
+    StepSkipped = "step_skipped",
+    StepStarted = "step_started",
+    StepCompleted = "step_completed",
+    StepFailed = "step_failed",
+    StepParticipantNotified = "step_participant_notified",
+    StepParticipantViewed = "step_participant_viewed",
+    StepParticipantSignatureAdopted = "step_participant_signature_adopted",
+    StepParticipantDeclined = "step_participant_declined",
+    StepParticipantSigned = "step_participant_signed",
+    EnvelopeCompleted = "envelope_completed",
+    EnvelopeFailed = "envelope_failed"
+}
+export declare enum ExecutionMode {
+    Prod = "Prod",
+    Test = "Test"
+}
+export interface WorkflowEventInfo {
+    eventType: WorkflowEventType;
+    eventAt: Date;
+    stepKey?: string;
+    details?: Record<string, unknown>;
+}
+export interface GetEntitySnapshotsResp {
+    entitySnapshots: {
+        /** Prefixed lowercase ULID, e.g. `es_01jv8m7qfj6xj9gkz7a4s2h8e`. */
+        id: string;
+        entityKey: string;
+        schemaKey?: string;
+        schemaVersion?: string;
+        /** Prefixed lowercase ULID, e.g. `wf_01jv8m7qfj6xj9gkz7a4s2h8e`. */
+        workflowId: string;
+        data: Record<string, any>;
+        createdAt: Date;
+        updatedAt: Date;
+    }[];
+}
+export interface AddEntitySnapshotsReq {
+    /** Prefixed lowercase ULID, e.g. `wf_01jv8m7qfj6xj9gkz7a4s2h8e`. */
+    workflowId: string;
+    entitySnapshots: {
+        schemaKey?: string;
+        schemaVersion?: string;
+        inlineSchemaDefinition?: Record<string, any>;
+        inlineSchemaDraft?: string;
+        entityKey: string;
+        data: Record<string, any>;
+    }[];
+}
+export interface AddEntitySnapshotsResp {
+    entitySnapshots: {
+        entityKey: string;
+        /** Prefixed lowercase ULID, e.g. `es_01jv8m7qfj6xj9gkz7a4s2h8e`. */
+        entitySnapshotId: string;
+        schemaKey?: string;
+        schemaVersion?: string;
+    }[];
+}
+export interface StepDataUpdate {
+    key: string;
+    transform: string;
+}
+export interface StepOnComplete {
+    validateExpression?: string;
+    updates?: StepDataUpdate[];
+}
+export interface WorkflowStepBase {
+    key: string;
+    type: WorkflowStepType;
+    name?: string;
+    status?: WorkflowStepStatus;
+    includeIf?: string;
+    onComplete?: StepOnComplete;
+    inputEntities?: AddEntitySnapshotsResp['entitySnapshots'];
+    outputEntities?: AddEntitySnapshotsResp['entitySnapshots'];
+    isCompletionClaimed?: boolean;
+}
+export interface WorkflowGroupStep extends WorkflowStepBase {
+    type: WorkflowStepType.Group;
+    executionMode: WorkflowStepExecutionMode;
+    completionRule: WorkflowStepCompletionRule;
+    quorumCount?: number;
+    childStepKeys?: string[];
+    children: WorkflowStep[];
+}
+export interface WorkflowParticipantStep extends WorkflowStepBase {
+    type: WorkflowStepType.Participant;
+    participantKey: string;
+    action?: {
+        type: ParticipantActionType;
+        envelopeKey: string;
+        status: ParticipantActionStatus;
+        signedAt?: Date;
+        initialsImageFileId?: string;
+        signatureImageFileId?: string;
+        signingToken?: string;
+        assignments: DocumentAssignment[];
+    };
+}
+export type WorkflowStep = WorkflowGroupStep | WorkflowParticipantStep;
+export type WorkflowStepInfo = WorkflowStep;
+export interface ParticipantInfo {
+    key: string;
+    name?: string;
+    email?: string;
+}
+export interface DocumentAssignment {
+    documentKey: string;
+    roleKey: string;
+}
+export interface CreateWorkflowStepBaseReq {
+    key: string;
+    name?: string;
+    includeIf?: string;
+    onComplete?: StepOnComplete;
+    inputEntities?: AddEntitySnapshotsResp['entitySnapshots'];
+    outputEntities?: AddEntitySnapshotsResp['entitySnapshots'];
+}
+export interface CreateWorkflowGroupStepReq extends CreateWorkflowStepBaseReq {
+    type: WorkflowStepType.Group;
+    executionMode?: WorkflowStepExecutionMode;
+    completionRule?: WorkflowStepCompletionRule;
+    quorumCount?: number;
+    children?: CreateWorkflowStepReq[];
+}
+export interface CreateWorkflowParticipantStepReq extends CreateWorkflowStepBaseReq {
+    type: WorkflowStepType.Participant;
+    participantKey: string;
+    action?: {
+        type: ParticipantActionType;
+        envelopeKey: string;
+        assignments: DocumentAssignment[];
+    };
+}
+export type CreateWorkflowStepReq = CreateWorkflowGroupStepReq | CreateWorkflowParticipantStepReq;
+export interface SenderInfo {
+    name: string;
+    company: string;
+    email: string;
+    logoUrl: string;
+    senderEmail: string;
+    phone?: string;
+    address?: string;
+}
+export declare enum EnvelopeResolutionMode {
+    Immediate = "immediate",
+    JustInTime = "just_in_time"
+}
+export interface WorkflowEnvelope {
+    key: string;
+    subject: string;
+    documents: {
+        key: string;
+        templateKey?: string;
+        templateVersion?: string;
+        includeIf?: string;
+        fileId?: LiteralOrExpression<string>;
+        iterator?: string;
+        fieldOverrides?: FieldOverrideInfo[];
+        adhocFields?: AdHocFieldInfo[];
+        inputMap?: InputMapEntry[];
+    }[];
+    resolutionMode?: EnvelopeResolutionMode;
+}
+export interface CustomFieldConfig {
+    key: string;
+    name: string;
+    value?: LiteralOrExpression<string | number | boolean | Date>;
+}
+export interface ResolvedCustomField {
+    key: string;
+    value?: string | number | boolean | Date;
+}
+export type SenderInfoOverrides = Omit<SenderInfo, 'senderEmail'>;
+export interface CreateWorkflowReq {
+    name?: string;
+    description?: string;
+    blueprintKey?: string;
+    blueprintVersion?: string;
+    inlineResources?: {
+        blueprint?: BlueprintResource;
+        templates?: TemplateResource[];
+        assets?: AssetResource[];
+        functions?: JsonataFunctionResource[];
+        schemas?: SchemaResource[];
+    };
+    listingKey?: string;
+    listingVersion?: string;
+    data?: Record<string, any>;
+    options?: {
+        inlineOnly?: boolean;
+        disableParticipantNotifications?: boolean;
+        /**
+         * @public-api-shape DO-NOT-DOCUMENT
+         *   Per-participant override is intentionally excluded from `openapi.json`
+         *   and public API references. Until the public surface is finalized, do
+         *   NOT add this field to the spec or user-facing docs. Runtime behavior
+         *   stays — internal callers depend on it.
+         */
+        participantOverrides?: {
+            key: string;
+            name: string;
+            email: string;
+        }[];
+        /**
+         * @public-api-shape DO-NOT-DOCUMENT
+         *   Test-only override that sends every participant's signing email to a
+         *   single address. Excluded from `openapi.json` and public API references
+         *   to prevent accidental production use. Do NOT add this field to the
+         *   spec or user-facing docs. Runtime behavior stays — internal callers
+         *   depend on it.
+         */
+        overrideAllParticipantEmails?: string;
+        senderInfoOverrides?: SenderInfoOverrides;
+        mode?: CreateWorkflowMode;
+    };
+}
+export declare enum CreateWorkflowMode {
+    Run = "Run",
+    Review = "Review"
+}
+export interface FieldOverrideInfo {
+    fieldKey: string;
+    overriddenValue?: string | number | boolean | Date;
+    overriddenIsHidden?: boolean;
+    overriddenWidgets?: FieldWidgetInfo[];
+}
+export interface UpdateWorkflowReq {
+    name?: string;
+    description?: string;
+    envelopes?: WorkflowEnvelope[];
+    participants?: ParticipantInfo[];
+    rootStep?: CreateWorkflowStepReq;
+}
+export type UpdateWorkflowResp = GetWorkflowInfoResp;
+export type CreateWorkflowResp = GetWorkflowInfoResp;
+export interface UpdateWorkflowEntitiesReq {
+    /**
+     * Entity payload, keyed by the blueprint's input keys. Same shape as
+     * `CreateWorkflowReq.data`. Schema for each entity is derived from the
+     * blueprint's input declarations — callers don't supply `schemaKey`.
+     * Must include every entity key the workflow declares.
+     */
+    data: Record<string, any>;
+}
+export type UpdateWorkflowEntitiesResp = GetWorkflowInfoResp;
+export declare enum SignatureType {
+    Signature = "Signature",
+    Initials = "Initials"
+}
+export declare enum SignatureMethod {
+    Typed = "typed",
+    Drawn = "drawn"
+}
+/**
+ * Supported hash algorithm identifiers for tamper-evidence.
+ * Stored alongside all hashes for future algorithm migration support.
+ */
+export declare const HASH_ALGORITHM: {
+    readonly SHA256: "SHA-256";
+};
+export interface SignatureImageInfo {
+    fileId: string;
+    fileHash: string;
+    hashAlgorithm: string;
+    method: SignatureMethod;
+    adoptedAt?: Date;
+}
+export interface FinishParticipantTaskReq {
+    fieldUpdates: {
+        documentKey: string;
+        fields: {
+            key: string;
+            value: string | number | boolean | Date;
+        }[];
+    }[];
+}
+export interface FinishParticipantTaskResp {
+}
+export interface UploadWorkflowSignatureReq {
+    signatureImage?: {
+        fileId: string;
+        fileHash: string;
+        hashAlgorithm: string;
+        method: SignatureMethod;
+    };
+    initialsImage?: {
+        fileId: string;
+        fileHash: string;
+        hashAlgorithm: string;
+        method: SignatureMethod;
+    };
+}
+export interface UploadWorkflowSignatureResp {
+}
+export interface GetWorkflowStepInfoReq {
+    /** Prefixed lowercase ULID, e.g. `wf_01jv8m7qfj6xj9gkz7a4s2h8e`. */
+    workflowId: string;
+    signingToken: string;
+}
+export type GetWorkflowStepInfoResp = WorkflowStep & {
+    senderInfo?: SenderInfo;
+    subject?: string;
+    participant?: ParticipantInfo;
+};
+/**
+ * Consumer consent disclosure information for ESIGN Act compliance.
+ * Captures the specific version and hash of the disclosure text shown to the participant.
+ */
+export interface ConsentDisclosureInfo {
+    /** Version identifier for the consent disclosure (e.g., "1.0.0") */
+    version: string;
+    /** SHA-256 hash of the full disclosure text for tamper-evidence */
+    textHash: string;
+    /** Algorithm used for hashing (e.g., "SHA-256") */
+    hashAlgorithm: string;
+}
+/**
+ * Standard ESIGN consent disclosure configuration.
+ * Increment version when the text changes.
+ */
+export declare const CONSENT_DISCLOSURE: {
+    readonly VERSION: "1.0.0";
+    readonly TEXT: "I acknowledge that I have reviewed the terms and agree to use electronic records and signatures for this transaction.\n\nELECTRONIC SIGNATURE DISCLOSURES:\n\nScope of Consent: Your consent applies to this transaction only.\n\nWithdrawing Consent: You may withdraw your consent at any time by declining to sign and contacting the sender.\n\nUpdating Your Information: To update your contact information, please contact the sender directly.\n\nSystem Requirements: To access and retain electronic records, you need: a device with internet access, a current web browser with JavaScript and cookies enabled, and the ability to view PDF documents.\n\nPaper Copies: You may request a paper copy of any document signed electronically by contacting the sender. The sender may charge a reasonable fee for the preparation and mailing of paper copies.";
+};
+export interface UpdateStepParticipantTaskStatusReq {
+    status: ParticipantActionStatus;
+    /** Consent disclosure info when transitioning to Viewed status (ESIGN compliance) */
+    consentDisclosure?: ConsentDisclosureInfo;
+}
+export interface UpdateStepParticipantTaskStatusResp {
+}
+export interface WorkflowCancellationReq {
+    reason: string;
+}
+export interface WorkflowCancellationResp {
+    success: boolean;
+}
+export interface GetWorkflowSignatureReq extends GetWorkflowStepInfoReq {
+}
+export interface GetWorkflowSignatureResp {
+    signatureImageFileId?: string;
+    initialsImageFileId?: string;
+}
+export interface DocumentInfo {
+    filePath: string;
+    fileExtension: string;
+    name: string;
+    id: string;
+    sequence: number;
+    templateFields?: TemplateFieldInfo[];
+    fieldOverrides?: FieldOverrideInfo[];
+    adhocFields?: AdHocFieldInfo[];
+    roles?: TemplateRole[];
+}
+export declare enum WorkflowStatus {
+    Pending = "pending",
+    InProgress = "in_progress",
+    Completed = "completed",
+    Failed = "failed",
+    Declined = "declined",
+    Voided = "voided"
+}
+export declare enum WorkflowSourceType {
+    /** Workflow was instantiated from a stored, named blueprint in this namespace. */
+    Blueprint = "blueprint",
+    /** Workflow was instantiated from a marketplace listing published by another org. */
+    Listing = "listing",
+    /** Workflow was created from inline resources — caller supplied the blueprint blob directly (CLI preview, ad-hoc flows). The blueprint is not a stored resource and its key/version may not be resolvable. */
+    Inline = "inline"
+}
+export declare enum EnvelopeStatus {
+    Pending = "pending",
+    InProgress = "in_progress",
+    Completed = "completed",
+    Voided = "voided",
+    Failed = "failed"
+}
+export interface AddDocumentToWorkflowReq {
+    envelopeKey: string;
+    templateKey?: string;
+    templateVersion?: string;
+    fileId?: string;
+    inputMap?: InputMapEntry[];
+}
+export interface AddDocumentToWorkflowResp {
+    addedDoc: {
+        templateKey?: string;
+        templateVersion?: string;
+        key: string;
+        fileId: string;
+        fileName: string;
+        templateFields: TemplateFieldInfo[];
+        fieldOverrides: FieldOverrideInfo[];
+        adhocFields: AdHocFieldInfo[];
+        inputMap?: InputMapEntry[];
+    };
+}
+export interface RenderWorkflowResp {
+    documents: {
+        /**
+         * Pre-signed download URL for the rendered PDF. The render output is
+         * ephemeral — bytes live in tmp/ and are regenerated on each /render
+         * call — so it's served inline rather than via a fileId handle.
+         */
+        signedUrl: string;
+        fileName: string;
+        templateKey: string;
+        key: string;
+        signerOverlayFields: RenderSignerFieldInfo[];
+    }[];
+    participants: ParticipantInfo[];
+    rootStep: WorkflowStep;
+}
+export interface RenderSignerFieldInfo {
+    key: string;
+    type: FieldType;
+    widgets: FieldWidgetInfo[];
+    assignment: {
+        assignedToStepKey: string;
+    };
+    value?: string;
+}
+export interface WorkflowEnvelopeInfo {
+    key: string;
+    status: EnvelopeStatus;
+    resolvedDocuments: ResolvedWorkflowDocumentInfo[];
+    signedDocumentFileId?: string;
+    certificateFileId?: string;
+}
+/**
+ * Internal-only variant of `WorkflowEnvelopeInfo` that carries fields stripped
+ * from the public `GET /workflows/{id}` response: the Mongo `envelopeId`,
+ * the pre-sign `initialCombinedDocumentFileId` (used by the BE document
+ * download flow as a fallback before a signed PDF exists), and the rich
+ * per-document shape. Public consumers target envelopes by `key` and only
+ * see the final signed PDF + certificate.
+ */
+export interface WorkflowEnvelopeInfoInternal extends Omit<WorkflowEnvelopeInfo, 'resolvedDocuments'> {
+    envelopeId: string;
+    initialCombinedDocumentFileId?: string;
+    resolvedDocuments: ResolvedWorkflowDocumentInfoInternal[];
+}
+export interface StepRunInfo {
+    key: string;
+    status: WorkflowStepStatus;
+    resolvedCustomFields?: ResolvedCustomField[];
+    participantAction?: {
+        status: ParticipantActionStatus;
+        signedAt?: Date;
+    };
+}
+/**
+ * Internal-only variant of `StepRunInfo` that carries per-step entity
+ * snapshot references and the signing-flow internals (signingToken, raw
+ * signature/initials image file IDs, and the per-participant signed PDF
+ * pointer used by the BE document-download flow). Used inside
+ * `GetWorkflowInternalResp` for in-process BE callers (renderer, expression
+ * evaluator, signing controller). Public consumers fetch entity data via the
+ * dedicated `GET /workflows/{id}/entities` endpoint; signing tokens,
+ * signature artifacts, and per-participant signed PDFs are never exposed on
+ * the public response (the envelope-level `signedDocumentFileId` is the
+ * public final-PDF signal).
+ */
+export interface StepRunInfoInternal extends Omit<StepRunInfo, 'participantAction'> {
+    participantAction?: StepRunInfo['participantAction'] & {
+        signingToken?: string;
+        signatureImageFileId?: string;
+        initialsImageFileId?: string;
+        signedDocumentFileId?: string;
+    };
+    inputEntities?: AddEntitySnapshotsResp['entitySnapshots'];
+    outputEntities?: AddEntitySnapshotsResp['entitySnapshots'];
+}
+export interface GetWorkflowInfoResp {
+    /** Prefixed lowercase ULID, e.g. `wf_01jv8m7qfj6xj9gkz7a4s2h8e`. */
+    id: string;
+    mode: NamespaceMode;
+    name?: string;
+    description?: string;
+    source: WorkflowSourceInfo;
+    idempotencyKey?: string;
+    /**
+     * @public-api-shape DO-NOT-DOCUMENT
+     *   The blueprint structure is intentionally excluded from `openapi.json`
+     *   and public API references. It's redundant with `source.blueprint.{key,version}` —
+     *   public consumers should fetch the source blueprint directly via
+     *   `GET /blueprints/{key}?version={version}` (or the equivalent listing
+     *   endpoint for listing-sourced workflows). Inline-workflow consumers
+     *   already have the blueprint they supplied at create time. Runtime
+     *   behavior stays — Studio and internal callers depend on this field.
+     *
+     *   Note: `inlineResources` (full template / asset / function / schema bodies)
+     *   is excluded from this public shape because it is heavy and may contain
+     *   sensitive data. Internal callers that need inline resources receive them
+     *   via `GetWorkflowInternalResp` (defined below).
+     */
+    blueprint: {
+        metadata?: {
+            key: string;
+            version: string;
+        };
+        spec: BlueprintSpec;
+    };
+    participants: ParticipantInfo[];
+    status: WorkflowStatus;
+    /**
+     * Lightweight summary of the entities supplied at workflow create time —
+     * matches the shape used in `WorkflowListItem.entities`. Only carries
+     * identity + schema reference, not the entity values themselves; for the
+     * full entity payload (including step-transitioned snapshots), call the
+     * dedicated `GET /workflows/{id}/entities` endpoint.
+     */
+    inputEntities?: {
+        entityKey: string;
+        schemaKey?: string;
+        schemaVersion?: string;
+    }[];
+    envelopes: WorkflowEnvelopeInfo[];
+    stepRuns: StepRunInfo[];
+    senderInfo: SenderInfo;
+    completedAt?: Date;
+    voidedAt?: Date;
+    voidReason?: string;
+    declinedAt?: Date;
+    declineReason?: string;
+}
+/**
+ * Internal-only variant of `GetWorkflowInfoResp` for in-process BE callers
+ * (renderer, resource resolver, conversion service, expression evaluator).
+ * Carries the heavy / sensitive fields that are stripped from the public
+ * response: blueprint inline resources, top-level entity snapshots, the
+ * append-only event log, per-step input/output entity references, and the
+ * `updatedAt` timestamp the controller reads to set the response `ETag`
+ * header (public consumers get the ETag in the header — the timestamp on
+ * the body is redundant noise).
+ *
+ * The public `GET /workflows/{id}` controller strips this back down to
+ * `GetWorkflowInfoResp` at the response boundary. Public consumers that need
+ * entity data fetch it via `GET /workflows/{id}/entities`; event history via
+ * `GET /workflows/{id}/events`.
+ */
+export interface GetWorkflowInternalResp extends Omit<GetWorkflowInfoResp, 'blueprint' | 'stepRuns' | 'envelopes'> {
+    blueprint: GetWorkflowInfoResp['blueprint'] & {
+        inlineResources?: {
+            templates?: TemplateResource[];
+            assets?: AssetResource[];
+            functions?: JsonataFunctionResource[];
+            schemas?: SchemaResource[];
+        };
+    };
+    stepRuns: StepRunInfoInternal[];
+    envelopes: WorkflowEnvelopeInfoInternal[];
+    entitySnapshots: GetEntitySnapshotsResp['entitySnapshots'];
+    eventLog?: WorkflowEventInfo[];
+    updatedAt?: Date;
+}
+/**
+ * Response shape for `GET /workflows/{id}/entities` — an internal-only
+ * (DO-NOT-DOCUMENT) endpoint that returns the workflow's entity data.
+ *
+ * `entitySnapshots` carries the full snapshot rows (id, schema, data, ...).
+ * `stepEntities` carries per-step references into `entitySnapshots` by ID;
+ * only includes steps that have at least one of `inputEntities` /
+ * `outputEntities` populated.
+ */
+export interface GetWorkflowEntitiesResp {
+    entitySnapshots: GetEntitySnapshotsResp['entitySnapshots'];
+    stepEntities: {
+        stepKey: string;
+        inputEntities?: AddEntitySnapshotsResp['entitySnapshots'];
+        outputEntities?: AddEntitySnapshotsResp['entitySnapshots'];
+    }[];
+}
+/**
+ * Response shape for `GET /workflows/{id}/templates` — an internal-only
+ * (DO-NOT-DOCUMENT) endpoint that returns the resolved template-derived
+ * data per document slot in the workflow. Pairs with the lean public
+ * `GET /workflows/{id}` to give Studio (and any caller) the template echo
+ * (templateKey, templateFields, inputs, roles, name, fileName, fileId)
+ * without making them chain N template fetches by hand.
+ *
+ * Flat array keyed by `documentKey`. The parent `envelopeKey` is omitted —
+ * consumers join against the workflow Get's `envelopes[].resolvedDocuments[].key`
+ * when they need to associate documents back to envelopes.
+ */
+export interface GetWorkflowTemplatesResp {
+    templates: {
+        documentKey: string;
+        templateKey?: string;
+        templateVersion?: string;
+        name?: string;
+        fileName?: string;
+        fileId?: string;
+        templateFields?: TemplateFieldInfo[];
+        inputs?: Input[];
+        roles?: TemplateRole[];
+    }[];
+}
+/**
+ * Query parameters for `GET /workflows/{id}/events`. All optional. `since`
+ * filters events to those that occurred after a given timestamp — pair with
+ * the most recent `eventAt` you've already processed to incrementally
+ * consume new events without re-fetching history.
+ */
+export interface ListWorkflowEventsReq {
+    offset?: number;
+    limit?: number;
+    since?: Date;
+}
+/**
+ * Response shape for `GET /workflows/{id}/events`. Pairs with webhooks: the
+ * push channel for real-time delivery, this endpoint for the persistent
+ * historical record. Returns the workflow's append-only event log
+ * (created, started, step transitions, participant actions, completed /
+ * failed / voided / declined) ordered by `eventAt` descending — newest first.
+ */
+export type GetWorkflowEventsResp = ListResp<WorkflowEventInfo>;
+export interface GetWorkflowStatusResp {
+    status: WorkflowStatus;
+}
+/**
+ * One participant's action URL plus their current status. The URL embeds a
+ * token that is the sole credential required to complete the action (e.g.
+ * sign) — anyone holding it can act on this participant's behalf. Returned
+ * only from the dedicated, privileged `GET /workflows/{id}/action-urls`
+ * endpoint (scope `workflow:action-urls`), never from the default workflow
+ * read responses.
+ */
+export interface ParticipantActionUrlInfo {
+    participantKey: string;
+    name?: string;
+    email?: string;
+    /** The participant step this URL is for. */
+    stepKey: string;
+    /** What the participant does at this step (e.g. `sign`; more types later). */
+    actionType: ParticipantActionType;
+    /**
+     * Lifecycle state. With notifications disabled, `ready` means the step is
+     * active and SignStack did not email the participant — send the link now.
+     * `pending` = not their turn yet; `viewed`/`signed`/`declined` = already
+     * engaged/done. (With notifications enabled, an active step is `notified`.)
+     */
+    status: ParticipantActionStatus;
+    /**
+     * Token-bearing link to the participant's task surface. Bearer-style: holding
+     * it grants the ability to complete the action on the participant's behalf.
+     */
+    url: string;
+}
+export interface GetParticipantActionUrlsResp {
+    actionUrls: ParticipantActionUrlInfo[];
+}
+export interface ListWorkflowsReq {
+    status?: WorkflowStatus;
+    limit?: number;
+    offset?: number;
+    search?: string;
+    labels?: Record<string, string>;
+}
+export type WorkflowSourceInfo = {
+    type: WorkflowSourceType.Blueprint;
+    blueprint: {
+        key: string;
+        version: string;
+        name?: string;
+    };
+} | {
+    type: WorkflowSourceType.Listing;
+    listing: {
+        key: string;
+        version: string;
+        name?: string;
+    };
+} | {
+    type: WorkflowSourceType.Inline;
+};
+export interface WorkflowListItem {
+    /** Prefixed lowercase ULID, e.g. `wf_01jv8m7qfj6xj9gkz7a4s2h8e`. */
+    id: string;
+    name?: string;
+    description?: string;
+    status: WorkflowStatus;
+    source: WorkflowSourceInfo;
+    idempotencyKey?: string;
+    createdBy: ActorRef;
+    createdAt: Date;
+    completedAt?: Date;
+    voidedAt?: Date;
+    voidReason?: string;
+    declinedAt?: Date;
+    declineReason?: string;
+    /**
+     * Lightweight summary of the entities supplied at workflow create time.
+     * Carries identity + schema reference only — entity values are not
+     * included. For the full entity payload (including step-transitioned
+     * snapshots), call `GET /workflows/{id}/entities` on the individual
+     * workflow.
+     */
+    inputEntities?: {
+        entityKey: string;
+        schemaKey?: string;
+        schemaVersion?: string;
+    }[];
+    participants?: ParticipantInfo[];
+    envelopes?: {
+        key: string;
+        status: EnvelopeStatus;
+    }[];
+    progress?: {
+        totalSteps: number;
+        completedSteps: number;
+    };
+}
+export type ListWorkflowsResp = ListResp<WorkflowListItem>;
+export interface WorkflowDocInfoForStep {
+    documentKey: string;
+    docName: string;
+    roleKey: string;
+    name?: string;
+}
+export interface AdHocFieldInfo {
+    key: string;
+    type: FieldType;
+    value?: string | number | boolean | Date;
+    widgets: FieldWidgetInfo[];
+    isHidden?: boolean;
+    assignment?: {
+        assignedToStepKey: string;
+    };
+}
+export interface WorkflowDocumentInfo {
+    templateKey?: string;
+    templateVersion?: string;
+    key: string;
+    envelopeKey: string;
+    templateFields: TemplateFieldInfo[];
+    fieldOverrides: FieldOverrideInfo[];
+    adhocFields: AdHocFieldInfo[];
+    inputMap: InputMapEntry[];
+    inputs?: Input[];
+    roles?: TemplateRole[];
+    functions?: FunctionDependency[];
+    templateFileId?: string;
+    fileId?: LiteralOrExpression<string>;
+    fileName?: string;
+    name?: string;
+    includeIf?: string;
+    iterator?: string;
+}
+/**
+ * Public shape returned for each entry in `envelopes[].resolvedDocuments[]`
+ * on `GET /workflows/{id}`. Carries only workflow-runtime state per
+ * document — the slot key plus the caller-supplied / Review-editable
+ * payload (adhocFields, fieldOverrides, inputMap).
+ *
+ * Template-derived data (templateKey/Version, templateFields, inputs, roles,
+ * name, fileName, fileId) lives on the dedicated
+ * `GET /workflows/{id}/templates` endpoint — see `GetWorkflowTemplatesResp`.
+ * The `envelopeKey` back-ref is omitted since the document is already nested
+ * under its parent envelope; consumers that flatten the array synthesize it
+ * locally from the parent's `key`.
+ */
+export interface ResolvedWorkflowDocumentInfo {
+    key: string;
+    adhocFields: AdHocFieldInfo[];
+    fieldOverrides: FieldOverrideInfo[];
+    inputMap: InputMapEntry[];
+}
+/**
+ * Internal-only variant of `ResolvedWorkflowDocumentInfo` for in-process BE
+ * callers (renderer, signing flow, conversion service). Carries the heavy
+ * template echo + source-PDF pointer + back-ref fields stripped from the
+ * public shape.
+ */
+export interface ResolvedWorkflowDocumentInfoInternal extends ResolvedWorkflowDocumentInfo {
+    envelopeKey: string;
+    templateKey?: string;
+    templateVersion?: string;
+    templateFields?: TemplateFieldInfo[];
+    inputs?: Input[];
+    roles?: TemplateRole[];
+    functions?: FunctionDependency[];
+    templateFileId?: string;
+    fileId?: string;
+    fileName?: string;
+    name?: string;
+    includeIf?: string;
+    iterator?: string;
+}
+export interface InputMapEntry {
+    templateInputKey: string;
+    blueprintInputKey: string;
+}
+export interface SignerInfo {
+    name?: string;
+    email?: string;
+    signerId?: string;
+    signerRoleKey?: string;
+    stepKey: string;
+    routingOrder: number;
+}
+export interface AnnotatorSignerInfo {
+    id: string;
+    name?: string;
+    roleKey?: string;
+    stepKey?: string;
+}
+export declare enum WorkflowActorType {
+    Sender = "sender",
+    ParticipantTask = "participant_task"
+}
+export interface GetStepEntityDataReq {
+    /** Prefixed lowercase ULID, e.g. `wf_01jv8m7qfj6xj9gkz7a4s2h8e`. */
+    workflowId: string;
+    stepKey: string;
+}
+export interface GetStepEntityDataResp {
+    inputEntities: StepEntityData[];
+    outputEntities: StepEntityData[];
+}
+export interface StepEntityData {
+    entityKey: string;
+    name: string;
+    entityType: string;
+    version: string;
+    data: Record<string, any>;
+}
+export interface WorkflowNodeFormValue {
+    key: string;
+    type: WorkflowStepType;
+    name?: string;
+    status?: WorkflowStepStatus;
+    executionMode?: WorkflowStepExecutionMode;
+    completionRule?: WorkflowStepCompletionRule;
+    quorumCount?: number;
+    includeIf?: string;
+    onComplete?: StepOnComplete;
+    participantKey?: string;
+    action?: {
+        type: ParticipantActionType;
+        status: ParticipantActionStatus;
+        envelopeKey: string;
+        assignments: DocumentAssignment[];
+    } | null;
+}
+export interface EmbedSigningContextResp {
+    signingToken: string;
+    workflow: {
+        /** Prefixed lowercase ULID, e.g. `wf_01jv8m7qfj6xj9gkz7a4s2h8e`. */
+        id: string;
+        name: string;
+    };
+    step: {
+        key: string;
+        label: string;
+        status: ParticipantActionStatus;
+    };
+    participant?: {
+        key: string;
+        name: string;
+        email: string;
+    };
+}