[v4]: add synthetic arg to /click route stub

[seanmcguire12]

why

• to group two types of clicking into a single route. ie, we don't need to add a separate /sendClickEvent route

what changed

• added an optional synthetic parameter to the /click schema, which we will internally route to .sendClickEvent()

screenshot:

test plan

• added a test to verify passing synthetic: true passes validation

---

Summary by cubic

Add an optional synthetic flag to the v4 /click route to support synthetic click events through the same endpoint, defaulting to false for backward compatibility. Addresses Linear STG-1659.

• New Features
  • Adds synthetic?: boolean (default false) to /click params and routes synthetic clicks to sendClickEvent.
  • Updates OpenAPI in packages/server-v4 to include synthetic in params and require it in action output params (with default false).
  • Adds an integration test validating synthetic: true is accepted and succeeds.

^{Written for commit b0bd197. Summary will update on new commits. Review in cubic}

[changeset-bot]

⚠️ No Changeset found

Latest commit: b0bd197

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

No issues found across 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Client
    participant API as API Route (/v4/page/click)
    participant Schema as Zod / OpenAPI Validation
    participant Service as Page Service

    Client->>API: POST /v4/page/click { selector, synthetic? }
    
    API->>Schema: Validate request body
    Note over Schema: NEW: Schema now includes "synthetic" (boolean, default false)
    
    alt Invalid Payload
        Schema-->>API: Validation Error
        API-->>Client: 400 Bad Request
    else Valid Payload
        Schema-->>API: Parsed Params
        API->>Service: click(params)

        alt NEW: params.synthetic == true
            Service->>Service: INTERNAL: route to sendClickEvent()
            Note over Service: Dispatches a synthetic JS click event
        else params.synthetic == false (default)
            Service->>Service: Standard click() logic
            Note over Service: Simulates trusted physical mouse interaction
        end

        Service-->>API: Action Result
        
        API->>Schema: NEW: Map to PageClickActionOutput
        Note over Schema: Output now includes synthetic flag in params metadata
        Schema-->>API: Formatted Response
        
        API-->>Client: 200 OK + Result
    end

Loading