npm package: @splpi/dms-estore-upload
Description: St. Peter DMS — eStore V2 Upload Requirements Component
Latest version: 1.0.1

# @splpi/dms-estore-upload

A React upload dialog component for integrating with the St. Peter Group Document Management System (DMS). Used in eStorev2 to collect and upload customer documents (Government ID, Specimen Signatures) to the DMS API.

---

## Installation

```bash
npm install @splpi/dms-estore-upload
```

### Peer Dependencies

Make sure these are already installed in your project:

```bash
npm install react react-dom @chakra-ui/react react-icons
```

---

## Usage

```tsx
import { DmsUploadRequirements } from '@splpi/dms-estore-upload';
import { useRef } from 'react';

export default function YourPage() {
  const uploadRef = useRef(null);

  return (
    <DmsUploadRequirements
      apiBase="http://192.168.23.126:5129"
      uploadedBy="customer@email.com"
      PrimaryMdButton={PrimaryMdButton}
      onChange={(file) => {
        // Fires immediately when user selects a Government ID file.
        // Use this to call your OCR API and pre-fill form fields.
        console.log('ID file selected:', file);
      }}
      onBeforeNext={(uploadFn) => {
        // Registers the upload function with the parent.
        // Call uploadRef.current() on your Next button click.
        uploadRef.current = uploadFn;
      }}
      onIdUploadComplete={(result) => {
        // Fires after the Government ID is uploaded to DMS.
        console.log(result.driveFileId, result.fileName);
      }}
      onSignatureUploadComplete={(result) => {
        // Fires after each specimen signature is uploaded to DMS.
        console.log(result.driveFileId, result.fileName);
      }}
    />
  );
}
```

### Wiring up the Next button

The component does **not** upload immediately on file select. Upload is triggered by calling the function registered via `onBeforeNext` — typically on your Next button click.

```tsx
const uploadRef = useRef(null);

// Pass to DmsUploadRequirements:
onBeforeNext={(uploadFn) => { uploadRef.current = uploadFn; }}

// Then on your Next button:
<NextButton
  onClick={async () => {
    if (uploadRef.current) {
      const result = await uploadRef.current();
      if (!result.success) return; // stop if upload failed
    }
    // proceed to next step
    setUploadDialogOpen(false);
    setNextDialogOpen(true);
  }}
/>
```

---

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `apiBase` | `string` | ✅ | Base URL of the DMS API (e.g. `http://192.168.23.126:5129`) |
| `uploadedBy` | `string` | ✅ | Customer identifier — usually their email address |
| `PrimaryMdButton` | `React.ComponentType` | ✅ | Themed button component from `st-peter-ui` used for the camera button |
| `onChange` | `(file: File) => void` | ❌ | Fires immediately when user selects a Government ID file, before Next is clicked |
| `onBeforeNext` | `(uploadFn: () => Promise<{ success: boolean }>) => void` | ❌ | Registers the upload trigger function with the parent component |
| `onIdUploadComplete` | `(result: UploadResult) => void` | ❌ | Fires after the Government ID is successfully uploaded to DMS |
| `onSignatureUploadComplete` | `(result: UploadResult) => void` | ❌ | Fires after each specimen signature is successfully uploaded to DMS |

### UploadResult

```ts
{
  driveFileId: string;
  fileName: string;
}
```

---

## How It Works

1. User selects a Government ID file → `onChange` fires immediately (for OCR pre-fill)
2. User selects specimen signature files
3. User clicks **Next** → parent calls `uploadRef.current()`
4. Component uploads all files to the DMS API
5. Files are saved to Google Drive and recorded in the database with `is_final = 0`
6. `onIdUploadComplete` and `onSignatureUploadComplete` fire with the upload results
7. A later step in the purchase flow sets `is_final = 1` to confirm the documents

---

## Notes

- Files are uploaded to the DMS API endpoint `POST /api/files/direct-upload`
- The `is_final = 0` flag means the upload is temporary until confirmed by the purchase flow
- This component is intended for internal St. Peter Group use only