feat: add preview access for non-public forms in form-fields API

[metaforx]

• Handle form fields preview.

Summary by Sourcery

Allow preview access to non-public forms via the form-fields API while preserving existing behavior for public forms.

New Features:

• Expose an is_preview flag in the form-fields API response to distinguish preview from public access.
• Enable authenticated users with the appropriate view permission to retrieve field definitions for non-public forms as a preview.

Documentation:

• Document the preview-access behavior and requirements for the form-fields API in the internal task description.

Tests:

• Add tests covering public vs non-public form access for anonymous, staff with permission, staff without permission, and superusers, including is_preview behavior.

[sourcery-ai]

Reviewer's Guide

Extends the form-fields API to support previewing non-public forms by authorized users, adds an is_preview flag to the response, refactors access/error handling in the view, and introduces tests and internal documentation for the new preview behavior.

Sequence diagram for form-fields API access and preview behavior

sequenceDiagram
    actor User
    participant ClientApp
    participant FormFieldsView
    participant FormEntryModel
    participant AuthSystem

    User->>ClientApp: Request form rendering for slug
    ClientApp->>FormFieldsView: GET /api/fobi-form-fields/{slug}/

    FormFieldsView->>FormEntryModel: get(slug=slug)
    alt FormEntry exists
        FormEntryModel-->>FormFieldsView: FormEntry
        alt FormEntry is_public is true
            FormFieldsView->>FormFieldsView: is_preview = false
            FormFieldsView->>FormFieldsView: get_declared_fields(form_entry)
            FormFieldsView->>FormFieldsView: _build_widget_map(form_entry)
            FormFieldsView-->>ClientApp: 200 OK
            ClientApp-->>User: Render form (is_preview=false)
        else FormEntry is_public is false
            alt User is_authenticated and has view_formentry permission
                FormFieldsView->>AuthSystem: check has_perm view_formentry
                AuthSystem-->>FormFieldsView: allowed
                FormFieldsView->>FormFieldsView: is_preview = true
                FormFieldsView->>FormFieldsView: get_declared_fields(form_entry)
                FormFieldsView->>FormFieldsView: _build_widget_map(form_entry)
                FormFieldsView-->>ClientApp: 200 OK (is_preview=true)
                ClientApp-->>User: Render form with preview indicator
            else User not authenticated or lacks permission
                FormFieldsView-->>ClientApp: 404 NotFound
                ClientApp-->>User: Show form not found
            end
        end
    else FormEntry does not exist
        FormEntryModel-->>FormFieldsView: DoesNotExist
        FormFieldsView-->>ClientApp: 404 NotFound
        ClientApp-->>User: Show form not found
    end

Loading

File-Level Changes

Change	Details	Files
Allow preview access to non-public forms with explicit permission and expose preview state in the form-fields API response.	Change FormEntry lookup to use only slug and then enforce visibility rules instead of filtering by is_public in the query. Introduce preview access: if the form is non-public, only authenticated users with the appropriate permission can access it; others receive a 404. Add an is_preview boolean field to the response payload indicating whether the form is being accessed in preview mode. Normalize error handling for missing forms to raise a DRF NotFound exception instead of returning a manual 404 Response. Slightly simplify field/choices mapping logic and remove an unused EmailField import from the widget map helper.	src/unfold_fobi/api/views.py
Add tests covering public vs private form access and preview behavior for different user roles.	Add a regression test to validate the shared form_entry fixture returns a valid form-fields payload. Introduce a dedicated TestFormFieldsPreviewAccess test class with fixtures to build a private form and staff users with and without the relevant permission. Add tests to verify: public forms are accessible to anonymous and staff with is_preview false; private forms return 404 to anonymous and staff without permission; private forms return 200 with is_preview true for staff with permission and superusers.	tests/api/test_form_fields.py
Document the new preview-access behavior and constraints for the form-fields API.	Add an internal task document describing the goal, scope, implementation requirements, acceptance criteria, and tests for the form-fields preview feature.	.agents/tasks/T23_api_form_fields_preview_hook.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• The implementation checks request.user.has_perm("fobi.view_formentry"), but the task spec and acceptance criteria call for unfold_fobi.view_formentryproxy; aligning the permission codename and app label will avoid surprises and keep behavior consistent with the documented contract.
• Switching from returning a JSON body {"error": "Form not found"} to raising NotFound changes the 404 response payload; if existing consumers rely on the previous error shape, consider preserving the response structure while still using DRF’s NotFound status handling.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The implementation checks `request.user.has_perm("fobi.view_formentry")`, but the task spec and acceptance criteria call for `unfold_fobi.view_formentryproxy`; aligning the permission codename and app label will avoid surprises and keep behavior consistent with the documented contract.
- Switching from returning a JSON body `{"error": "Form not found"}` to raising `NotFound` changes the 404 response payload; if existing consumers rely on the previous error shape, consider preserving the response structure while still using DRF’s `NotFound` status handling.

## Individual Comments

### Comment 1
<location path="src/unfold_fobi/api/views.py" line_range="107-108" />
<code_context>
+    is_preview = False
+    if not form_entry.is_public:
+        if (
+            request.user.is_authenticated
+            and request.user.has_perm("fobi.view_formentry")
+        ):
+            is_preview = True
</code_context>
<issue_to_address>
**🚨 question (security):** Preview access is granted solely on a global permission, which may be too broad for private forms.

Using only the global `fobi.view_formentry` permission means any user with that permission can preview all non-public forms, regardless of ownership or relationship to the form. If previews are meant to be more restricted, consider changing this to an object-level or ownership-based check, or introducing a dedicated, narrower preview permission.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

🚨 question (security): Preview access is granted solely on a global permission, which may be too broad for private forms.

Using only the global fobi.view_formentry permission means any user with that permission can preview all non-public forms, regardless of ownership or relationship to the form. If previews are meant to be more restricted, consider changing this to an object-level or ownership-based check, or introducing a dedicated, narrower preview permission.