[v4]: add method 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 a method param to the v4 /click route to support both coordinate-based and JS event clicks in one endpoint, defaulting to xy for backward compatibility. Caps clickCount at 3 and updates the OpenAPI/action output. Addresses Linear STG-1659.

• New Features
  • Adds method: 'xy' | 'jsevent' (default xy) to /click params; action output now includes and requires method via PageClickParamsOutput.
  • Limits clickCount to 1–3 in schema and OpenAPI in packages/server-v4.
  • Adds integration tests for coordinate clicks and method: "jsevent" selector clicks.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: c02c521

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

[pirate]

Suggested change

	synthetic: z.boolean().default(false),
	method: z.enum(['jsevent', 'xy']).default('jsevent'),

[pirate]

Suggested change

	clickCount: z.number().int().min(1).optional(),
	clickCount: z.number().int().lte(3).gte(1).optional(),

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/server-v4/openapi.v4.yaml">

<violation number="1" location="packages/server-v4/openapi.v4.yaml:2494">
P1: The schema replaces `synthetic` with `method`, which breaks the intended `/click` API contract and rejects `synthetic` requests.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P1: The schema replaces synthetic with method, which breaks the intended /click API contract and rejects synthetic requests.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/server-v4/openapi.v4.yaml, line 2494:

<comment>The schema replaces `synthetic` with `method`, which breaks the intended `/click` API contract and rejects `synthetic` requests.</comment>

<file context>
@@ -2488,12 +2488,15 @@ components:
-        synthetic:
-          default: false
-          type: boolean
+        method:
+          default: xy
+          type: string
</file context>