[PULSE-41] Implement UTM Campaign URL Builder & Tools

[uz1mani]

Work Item

PULSE-41

Summary

• Implemented a comprehensive UTM Campaign URL Builder accessible via a new global "Tools" page and directly from site dashboards.
• Updated the global navigation to include a "Tools" link for logged-in users.
• Ensured full compliance with the Ciphera design system by using shared UI components and standard styling.

Changes

• New Component: Created UtmBuilder.tsx in Pulse/pulse-frontend/components/tools/ to handle URL construction, site selection, and domain enforcement.
• New Page: Added Pulse/pulse-frontend/app/tools/page.tsx to host the standalone builder tool.
• Dashboard Integration: Updated Campaigns.tsx to include a "Build URL" button that opens the builder in a modal with the current site pre-selected.
• Navigation: Modified Pulse/pulse-frontend/app/layout-content.tsx and ciphera-ui/Header.tsx to inject a "Tools" link into the main header bar when a user is logged in.
• Design System: Refactored new components to use Input and Button from @ciphera-net/ui for consistent styling (focus rings, dark mode, hover states).
• Versioning: Bumped ciphera-ui to 0.0.44 and updated all frontend dependencies (auth, drop, pulse, website) to match.

Test Plan

[ ] Log in to Pulse and verify the "Tools" link appears in the top navigation bar.
[ ] Navigate to /tools and verify the UTM Builder loads and allows selecting any site.
[ ] Go to a specific site dashboard, click "Build URL" in the Campaigns widget, and verify the current site is pre-selected and the domain is locked.
[ ] Generate a URL with special characters in the campaign name and verify it is correctly URL-encoded.
[ ] Check that the "Copy to Clipboard" button works.
[ ] Verify dark mode styling for all new inputs and modals.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR implements a comprehensive UTM Campaign URL Builder feature that integrates seamlessly into the Pulse analytics platform. The implementation adds both a standalone Tools page accessible via global navigation and a contextual modal accessible from individual site dashboards.

Key Changes:

• New UtmBuilder component handles URL construction with automatic site selection, domain enforcement, and clipboard copy functionality
• Global "Tools" navigation link added to header for authenticated users
• Dashboard integration via "Build URL" button that opens the builder in a modal with the current site pre-selected
• Proper error handling for API failures and malformed URLs
• Design system compliance using shared UI components from @ciphera-net/ui

Architecture:

• The component uses two separate useEffect hooks to avoid dependency issues: one for fetching sites on mount, another for initialization logic
• When a site is selected, the domain is locked and users can only modify the path portion
• URL generation uses the native URL API for proper encoding and parameter handling
• All UTM parameters are automatically lowercased for consistency (with a minor inconsistency in utm_term and utm_content)

Minor Issue Found:

• Inconsistent lowercasing of optional UTM parameters (utm_term and utm_content) compared to required parameters

Confidence Score: 4.5/5

• This PR is safe to merge with only a minor style inconsistency that doesn't affect functionality
• The implementation is well-structured with proper error handling, React best practices (resolved dependency array issue), and good UX design. The only issue found is a minor style inconsistency in parameter casing that doesn't impact functionality or security. All changes follow existing patterns in the codebase and use the design system consistently.
• No files require special attention - the casing inconsistency in UtmBuilder.tsx is optional to fix

Important Files Changed

Filename	Overview
components/tools/UtmBuilder.tsx	New UTM builder component with site selection, URL construction, and clipboard copy functionality - well-structured with proper error handling
app/tools/page.tsx	Simple page wrapper for the UTM builder tool - minimal code, no issues
components/dashboard/Campaigns.tsx	Added "Build URL" button and modal integration for UTM builder with proper state management
app/layout-content.tsx	Added Tools navigation link to header for authenticated users - clean integration

Sequence Diagram

sequenceDiagram
    participant User
    participant LayoutContent
    participant ToolsPage
    participant Campaigns
    participant UtmBuilder
    participant API as listSites API
    participant Clipboard

    Note over User,Clipboard: Standalone Tools Page Flow
    User->>LayoutContent: Click "Tools" nav link
    LayoutContent->>ToolsPage: Navigate to /tools
    ToolsPage->>UtmBuilder: Render (no initialSiteId)
    UtmBuilder->>API: Fetch all sites
    API-->>UtmBuilder: Return sites array
    UtmBuilder->>UtmBuilder: Auto-select first site
    User->>UtmBuilder: Enter UTM parameters
    UtmBuilder->>UtmBuilder: Generate URL with params
    User->>UtmBuilder: Click copy button
    UtmBuilder->>Clipboard: Write generated URL
    UtmBuilder->>User: Show checkmark (copied)

    Note over User,Clipboard: Dashboard Modal Flow
    User->>Campaigns: Click "Build URL" button
    Campaigns->>UtmBuilder: Open modal with initialSiteId
    UtmBuilder->>API: Fetch all sites
    API-->>UtmBuilder: Return sites array
    UtmBuilder->>UtmBuilder: Pre-select site by initialSiteId
    UtmBuilder->>UtmBuilder: Lock domain to selected site
    User->>UtmBuilder: Add path and UTM params
    UtmBuilder->>UtmBuilder: Generate URL with params
    User->>UtmBuilder: Click copy button
    UtmBuilder->>Clipboard: Write generated URL
    UtmBuilder->>User: Show checkmark (copied)

Loading

[greptile-apps]

_{4 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

_{4 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Inconsistent casing: utm_term and utm_content aren't lowercased like the other UTM parameters

Suggested change

	if (values.term) url.searchParams.set('utm_term', values.term)
	if (values.content) url.searchParams.set('utm_content', values.content)
	if (values.term) url.searchParams.set('utm_term', values.term.toLowerCase())
	if (values.content) url.searchParams.set('utm_content', values.content.toLowerCase())

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review.
Path: components/tools/UtmBuilder.tsx
Line: 75:76

Comment:
Inconsistent casing: `utm_term` and `utm_content` aren't lowercased like the other UTM parameters

```suggestion
      if (values.term) url.searchParams.set('utm_term', values.term.toLowerCase())
      if (values.content) url.searchParams.set('utm_content', values.content.toLowerCase())
```

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.