From 60cdc2b0364d4d7a65733c7ba1deb81ba7b73286 Mon Sep 17 00:00:00 2001
From: tsushanth <78000697+tsushanth@users.noreply.github.com>
Date: Thu, 11 Jun 2026 09:13:21 -0700
Subject: [PATCH 1/2] docs(events): note that GET /events silently ignores the
 `order` parameter

Refs #1610.

`ListEventOptions.order` was added in #1524 to match the API reference,
but the live `GET /events` endpoint silently ignores it on every value
(`asc`, `desc`, `normal`, omitted) and always returns events oldest-first.
That's been verified with raw curl against a sandbox key on 2026-06-11,
so it's not an SDK serialization bug. A consumer who upgraded for #1524
to seed cursor pagination from the newest event with
`order=desc&limit=1` is silently getting the oldest event instead, with
no error to root-cause from.

Annotate the field's JSDoc with a pointer to the tracking issue so
intellisense surfaces the gotcha at the point of confusion, and explain
the current ascending behaviour and the cursor-pagination workaround.
Leaves the wire format unchanged so callers automatically pick up the
server-side fix the moment it ships.
---
 src/events/interfaces/list-events-options.interface.ts | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/events/interfaces/list-events-options.interface.ts b/src/events/interfaces/list-events-options.interface.ts
index 003e4fc4c..6138fbeb8 100644
--- a/src/events/interfaces/list-events-options.interface.ts
+++ b/src/events/interfaces/list-events-options.interface.ts
@@ -7,6 +7,16 @@ export interface ListEventOptions {
   limit?: number;
   after?: string;
   organizationId?: string;
+  /**
+   * As of 2026-06-11 the `GET /events` endpoint silently ignores this
+   * parameter and always returns events oldest-first regardless of whether
+   * `asc`, `desc`, `normal`, or nothing is sent — see
+   * {@link https://github.com/workos/workos-node/issues/1610}. The SDK
+   * continues to serialize the value on the wire so callers automatically
+   * pick up the server-side fix when it lands; until then, treat the
+   * response as ascending-by-`created_at` and seed cursor pagination from
+   * the oldest end of the stream.
+   */
   order?: 'asc' | 'desc';
 }
 

From 23ec8f7d180f81c1fa04423569d278e569fa5dc5 Mon Sep 17 00:00:00 2001
From: tsushanth <78000697+tsushanth@users.noreply.github.com>
Date: Fri, 12 Jun 2026 19:40:09 -0700
Subject: [PATCH 2/2] docs(events): mirror the order no-op note onto
 SerializedListEventOptions

Greptile pointed out (#1611 review) that the wire-layer interface
SerializedListEventOptions.order had no JSDoc, so a maintainer working
purely at the serialization layer would miss the caveat that lives on
ListEventOptions.order. Add a short note pointing at the canonical
JSDoc and at issue #1610 so both surfaces stay in sync.
---
 src/events/interfaces/list-events-options.interface.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/events/interfaces/list-events-options.interface.ts b/src/events/interfaces/list-events-options.interface.ts
index 6138fbeb8..9192afb2f 100644
--- a/src/events/interfaces/list-events-options.interface.ts
+++ b/src/events/interfaces/list-events-options.interface.ts
@@ -27,5 +27,11 @@ export interface SerializedListEventOptions {
   limit?: number;
   after?: string;
   organization_id?: string;
+  /**
+   * Wire-layer mirror of {@link ListEventOptions.order}. The server-side bug
+   * lives at this layer: as of 2026-06-11 `GET /events?order=desc` returns
+   * events oldest-first regardless. See
+   * {@link https://github.com/workos/workos-node/issues/1610}.
+   */
   order?: 'asc' | 'desc';
 }