# Nuage module – Dashboard (Mes fichiers)

This guide explains how to add a **Mes fichiers** (My files) section to your client dashboard so that logged-in users can browse, download, and upload files/folders that have been shared with them by an admin.

## Prerequisites

- Auth and dashboard set up as in [Client dashboard and user features](../../features/auth/README-dashboard.md).
- Nuage module enabled (`ZEN_MODULE_NUAGE=true`).
- **User–share link**: In the admin Nuage explorer, an admin must have created a share targeting a specific user (by their email/account). The share is stored in `zen_nuage_shares` with `user_id` set to the user.

## API for "my shares"

When a user is authenticated, you can load all active file/folder shares assigned to them with:

| Endpoint | Method | Auth | Description |
|----------|--------|------|-------------|
| `/zen/api/nuage/me` | GET | Session (user) | Returns all active shares assigned to the current user. |
| `/zen/api/nuage/shared` | GET | Session (user) | Returns the contents of a shared folder (subfolders + files). |
| `/zen/api/nuage/download` | GET | Session (user) | Returns a signed download URL for a file inside a share. |
| `/zen/api/nuage/upload` | POST | Session (user) | Uploads a file into a shared folder (collaborator permission only). |

### GET `/zen/api/nuage/me`

**Example response (user has active shares):**

```json
{
  "success": true,
  "shares": [
    {
      "id": 1,
      "token": "abc123...",
      "target_type": "folder",
      "target_id": "42",
      "target_name": "Contrats 2025",
      "permission": "reader",
      "expires_at": null
    },
    {
      "id": 2,
      "token": "def456...",
      "target_type": "file",
      "target_id": "17",
      "target_name": "Devis-2025-01.pdf",
      "permission": "collaborator",
      "expires_at": "2025-12-31T23:59:59.000Z"
    }
  ]
}
```

**When the user has no active shares:**

```json
{
  "success": true,
  "shares": []
}
```

### GET `/zen/api/nuage/shared`

**Query parameters:**

- `shareId` *(required)* – The share `token` returned by `/nuage/me`.
- `folder` *(optional)* – ID of a subfolder to navigate into.

**Example response:**

```json
{
  "success": true,
  "folders": [
    { "id": "10", "name": "Sous-dossier", "created_at": "2025-03-01T10:00:00.000Z" }
  ],
  "files": [
    {
      "id": "55",
      "display_name": "rapport.pdf",
      "mime_type": "application/pdf",
      "size": 204800
    }
  ],
  "breadcrumb": [
    { "id": "10", "name": "Sous-dossier" }
  ],
  "permission": "reader"
}
```

### GET `/zen/api/nuage/download`

**Query parameters:**

- `fileId` *(required)* – ID of the file to download.
- `shareId` *(required)* – The share `token`.

Returns a signed URL to download the file directly from storage.

### POST `/zen/api/nuage/upload`

Only available for shares with `permission: "collaborator"` targeting a folder.

**Form data fields:**

- `file` *(required)* – The file to upload.
- `shareId` *(required)* – The share `token`.
- `folderId` *(optional)* – ID of a subfolder to upload into (must be within the share scope).

All requests must send the session cookie (e.g. `fetch(..., { credentials: 'include' })`).

## Adding the Mes fichiers section to the dashboard

### 1. Protected page

Create a dashboard page that requires login and renders the Nuage section:

```js
// app/dashboard/fichiers/page.js (Server Component)
import { protect } from '@hykocx/zen/auth';
import ClientNuageSection from '@hykocx/zen/nuage/dashboard';

export default async function DashboardFichiersPage() {
  await protect({ redirectTo: '/auth/login' });

  return (
    <div>
      <h1>Mes fichiers</h1>
      <ClientNuageSection
        apiBasePath="/zen/api"
        nuagePageBasePath="/zen/nuage"
      />
    </div>
  );
}
```

**Props:**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `apiBasePath` | `string` | `"/zen/api"` | Base path for the Zen API. |
| `nuagePageBasePath` | `string` | `"/zen/nuage"` | Base path for the Nuage public pages (currently unused, reserved for future links). |
| `emptyMessage` | `string` | `"Aucun document partagé pour le moment."` | Message shown when the user has no active shares. |
| `newTab` | `boolean` | `false` | Open file download links in a new browser tab. |

### 2. Link in the dashboard layout

In your dashboard layout or nav, add a link to the Mes fichiers page:

```js
<Link href="/dashboard/fichiers">Mes fichiers</Link>
```

## Behaviour summary

- **Logged in, has active shares** → The section lists all files/folders shared with the user. Clicking a share opens a file browser with navigation, download, and (if `collaborator`) upload.
- **Logged in, no active shares** → The section shows `emptyMessage`.
- **Expired share** → The share is displayed as greyed out and cannot be opened.
- **Not logged in** → The dashboard page should not be reachable if you use `protect()` and redirect to login.
- **File preview** → Clicking a viewable file (image, PDF, video, audio, plain text) opens a full-screen viewer. Non-viewable files trigger a direct download.
- **Sorting** → The file list can be sorted by name, date, or size (ascending/descending).
- **Upload feedback** → When uploading as a collaborator, a per-file progress queue is displayed with a checkmark once each file completes.

## Share permissions

There are two permission levels for a share:

| Permission | Browse | Download | Upload |
|------------|--------|----------|--------|
| `reader` | Yes | Yes | No |
| `collaborator` | Yes | Yes | Yes (folder shares only) |

The collaborator upload zone appears automatically when the share is a folder with `permission: "collaborator"`. Files can be dragged and dropped or selected via the file picker. An optional upload size limit (`upload_limit_bytes`) can be set by the admin on the share.

## Creating a share (admin side)

In the Zen admin Nuage explorer:

1. Navigate to the file or folder you want to share.
2. Click the **Share** button (or the share icon).
3. Search for the user by email and select them.
4. Set the permission (`reader` or `collaborator`).
5. Optionally set an expiry date and an upload size limit.
6. Save. The user will immediately see the share in their dashboard under `GET /zen/api/nuage/me`.

## Security

- All four client-facing endpoints (`/nuage/me`, `/nuage/shared`, `/nuage/download`, `/nuage/upload`) require a valid session (`auth: 'user'`). No admin role needed.
- A user can only access shares explicitly assigned to them (`zen_nuage_shares.user_id = session.user.id`).
- File download and folder navigation are scoped to the share target — it is not possible to access files outside the shared scope (IDOR protection enforced server-side).
- Upload is only allowed when `permission = 'collaborator'` and `target_type = 'folder'`.