docs(events): note that GET /events silently ignores the order parameter

[tsushanth]

Refs #1610.

ListEventOptions.order was added in #1524 to match the published API reference, but the live GET /events endpoint silently ignores the parameter — every value (asc, desc, normal, omitted) returns byte-identical, oldest-first pages, verified with raw curl against a sandbox key on 2026-06-11. So this is a server-side bug, not an SDK serialization one. The consequence for SDK consumers is real: anyone who upgraded for #1524 to fetch the newest event with order=desc&limit=1 silently gets the oldest event instead, with no error to root-cause from.

This PR adds a JSDoc annotation to the field pointing at #1610, explaining the current ascending behaviour and the cursor-pagination workaround. The wire format is unchanged — callers automatically pick up the server-side fix the moment it ships.

I'd rather not remove the field (that's a breaking change for downstream code that already passes the parameter through), and surfacing it at the type-system level seems like the lowest-friction way to make sure the next person reading intellisense for listEvents doesn't waste an afternoon debugging why their desc request comes back ascending. Happy to swap to a @deprecated tag instead if that's the maintainer preference.

[greptile-apps]

Greptile Summary

Adds a JSDoc warning to ListEventOptions.order documenting the known server-side bug where GET /events silently ignores the order parameter and always returns events oldest-first, with a link to issue #1610 and a workaround note. No runtime or wire-format changes are made.

• The order field gains a JSDoc comment explaining the current ascending-only behaviour, referencing issue Events API: documented order parameter is silently ignored (always oldest-first) despite SDK sending it since #1524 #1610, and advising callers to treat the response as ascending until the server fix ships.
• The mirrored SerializedListEventOptions.order field (the wire-layer interface) does not receive the same annotation, leaving an undocumented surface for maintainers working at that layer.

Confidence Score: 4/5

Safe to merge — the change is documentation-only; no runtime behaviour, serialization, or type shapes are altered.

The diff touches only a JSDoc comment. The one gap worth noting before merging is that the companion SerializedListEventOptions.order field in the same file is left unannotated, so a maintainer working at the serialization layer wouldn’t see the warning without scrolling up.

src/events/interfaces/list-events-options.interface.ts — specifically the unannotated SerializedListEventOptions.order field on line 30.

Important Files Changed

Filename	Overview
src/events/interfaces/list-events-options.interface.ts	Adds JSDoc comment to order field explaining the known server-side bug where GET /events silently ignores the parameter; no runtime or wire-format changes.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant SDK as WorkOS SDK
    participant API as GET /events API

    Caller->>SDK: "listEvents({ order: 'desc', limit: 1 })"
    Note over SDK: Serializes order='desc' onto the wire
    SDK->>API: "GET /events?order=desc&limit=1"
    Note over API: Silently ignores order
    API-->>SDK: oldest event (ascending page)
    SDK-->>Caller: oldest event (not newest!)
    Note over Caller: JSDoc now warns about this behaviour

Loading

Comments Outside Diff (1)

1. src/events/interfaces/list-events-options.interface.ts, line 20-31 (link)

   The JSDoc comment is only on the ListEventOptions interface, but SerializedListEventOptions.order (line 30) is the field that actually goes on the wire. A developer editing the serialization layer who reads only SerializedListEventOptions won't see the caveat. Adding the same note there — or a cross-reference — keeps both surfaces in sync.

   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!

_{Reviews (1): Last reviewed commit: "docs(events): note that GET /events sile..." | Re-trigger Greptile}

[greptile-apps]

The comment mentions normal as a value that was tested, but the type union only allows 'asc' | 'desc'. Mentioning normal may confuse readers into thinking it is a valid SDK value. Dropping it keeps the comment consistent with the public API surface.

Suggested change

	* parameter and always returns events oldest-first regardless of whether
	* `asc`, `desc`, `normal`, or nothing is sent — see
	* parameter and always returns events oldest-first regardless of whether
	* `asc`, `desc`, or nothing is sent — see