@rytass/bpm-core-client 0.5.0 → 0.6.0

package/src/lib/workflow/workflow-api.d.ts

@@ -0,0 +1,517 @@
+import { FormDefinitionSchema, FormFieldValue, FormUiSchema } from '@rytass/bpm-core-shared/form';
+import { WorkflowDefinition } from '@rytass/bpm-core-shared/workflow';
+export type ApprovalInstanceState = 'APPROVED' | 'CANCELLED' | 'DRAFT' | 'EXPIRED' | 'REJECTED' | 'RETURNED' | 'RUNNING';
+export type TaskStatus = 'CANCELLED' | 'COMPLETED' | 'IN_PROGRESS' | 'PENDING' | 'TRANSFERRED';
+export type TaskAssignmentType = 'CANDIDATE_GROUP' | 'DIRECT_MEMBER';
+export type TaskDecisionAction = 'APPROVED' | 'REJECTED' | 'RETURNED' | 'TRANSFERRED';
+export type AdhocDirectiveType = 'COMPLETION_NOTIFY' | 'COUNTERSIGN' | 'PRE_APPROVAL' | 'STAGE_NOTIFY';
+export type AdhocDirectiveStatus = 'CANCELLED' | 'CONSUMED' | 'PENDING';
+export type AdhocTargetKind = 'MEMBER' | 'ORG_UNIT_MEMBER' | 'POSITION' | 'WEBHOOK';
+export type AdhocPreApprovalRejectBehavior = 'REJECT_INSTANCE' | 'RETURN_TO_ORIGIN';
+/**
+ * Polymorphic target of an ad-hoc directive. Set exactly the fields matching
+ * `kind`:
+ *
+ * - `MEMBER` → `memberIds`
+ * - `POSITION` → `positionId`
+ * - `ORG_UNIT_MEMBER` → `orgUnitId` (+ optional `includeDescendants`)
+ * - `WEBHOOK` → `webhookUrl` (+ optional `webhookHeaders`); only valid for
+ *   the notification directives, never as countersign / pre-approval signers.
+ */
+export interface AdhocTargetOptions {
+    readonly includeDescendants?: boolean;
+    readonly kind: AdhocTargetKind;
+    readonly memberIds?: readonly string[];
+    readonly orgUnitId?: string;
+    readonly positionId?: string;
+    readonly webhookHeaders?: Readonly<Record<string, string>>;
+    readonly webhookUrl?: string;
+}
+/**
+ * An instance-scoped ad-hoc directive recorded by a stage approver. Directives
+ * never modify the workflow template — they only affect the single approval
+ * instance they were created on. `status` lifecycle: `PENDING` (waiting for
+ * its trigger) → `CONSUMED` (effect applied / notification sent) or
+ * `CANCELLED` (withdrawn, or dropped by a return / reject / cancel).
+ */
+export interface AdhocDirectiveRecord {
+    readonly channels: readonly NotificationChannel[] | null;
+    readonly comment: string | null;
+    readonly consumedAt: string | null;
+    readonly createdAt: string;
+    readonly createdByMemberId: string;
+    readonly id: string;
+    readonly instanceId: string;
+    readonly onReject: AdhocPreApprovalRejectBehavior | null;
+    readonly originNodeId: string;
+    readonly originTaskId: string;
+    readonly status: AdhocDirectiveStatus;
+    readonly targetKind: AdhocTargetKind;
+    readonly targetValueJson: string;
+    readonly type: AdhocDirectiveType;
+}
+export interface ApprovalInstanceRecord {
+    readonly completedAt: string | null;
+    readonly formData: WorkflowFormData;
+    readonly formDataJson: string;
+    readonly formDefinitionSnapshot: FormDefinitionSnapshot;
+    readonly formDefinitionSnapshotJson: string;
+    readonly id: string;
+    readonly initiatorMemberId: string;
+    readonly startedAt: string;
+    readonly state: ApprovalInstanceState;
+    readonly templateId: string;
+    readonly templateVersionId: string;
+    readonly title: string;
+    readonly workflowSnapshot: WorkflowDefinition;
+    readonly workflowSnapshotJson: string;
+}
+export interface FormDefinitionSnapshot {
+    readonly formDefinitionVersionId?: string;
+    readonly schema?: FormDefinitionSchema;
+    readonly uiSchema?: FormUiSchema;
+    readonly version?: number;
+}
+export type WorkflowFormData = Readonly<Record<string, FormFieldValue | undefined>>;
+export interface TaskRecord {
+    readonly adhocDirectiveId: string | null;
+    readonly adhocOriginTaskId: string | null;
+    readonly adhocType: AdhocDirectiveType | null;
+    readonly assigneeMemberId: string | null;
+    readonly assignmentType: TaskAssignmentType;
+    readonly candidateMemberIds: readonly string[];
+    readonly completedAt: string | null;
+    readonly createdAt: string;
+    readonly decisionPolicySnapshotJson: string;
+    readonly delegationChainJson: string;
+    readonly id: string;
+    readonly instanceId: string;
+    readonly isAdhoc: boolean;
+    readonly nodeId: string;
+    readonly openedAt: string | null;
+    readonly originalAssigneeMemberId: string | null;
+    readonly slaDueAt: string | null;
+    readonly status: TaskStatus;
+    readonly tokenId: string;
+}
+export interface TaskCandidateRecord {
+    readonly claimedAt: string | null;
+    readonly createdAt: string;
+    readonly decidedAt: string | null;
+    readonly delegationChainJson: string;
+    readonly id: string;
+    readonly memberId: string;
+    readonly originalMemberId: string;
+    readonly sourceType: string;
+    readonly status: string;
+    readonly taskId: string;
+}
+export interface WorkflowTokenRecord {
+    readonly consumedAt: string | null;
+    readonly createdAt: string;
+    readonly currentNodeId: string;
+    readonly id: string;
+    readonly instanceId: string;
+    readonly parentTokenId: string | null;
+    readonly status: 'ACTIVE' | 'CONSUMED' | 'WAITING';
+}
+export interface TaskDecisionRecord {
+    readonly action: TaskDecisionAction;
+    readonly comment: string | null;
+    readonly decidedAt: string;
+    readonly decidedByMemberId: string;
+    readonly id: string;
+    readonly returnToNodeId: string | null;
+    readonly signatureId: string | null;
+    readonly taskId: string;
+    readonly transferToMemberId: string | null;
+}
+export interface ActivityLogRecord {
+    readonly actorMemberId: string | null;
+    readonly createdAt: string;
+    readonly eventType: string;
+    readonly id: string;
+    readonly nodeId: string | null;
+    readonly payloadJson: string;
+    readonly taskId: string | null;
+}
+export interface MemberProfileRecord {
+    readonly email: string;
+    readonly memberId: string;
+    readonly name: string;
+}
+export interface MemberDirectoryPage {
+    readonly members: readonly MemberProfileRecord[];
+    readonly totalCount: number;
+}
+export type DelegationScopeType = 'ALL' | 'CONDITION_BASED' | 'TEMPLATE_LIST';
+export type DelegationRuleStatus = 'ACTIVE' | 'EXPIRED' | 'REVOKED';
+export type NotificationChannel = 'EMAIL' | 'IN_APP' | 'WEBHOOK';
+export type NotificationDigestMode = 'DAILY' | 'INSTANT';
+export type NotificationStatus = 'FAILED' | 'PENDING' | 'READ' | 'SENT';
+export type NotificationType = 'INSTANCE_COMPLETED' | 'SLA_OVERDUE' | 'SLA_WARNING' | 'TASK_ASSIGNED' | 'TASK_TRANSFERRED';
+export type NotificationResolution = 'APPROVED' | 'REJECTED' | 'RETURNED' | 'SUPERSEDED' | 'TRANSFERRED';
+export interface NotificationRecord {
+    /**
+     * Whether the recipient can still act on this notification (an unresolved
+     * task assignment). Server-derived; drives the inline 同意/拒絕 actions.
+     */
+    readonly actionable: boolean;
+    readonly attemptCount: number;
+    readonly body: string;
+    readonly channel: NotificationChannel;
+    readonly createdAt: string;
+    readonly deliveredAt: string | null;
+    readonly deliveryError: string | null;
+    readonly deliveryTarget: string | null;
+    readonly id: string;
+    readonly instanceId: string | null;
+    readonly lastAttemptAt: string | null;
+    readonly nextRetryAt: string | null;
+    readonly payloadJson: string;
+    readonly readAt: string | null;
+    readonly recipientMemberId: string;
+    /** How an actionable notification was resolved; `null` while still open. */
+    readonly resolution: NotificationResolution | null;
+    readonly resolvedAt: string | null;
+    readonly sentAt: string | null;
+    readonly status: NotificationStatus;
+    readonly taskId: string | null;
+    readonly title: string;
+    readonly type: NotificationType;
+}
+export interface NotificationPreferenceRecord {
+    readonly emailDigestMode: NotificationDigestMode;
+    readonly emailEnabled: boolean;
+    readonly inAppEnabled: boolean;
+    readonly memberId: string;
+    readonly quietHoursEnd: string | null;
+    readonly quietHoursStart: string | null;
+    readonly updatedAt: string;
+}
+export interface DelegationRuleRecord {
+    readonly agentMemberId: string;
+    readonly createdAt: string;
+    readonly createdByMemberId: string | null;
+    readonly endAt: string | null;
+    readonly id: string;
+    readonly principalMemberId: string;
+    readonly priority: number;
+    readonly requiresConfirmation: boolean;
+    readonly revokedAt: string | null;
+    readonly revokedByMemberId: string | null;
+    readonly scopeConditionCel: string | null;
+    readonly scopeTemplateIds: readonly string[];
+    readonly scopeType: DelegationScopeType;
+    readonly startAt: string;
+    readonly status: DelegationRuleStatus;
+    readonly updatedAt: string;
+}
+export interface AttachmentRecord {
+    readonly checksumSha256: string;
+    readonly createdAt: string;
+    readonly filename: string;
+    readonly formFieldPath: string | null;
+    readonly id: string;
+    readonly instanceId: string | null;
+    readonly mimeType: string;
+    readonly sizeBytes: string;
+    readonly storageKey: string;
+    readonly storageProvider: string;
+    readonly taskId: string | null;
+    readonly uploaderMemberId: string;
+}
+export interface SignatureRecord {
+    readonly algorithm: string;
+    readonly id: string;
+    readonly instanceId: string;
+    readonly keyVersion: number;
+    readonly previousSignatureHash: string | null;
+    readonly signature: string;
+    readonly signedAt: string;
+    readonly signedPayloadHash: string;
+    readonly signedPayloadJson: string;
+    readonly signerMemberId: string;
+    readonly taskId: string | null;
+    readonly timestampTokenBase64: string | null;
+}
+export interface SignatureVerificationRecord {
+    readonly checkedCount: number;
+    readonly errors: readonly string[];
+    readonly instanceId: string;
+    readonly valid: boolean;
+}
+export interface ApprovalTemplateRecord {
+    readonly currentVersionId: string | null;
+    readonly id: string;
+    readonly name: string;
+    readonly updatedAt?: string;
+}
+export interface ApprovalTemplateVersionRecord {
+    readonly formDefinitionVersionId: string | null;
+    readonly id: string;
+    readonly status: 'ARCHIVED' | 'DRAFT' | 'PUBLISHED';
+    readonly version: number;
+}
+export interface LaunchContext {
+    readonly formVersion: {
+        readonly id: string;
+        readonly schema: FormDefinitionSchema;
+        readonly uiSchema: FormUiSchema;
+        readonly version: number;
+    };
+    readonly template: ApprovalTemplateRecord;
+    readonly templateVersion: ApprovalTemplateVersionRecord;
+}
+export interface LaunchableTemplateRecord {
+    readonly currentVersionId: string;
+    readonly formDefinitionVersionId: string;
+    readonly id: string;
+    readonly name: string;
+    readonly updatedAt: string;
+    readonly version: number;
+}
+export type ApprovalInstanceView = 'ALL' | 'CC' | 'SENT';
+export interface ApprovalInstancesPageInput {
+    readonly page: number;
+    readonly pageSize: number;
+    readonly searchText: string | null;
+    readonly state: ApprovalInstanceState | null;
+    readonly templateId: string | null;
+    readonly view: ApprovalInstanceView;
+}
+export interface ApprovalInstancesPageResult {
+    readonly instances: readonly ApprovalInstanceRecord[];
+    readonly pageInfo: ApprovalInstancePageInfoRecord;
+    readonly totalCount: number;
+}
+export interface ApprovalInstancePageInfoRecord {
+    readonly hasNextPage: boolean;
+    readonly hasPreviousPage: boolean;
+    readonly page: number;
+    readonly pageSize: number;
+    readonly totalCount: number;
+    readonly totalPages: number;
+}
+export interface WorkflowDashboardSummaryRecord {
+    readonly activeInstanceCount: number;
+    readonly completedInstanceCount: number;
+    readonly overdueTaskCount: number;
+    readonly pendingTaskCount: number;
+    readonly rejectedInstanceCount: number;
+    readonly totalInstanceCount: number;
+    readonly unreadNotificationCount: number;
+}
+export declare function listApprovalInstances(): Promise<readonly ApprovalInstanceRecord[]>;
+export declare function listApprovalInstancesPage({ page, pageSize, searchText, state, templateId, view, }: ApprovalInstancesPageInput): Promise<ApprovalInstancesPageResult>;
+export declare function readLaunchContext(templateId: string): Promise<LaunchContext>;
+export declare function listLaunchableTemplates(): Promise<readonly LaunchableTemplateRecord[]>;
+export declare function readApprovalInstance(instanceId: string): Promise<{
+    readonly activityLogs: readonly ActivityLogRecord[];
+    readonly instance: ApprovalInstanceRecord;
+    readonly tasks: readonly TaskRecord[];
+    readonly workflowTokens: readonly WorkflowTokenRecord[];
+}>;
+export declare function listInboxTasks(assigneeMemberId: string): Promise<readonly TaskRecord[]>;
+export declare function listApprovalHistoryTasks(assigneeMemberId: string): Promise<readonly TaskRecord[]>;
+export declare function readWorkflowDashboardSummary({ currentMemberId, from, to, }: {
+    readonly currentMemberId: string;
+    readonly from: string | null;
+    readonly to: string | null;
+}): Promise<WorkflowDashboardSummaryRecord>;
+export declare function listTaskDecisions(taskId: string): Promise<readonly TaskDecisionRecord[]>;
+export declare function listAttachments(instanceId: string): Promise<readonly AttachmentRecord[]>;
+export declare function uploadAttachment({ file, formFieldPath, }: {
+    readonly file: File;
+    readonly formFieldPath: string;
+}): Promise<AttachmentRecord>;
+export declare function readAttachmentDownloadUrl({ id, }: {
+    readonly id: string;
+}): Promise<string>;
+export declare function readAttachmentPreviewUrl({ id, }: {
+    readonly id: string;
+}): Promise<string>;
+export declare function readInstanceSignatures(instanceId: string): Promise<{
+    readonly signatures: readonly SignatureRecord[];
+    readonly verification: SignatureVerificationRecord;
+}>;
+export declare function resolveMemberProfiles(memberIds: readonly string[]): Promise<readonly MemberProfileRecord[]>;
+export declare function searchMembers(searchText: string): Promise<readonly MemberProfileRecord[]>;
+export declare function listMemberDirectoryPage({ page, pageSize, searchText, }: {
+    readonly page: number;
+    readonly pageSize: number;
+    readonly searchText?: string;
+}): Promise<MemberDirectoryPage>;
+export declare function listDelegationRules({ includeInactive, principalMemberId, }?: {
+    readonly includeInactive?: boolean;
+    readonly principalMemberId?: string | null;
+}): Promise<readonly DelegationRuleRecord[]>;
+export declare function listDelegationRulesPage({ agentMemberId, includeInactive, page, pageSize, principalMemberId, scopeType, status, }?: {
+    readonly agentMemberId?: string | null;
+    readonly includeInactive?: boolean;
+    readonly page?: number;
+    readonly pageSize?: number;
+    readonly principalMemberId?: string | null;
+    readonly scopeType?: DelegationScopeType | null;
+    readonly status?: DelegationRuleStatus | null;
+}): Promise<{
+    readonly rules: readonly DelegationRuleRecord[];
+    readonly totalCount: number;
+}>;
+export declare function createDelegationRule(input: {
+    readonly agentMemberId: string;
+    readonly createdByMemberId: string | null;
+    readonly endAt: string | null;
+    readonly principalMemberId: string;
+    readonly priority: number;
+    readonly requiresConfirmation: boolean;
+    readonly scopeConditionCel: string | null;
+    readonly scopeTemplateIds: readonly string[];
+    readonly scopeType: DelegationScopeType;
+    readonly startAt: string | null;
+}): Promise<DelegationRuleRecord>;
+export declare function revokeDelegationRule({ id, revokedByMemberId, }: {
+    readonly id: string;
+    readonly revokedByMemberId: string | null;
+}): Promise<DelegationRuleRecord>;
+export declare function listNotifications({ includeRead, page, pageSize, recipientMemberId, }: {
+    readonly includeRead?: boolean;
+    readonly page?: number;
+    readonly pageSize?: number;
+    readonly recipientMemberId: string;
+}): Promise<{
+    readonly notifications: readonly NotificationRecord[];
+    readonly totalCount: number;
+    readonly unreadCount: number;
+}>;
+export declare function readUnreadNotificationCount(recipientMemberId: string): Promise<number>;
+export declare function markNotificationRead({ id, readerMemberId, }: {
+    readonly id: string;
+    readonly readerMemberId: string;
+}): Promise<Pick<NotificationRecord, 'id' | 'readAt' | 'status'>>;
+export declare function markAllNotificationsRead({ recipientMemberId, }: {
+    readonly recipientMemberId: string;
+}): Promise<number>;
+export declare function readNotificationPreference(memberId: string): Promise<NotificationPreferenceRecord>;
+export declare function updateNotificationPreference(input: {
+    readonly emailDigestMode: NotificationDigestMode;
+    readonly emailEnabled: boolean;
+    readonly inAppEnabled: boolean;
+    readonly memberId: string;
+    readonly quietHoursEnd: string | null;
+    readonly quietHoursStart: string | null;
+}): Promise<NotificationPreferenceRecord>;
+export declare function submitApprovalInstance({ formData, initiatorMemberId, templateId, title, }: {
+    readonly formData: Readonly<Record<string, unknown>>;
+    readonly initiatorMemberId: string;
+    readonly templateId: string;
+    readonly title: string | null;
+}): Promise<string>;
+export declare function decideTask({ action, comment, decidedByMemberId, returnToNodeId, taskId, transferToMemberId, }: {
+    readonly action: TaskDecisionAction;
+    readonly comment: string | null;
+    readonly decidedByMemberId: string;
+    readonly returnToNodeId?: string | null;
+    readonly taskId: string;
+    readonly transferToMemberId?: string | null;
+}): Promise<TaskDecisionRecord>;
+export declare function cancelApprovalInstance({ cancelledByMemberId, comment, instanceId, }: {
+    readonly cancelledByMemberId: string;
+    readonly comment: string | null;
+    readonly instanceId: string;
+}): Promise<void>;
+export declare function resubmitApprovalInstance({ formData, initiatorMemberId, instanceId, title, }: {
+    readonly formData: Readonly<Record<string, unknown>>;
+    readonly initiatorMemberId: string;
+    readonly instanceId: string;
+    readonly title: string | null;
+}): Promise<void>;
+/**
+ * Ad-hoc countersign (臨時會簽): asks the given target to co-sign the NEXT
+ * stage of this instance. When the next user task is created, a parallel
+ * ad-hoc task is spawned for the target, and the flow only advances past
+ * that stage once BOTH the original task and every countersign task are
+ * approved. A countersigner's rejection rejects the whole instance.
+ *
+ * Only the current task's assignee/candidate may call this, and only on
+ * nodes whose template sets `allowAddSigner: true`. Returns the recorded
+ * directive (`PENDING` until the next user task consumes it; withdrawable
+ * via {@link cancelAdhocDirective} while pending). Never alters the
+ * workflow template.
+ */
+export declare function requestAdhocCountersign({ comment, target, taskId, }: {
+    readonly comment?: string | null;
+    readonly target: AdhocTargetOptions;
+    readonly taskId: string;
+}): Promise<AdhocDirectiveRecord>;
+/**
+ * Ad-hoc pre-approval (臨時加簽): immediately spawns a blocking ad-hoc task
+ * for the given target on the CURRENT stage. Even after the original
+ * approver approves, the flow stays on this stage until the pre-approver
+ * also approves. `onReject` decides what happens when the pre-approver
+ * rejects: `REJECT_INSTANCE` rejects the whole instance;
+ * `RETURN_TO_ORIGIN` hands the decision back to the original approver
+ * (re-opening their task if they had already approved).
+ *
+ * Only the current task's assignee/candidate may call this, and only on
+ * nodes whose template sets `allowAddSigner: true`. Returns the spawned
+ * ad-hoc task. Never alters the workflow template.
+ */
+export declare function requestAdhocPreApproval({ comment, onReject, target, taskId, }: {
+    readonly comment?: string | null;
+    readonly onReject: AdhocPreApprovalRejectBehavior;
+    readonly target: AdhocTargetOptions;
+    readonly taskId: string;
+}): Promise<TaskRecord>;
+/**
+ * Ad-hoc stage notification (臨時階段通知): notifies the target once the
+ * CURRENT stage ends — regardless of outcome (approved, rejected, or
+ * returned). Targets may be members, a position, an org unit, or a webhook
+ * URL. `channels` defaults to in-app notification.
+ *
+ * Available to the current task's assignee/candidate on any user-task node
+ * (no `allowAddSigner` requirement). Returns the recorded directive
+ * (withdrawable via {@link cancelAdhocDirective} while pending). Never
+ * alters the workflow template.
+ */
+export declare function configureAdhocStageNotification({ channels, target, taskId, }: {
+    readonly channels?: readonly NotificationChannel[] | null;
+    readonly target: AdhocTargetOptions;
+    readonly taskId: string;
+}): Promise<AdhocDirectiveRecord>;
+/**
+ * Ad-hoc completion notification (臨時完成通知): notifies the target once
+ * the WHOLE instance reaches a terminal state (`APPROVED`, `REJECTED`, or
+ * `CANCELLED`). Targets may be members, a position, an org unit, or a
+ * webhook URL. `channels` defaults to in-app notification.
+ *
+ * Available to the current task's assignee/candidate on any user-task node
+ * (no `allowAddSigner` requirement). Returns the recorded directive
+ * (withdrawable via {@link cancelAdhocDirective} while pending). Never
+ * alters the workflow template.
+ */
+export declare function configureAdhocCompletionNotification({ channels, target, taskId, }: {
+    readonly channels?: readonly NotificationChannel[] | null;
+    readonly target: AdhocTargetOptions;
+    readonly taskId: string;
+}): Promise<AdhocDirectiveRecord>;
+/**
+ * Withdraws a still-`PENDING` ad-hoc directive (countersign / stage-notify /
+ * completion-notify) before it takes effect. Only the directive's creator
+ * may withdraw it; pre-approval directives are consumed immediately on
+ * creation and therefore cannot be withdrawn.
+ */
+export declare function cancelAdhocDirective(directiveId: string): Promise<AdhocDirectiveRecord>;
+/**
+ * Lists every ad-hoc directive recorded on one approval instance, ordered by
+ * creation time. Use the `status` field to find directives that are still
+ * pending (withdrawable) versus already consumed or cancelled.
+ */
+export declare function listAdhocDirectives(instanceId: string): Promise<readonly AdhocDirectiveRecord[]>;
+export declare function readApprovalInstanceCaseTitle(instance: ApprovalInstanceRecord): string;
+export declare function readFormDataCaseTitle({ fallbackTitle, formData, schema, uiSchema, }: {
+    readonly fallbackTitle: string;
+    readonly formData: WorkflowFormData;
+    readonly schema: FormDefinitionSchema | null;
+    readonly uiSchema: FormUiSchema | null;
+}): string;