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] 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';
 }