core/src/modules/nuage/GUIDE-client-dashboard.md

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.
• 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):

{
  "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:

{
  "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:

{
  "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:

// 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:

<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'.