Overhaul DocumentLink Schema for Dynamic Visitor Fields

[mahid797]

We need to refactor the Link → DocumentLink model to support dynamic visitor fields via JSON, provide clarity on ownership (createdByUserId), improve naming consistency, and optionally implement more robust analytics. This change will let us add extra visitor fields in the future (phone, address, etc.) without creating new columns. The server will only store the keys or minimal flags for each requested field, leaving the front end responsible for labels, input types, etc.

While not currently under development, we will also create a feature to update link preferences such as updating/removing expiry times, changing Public Link option, changing Link Name (alias), etc.

Goals & Scope

• Rename the table from Link to DocumentLink, and rename some fields
• Add visitorFields (JSON column) that describes which fields (e.g., name, email, phone) are requested from each visitor.
  • Store only the minimal structure, e.g. {"name":true,"email":true} or ["name","email"].
• Adjust uniqueness constraints so alias is unique per (createdByUserId, alias) or (documentId, alias) rather than globally, if desired.
• Retain or revise password, expirationTime, and isPublic logic as needed.
• Add analytics structure (e.g., a separate DocumentLinkEvent table) as we need detailed download/view events.

📊 An Analytics API will be covered in a future issue to handle download/view tracking.

Detailed Tasks

1. Rename Schema Entities

   • In schema.prisma, rename Link → DocumentLink.
   • Rename fields (e.g., userId → createdByUserId, friendlyName → alias).

2. Add JSON Field for Visitor Config

   • Add visitorFields Json? to DocumentLink.

   • The server only stores the keys or booleans for which visitor fields are requested. For example:

     { "name": true, "email": true }
     

     or

     ["name", "email"]
     

3. Visitor Config

   • Add a shared config file in src/shared/config/visitorFieldsConfig.ts containing all possible visitor fields (e.g., name, email, phoneNumber, etc.), each with a type and label.

   • The backend will not store labels/types in the visitorFields column—only field keys or boolean mappings.

   • During validation (when creating a link or at link access), the server references this config to ensure the requested fields are valid.

   • Example Config:

     export const visitorFieldsConfig = {
     name: { type: 'string', label: 'Full Name' },
     email: { type: 'string', label: 'Email Address' },
     expirationTime: { type: 'date', label: 'Expiration Date' }, // Optional, but included if expiration is visitor-based
     };

     // Export the keys separately for quick reference
     export const visitorFieldKeys = Object.keys(visitorFieldsConfig);

   File Path: src/shared/config/visitorFieldsConfig.ts

4. Adjust Uniqueness Constraints

   • If alias should be unique only per user or doc, add a composite unique index:

     @@unique([createdByUserId, alias])
     

   • Keep linkUrl globally unique.

5. (Optional) Add or Sketch Analytics Table

   • If needed, create DocumentLinkEvent to track downloads/views with fields like eventType = 'VIEW' or 'DOWNLOAD'.

6. Password Protection

   • If password is non‐null, the server’s response should include passwordProtected: true so the client can handle it.

Acceptance Criteria

• Prisma schema includes the DocumentLink table (renamed from Link) with correct fields.
• visitorFields JSON column is present and tested, storing minimal data (no labels/types).
• Migrations run successfully, with no data loss except for potential rename friction if carefully mapped.
• Code references (LinkService, routes, etc.) updated to use new names (alias, createdByUserId, etc.).
• src/shared/config/visitorFieldsConfig.ts exists with all valid fields and labels.
• Server uses visitorFieldsConfig to validate fields at link creation (and optionally at visitor submission).
• (Optional) A new analytics table or approach is added if we want to track events in detail.