nucleus-core-ts 0.10.55 → 0.10.57

package/dist/.build-ok

@@ -1 +1 @@
-0.10.55
+0.10.57

package/dist/fe/components/VerificationFlowPage/components/PendingTab.d.ts

@@ -1,12 +1,14 @@
 import type { ReactElement } from 'react';
 import type { VerificationFlowLabels } from '../labels';
-import type { VerificationDecideAction, VerificationPendingAction } from '../types';
+import type { VerificationDecideAction, VerificationPendingAction, VerificationSignatureUploadAction } from '../types';
 interface PendingTabProps {
     pendingAction: VerificationPendingAction;
     decideAction: VerificationDecideAction;
+    /** Omit it and a signature-required step says so instead of failing on Approve. */
+    uploadSignatureAction?: VerificationSignatureUploadAction;
     onDecisionMade?: (entityName: string, entityId: string) => void;
     /** Spread over the English defaults; omit it and the tab stays English. */
     labels?: Partial<VerificationFlowLabels>;
 }
-export declare function PendingTab({ pendingAction, decideAction, onDecisionMade, labels, }: PendingTabProps): ReactElement;
+export declare function PendingTab({ pendingAction, decideAction, uploadSignatureAction, onDecisionMade, labels, }: PendingTabProps): ReactElement;
 export {};

package/dist/fe/components/VerificationFlowPage/components/PendingTab.js

@@ -1,10 +1,15 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useEffectEvent } from 'react';
+import { useEffect, useEffectEvent, useState } from 'react';
 import { DEFAULT_VERIFICATION_FLOW_LABELS } from '../labels';
 import { useVerificationFlowStore } from '../store';
+import { planDecision, signatureFileType } from './decisionPlan';
 import { getActiveTheme } from '../theme/store';
-export function PendingTab({ pendingAction, decideAction, onDecisionMade, labels }) {
+export function PendingTab({ pendingAction, decideAction, uploadSignatureAction, onDecisionMade, labels }) {
+    // Local, not in the store: only one card is in deciding mode at a time, and
+    // a chosen file must not survive cancelling out of that card.
+    const [signatureFile, setSignatureFile] = useState(null);
+    const [signatureNote, setSignatureNote] = useState(null);
     const theme = getActiveTheme();
     const say = {
         ...DEFAULT_VERIFICATION_FLOW_LABELS,
@@ -38,22 +43,81 @@ export function PendingTab({ pendingAction, decideAction, onDecisionMade, labels
     useEffect(()=>{
         loadPending();
     }, []);
-    const handleDecide = useEffectEvent((item, decision)=>{
+    const sendDecision = useEffectEvent((item, decision, signatureId)=>{
         decideAction.start({
             payload: {
                 entity_name: item.entity_name,
                 entity_id: item.entity_id,
                 decision,
-                reason: store.decisionReason || undefined
+                reason: store.decisionReason || undefined,
+                ...signatureId ? {
+                    signature_id: signatureId
+                } : {}
             },
             onAfterHandle: ()=>{
                 store.setDecidingId(null);
                 store.setDecisionReason('');
+                setSignatureFile(null);
+                setSignatureNote(null);
                 onDecisionMade?.(item.entity_name, item.entity_id);
                 loadPending();
             }
         });
     });
+    /*
+   * A step can demand a signature, and until this existed nothing on this
+   * screen could provide one. The flow builder offers the checkbox, the node
+   * shows a "✍ Signature" badge, and Approve posted without a signature_id --
+   * so the engine answered "Signature is required for this verification step"
+   * and the step could not be completed through the product at all.
+   *
+   * The engine requires a real file OWNED BY the verifier, so the file is
+   * uploaded as the signed-in user and only its id is sent. A rejection needs
+   * no signature: you do not sign what you are refusing.
+   */ const handleDecide = useEffectEvent((item, decision)=>{
+        setSignatureNote(null);
+        const plan = planDecision({
+            decision,
+            requireSignature: item.require_signature,
+            hasUploadAction: Boolean(uploadSignatureAction),
+            hasFile: Boolean(signatureFile)
+        });
+        if (plan.kind === 'send') {
+            sendDecision(item, decision);
+            return;
+        }
+        if (plan.kind === 'blocked') {
+            setSignatureNote(plan.reason === 'no-upload-action' ? say.signatureUnavailable : say.signatureMissing);
+            return;
+        }
+        if (!uploadSignatureAction || !signatureFile) return;
+        const form = new FormData();
+        form.append('files', signatureFile);
+        form.append('data', JSON.stringify({
+            name: signatureFile.name,
+            original_name: signatureFile.name,
+            path: 'uploads/files',
+            size: signatureFile.size,
+            mime_type: signatureFile.type || 'application/octet-stream',
+            extension: signatureFile.name.split('.').pop() || '',
+            type: signatureFileType(signatureFile.type)
+        }));
+        setSignatureNote(say.signatureUploading);
+        uploadSignatureAction.start({
+            payload: form,
+            onAfterHandle: (res)=>{
+                const id = res?.data?.id;
+                if (!id) {
+                    // Reported, never swallowed: a decision that silently did not happen
+                    // is worse than one that failed loudly.
+                    setSignatureNote(say.signatureUploadFailed);
+                    return;
+                }
+                sendDecision(item, decision, id);
+            },
+            onErrorHandle: ()=>setSignatureNote(say.signatureUploadFailed)
+        });
+    });
     if (store.isLoadingPending) {
         return /*#__PURE__*/ _jsx("div", {
             className: "flex items-center justify-center py-20",
@@ -121,6 +185,26 @@ export function PendingTab({ pendingAction, decideAction, onDecisionMade, labels
                             store.decidingId === item.instance_id ? /*#__PURE__*/ _jsxs("div", {
                                 className: theme.pending.card.actions,
                                 children: [
+                                    item.require_signature ? /*#__PURE__*/ _jsxs("label", {
+                                        className: "flex flex-col gap-1 text-xs",
+                                        children: [
+                                            /*#__PURE__*/ _jsx("span", {
+                                                children: say.signaturePrompt
+                                            }),
+                                            /*#__PURE__*/ _jsx("input", {
+                                                type: "file",
+                                                onChange: (e)=>{
+                                                    setSignatureFile(e.target.files?.[0] ?? null);
+                                                    setSignatureNote(null);
+                                                },
+                                                className: theme.pending.input
+                                            }),
+                                            signatureNote ? /*#__PURE__*/ _jsx("span", {
+                                                className: "text-red-600",
+                                                children: signatureNote
+                                            }) : null
+                                        ]
+                                    }) : null,
                                     /*#__PURE__*/ _jsx("input", {
                                         type: "text",
                                         placeholder: say.reasonPlaceholder,
@@ -145,6 +229,8 @@ export function PendingTab({ pendingAction, decideAction, onDecisionMade, labels
                                         onClick: ()=>{
                                             store.setDecidingId(null);
                                             store.setDecisionReason('');
+                                            setSignatureFile(null);
+                                            setSignatureNote(null);
                                         },
                                         className: theme.pending.cancelButton,
                                         children: say.cancel

package/dist/fe/components/VerificationFlowPage/components/VerificationFlowPage.d.ts

@@ -1,4 +1,4 @@
 import '@xyflow/react/dist/style.css';
 import type { ReactElement } from 'react';
 import type { VerificationFlowPageProps } from '../types';
-export declare function VerificationFlowPage({ entityName, title, subtitle, flowListAction, flowGetAction, flowSaveAction, flowPublishAction, flowDeleteAction, pendingAction, decideAction, listUsersAction, listRolesAction, entityStatusesAction, onFlowSelected, onDecisionMade, onEntityClick, onBack, showPending, showEntityStatuses, className, themeMode, labels, }: VerificationFlowPageProps): ReactElement;
+export declare function VerificationFlowPage({ entityName, title, subtitle, flowListAction, flowGetAction, flowSaveAction, flowPublishAction, flowDeleteAction, pendingAction, decideAction, uploadSignatureAction, listUsersAction, listRolesAction, entityStatusesAction, onFlowSelected, onDecisionMade, onEntityClick, onBack, showPending, showEntityStatuses, className, themeMode, labels, }: VerificationFlowPageProps): ReactElement;

package/dist/fe/components/VerificationFlowPage/components/VerificationFlowPage.js

@@ -280,7 +280,7 @@ function buildSavePayload(flowId, entityName, flowName, flowDescription, trigger
     };
 }
 // ─── Main Component ───────────────────────────────────────────────
-export function VerificationFlowPage({ entityName, title, subtitle, flowListAction, flowGetAction, flowSaveAction, flowPublishAction, flowDeleteAction, pendingAction, decideAction, listUsersAction, listRolesAction, entityStatusesAction, onFlowSelected, onDecisionMade, onEntityClick, onBack, showPending = true, showEntityStatuses = false, className, themeMode = 'dark', labels }) {
+export function VerificationFlowPage({ entityName, title, subtitle, flowListAction, flowGetAction, flowSaveAction, flowPublishAction, flowDeleteAction, pendingAction, decideAction, uploadSignatureAction, listUsersAction, listRolesAction, entityStatusesAction, onFlowSelected, onDecisionMade, onEntityClick, onBack, showPending = true, showEntityStatuses = false, className, themeMode = 'dark', labels }) {
     const theme = getVerificationFlowTheme(themeMode);
     setActiveTheme(theme);
     const say = {
@@ -1205,6 +1205,7 @@ export function VerificationFlowPage({ entityName, title, subtitle, flowListActi
                 children: /*#__PURE__*/ _jsx(PendingTab, {
                     pendingAction: pendingAction,
                     decideAction: decideAction,
+                    uploadSignatureAction: uploadSignatureAction,
                     onDecisionMade: onDecisionMade,
                     labels: say
                 })

package/dist/fe/components/VerificationFlowPage/components/decisionPlan.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What pressing Approve or Reject on a pending card should actually do.
+ *
+ * Pulled out as a plain function because the interesting cases are the ones
+ * that must NOT send a decision, and those are the easiest to get wrong from
+ * inside a component: a step that demands a signature with no file chosen, and
+ * a screen the host wired no upload action into. Before this existed, both of
+ * them posted the decision anyway and the engine answered "Signature is
+ * required for this verification step" — a step nobody could complete through
+ * the product, with the checkbox that caused it sitting in the flow builder.
+ *
+ * Rejection never needs a signature: you do not sign what you are refusing.
+ */
+export type DecisionPlan = {
+    kind: 'send';
+} | {
+    kind: 'upload-then-send';
+} | {
+    kind: 'blocked';
+    reason: 'no-upload-action' | 'no-file';
+};
+export declare function planDecision(input: {
+    decision: 'approved' | 'rejected';
+    requireSignature: boolean;
+    hasUploadAction: boolean;
+    hasFile: boolean;
+}): DecisionPlan;
+/**
+ * Which `files.type` a signature upload should declare.
+ *
+ * The column is an enum the HOST configures, and a generic component cannot
+ * invent a value for it. The first version of this sent `type: 'signature'`
+ * and the install answered, from its own list: "type must be one of: image,
+ * document, video, audio, profile_picture" — a 400 the reviewer saw only as
+ * "the signature could not be uploaded".
+ *
+ * So it is derived from the file itself and lands on one of the names every
+ * install carries. `document` is the fallback because a signature that is not
+ * an image is a signed document, and because it is the safest of the five to
+ * be wrong about.
+ */
+export declare function signatureFileType(mimeType: string | undefined): string;

package/dist/fe/components/VerificationFlowPage/components/decisionPlan.js

@@ -0,0 +1,51 @@
+/**
+ * What pressing Approve or Reject on a pending card should actually do.
+ *
+ * Pulled out as a plain function because the interesting cases are the ones
+ * that must NOT send a decision, and those are the easiest to get wrong from
+ * inside a component: a step that demands a signature with no file chosen, and
+ * a screen the host wired no upload action into. Before this existed, both of
+ * them posted the decision anyway and the engine answered "Signature is
+ * required for this verification step" — a step nobody could complete through
+ * the product, with the checkbox that caused it sitting in the flow builder.
+ *
+ * Rejection never needs a signature: you do not sign what you are refusing.
+ */ export function planDecision(input) {
+    if (input.decision === 'rejected') return {
+        kind: 'send'
+    };
+    if (!input.requireSignature) return {
+        kind: 'send'
+    };
+    if (!input.hasUploadAction) return {
+        kind: 'blocked',
+        reason: 'no-upload-action'
+    };
+    if (!input.hasFile) return {
+        kind: 'blocked',
+        reason: 'no-file'
+    };
+    return {
+        kind: 'upload-then-send'
+    };
+}
+/**
+ * Which `files.type` a signature upload should declare.
+ *
+ * The column is an enum the HOST configures, and a generic component cannot
+ * invent a value for it. The first version of this sent `type: 'signature'`
+ * and the install answered, from its own list: "type must be one of: image,
+ * document, video, audio, profile_picture" — a 400 the reviewer saw only as
+ * "the signature could not be uploaded".
+ *
+ * So it is derived from the file itself and lands on one of the names every
+ * install carries. `document` is the fallback because a signature that is not
+ * an image is a signed document, and because it is the safest of the five to
+ * be wrong about.
+ */ export function signatureFileType(mimeType) {
+    const mime = (mimeType || '').toLowerCase();
+    if (mime.startsWith('image/')) return 'image';
+    if (mime.startsWith('video/')) return 'video';
+    if (mime.startsWith('audio/')) return 'audio';
+    return 'document';
+}

package/dist/fe/components/VerificationFlowPage/labels.d.ts

@@ -87,6 +87,16 @@ export type VerificationFlowLabels = {
     noUserAssigned: string;
     /** The badge on a verifier node that demands a signature. */
     signatureBadge: string;
+    /** Prompt above the file picker on a step that demands a signature. */
+    signaturePrompt: string;
+    /** Shown when Approve is pressed on such a step with no file chosen. */
+    signatureMissing: string;
+    /** Shown while the chosen file is being uploaded. */
+    signatureUploading: string;
+    /** Shown when the upload itself fails. */
+    signatureUploadFailed: string;
+    /** Shown when the host wired no upload action at all. */
+    signatureUnavailable: string;
     recipientAllVerifiers: string;
     recipientStepVerifier: string;
     recipientEntityCreator: string;

package/dist/fe/components/VerificationFlowPage/labels.js

@@ -72,6 +72,11 @@
     noRoleAssigned: 'No role',
     noUserAssigned: 'No user',
     signatureBadge: 'Signature',
+    signaturePrompt: 'This step requires a signature. Choose the file you sign with.',
+    signatureMissing: 'Choose a signature file before approving.',
+    signatureUploading: 'Uploading signature…',
+    signatureUploadFailed: 'The signature could not be uploaded. The decision was not sent.',
+    signatureUnavailable: 'This step requires a signature, but signing is not available on this screen. Nobody can complete it here — remove the signature requirement from the step, or wire an upload action.',
     recipientAllVerifiers: 'All Verifiers',
     recipientStepVerifier: 'Step Verifier',
     recipientEntityCreator: 'Entity Creator',

package/dist/fe/components/VerificationFlowPage/types/index.d.ts

@@ -30,6 +30,19 @@ export type VerificationDecideAction = GenericAction<VerificationDecidePayload &
     entity_id: string;
 }, VerificationDecideResponse>;
 export type VerificationPendingAction = GenericAction<undefined, VerificationPendingResponse>;
+/**
+ * Uploads the file a verifier signs with, and hands back its id.
+ *
+ * `FormData` rather than a typed payload because that is what the entity
+ * upload route takes: a `files` part and a `data` part. The host supplies the
+ * action, so the component never learns where files live.
+ */
+export type VerificationSignatureUploadAction = GenericAction<FormData, {
+    success?: boolean;
+    data?: {
+        id?: string;
+    } | null;
+}>;
 export type VerificationStartAction = GenericAction<VerificationStartPayload, VerificationStartResponse>;
 export type VerificationStartForEntityAction = GenericAction<VerificationStartForEntityPayload, VerificationStartResponse>;
 export type VerificationStatusAction = GenericAction<{
@@ -185,6 +198,14 @@ export type VerificationFlowPageProps = {
     flowDeleteAction?: FlowDeleteAction;
     pendingAction: VerificationPendingAction;
     decideAction: VerificationDecideAction;
+    /**
+     * Lets a verifier attach the signature a step demands.
+     *
+     * Optional, and its absence is SAID rather than hidden: without it a step
+     * with `require_signature` cannot be decided at all, so the card explains
+     * that instead of offering an Approve button the engine will refuse.
+     */
+    uploadSignatureAction?: VerificationSignatureUploadAction;
     startAction?: VerificationStartAction;
     startForEntityAction?: VerificationStartForEntityAction;
     statusAction?: VerificationStatusAction;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nucleus-core-ts",
-  "version": "0.10.55",
+  "version": "0.10.57",
   "description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
   "author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
   "license": "SEE LICENSE IN LICENSE",