Merge pull request #734 from martoniel/openAPI-examples-for-Appindexer

Open api examples for appindexer

Author: greatest0fallt1me

docs/audit-log-pagination.md

@@ -0,0 +1,88 @@
+# Audit Log API — Cursor Pagination
+
+`GET /api/admin/audit` returns audit log entries ordered by `(created_at DESC, id DESC)` with opaque keyset cursor pagination. This document explains the ordering contract, why a composite cursor is necessary, and how to page through results correctly.
+
+## Why `(created_at, id)` and not just `created_at`
+
+A `ORDER BY created_at DESC` alone is **not stable** when multiple rows share the same millisecond timestamp — which is routine under concurrent writes (e.g. a burst of audit events from a batch admin operation or multiple simultaneous requests). Postgres makes no guarantee about the relative order of ties, so a single-column sort can return different orderings on repeated executions, causing a page boundary to **skip or duplicate rows**.
+
+Adding `id DESC` as a tie-breaker makes the sort key `(created_at, id)` globally unique and deterministic. The backing database index `audit_logs_created_at_id_idx` covers exactly this pair:
+
+```sql
+CREATE INDEX audit_logs_created_at_id_idx
+  ON audit_logs (created_at DESC, id DESC);
+```
+
+## How the cursor works
+
+The cursor encodes the `(created_at, id)` of the **last row on the current page**. On the next request it is decoded into a keyset predicate:
+
+```sql
+WHERE (created_at < :cursor_ts)
+   OR (created_at = :cursor_ts AND id < :cursor_id)
+ORDER BY created_at DESC, id DESC
+LIMIT :limit + 1   -- one extra row for the "has more" check
+```
+
+The `OR` branches correspond to two cases:
+
+| Case | Meaning |
+|------|---------|
+| `created_at < cursor_ts` | The next row has an older timestamp — the common case. |
+| `created_at = cursor_ts AND id < cursor_id` | The next row shares the same timestamp; the `id` tie-breaker selects the correct continuation point. |
+
+## Paging example
+
+```
+GET /api/admin/audit?limit=2
+→ { data: [{id:"e", ...}, {id:"d", ...}], nextCursor: "eyJ...A" }
+
+GET /api/admin/audit?limit=2&cursor=eyJ...A
+→ { data: [{id:"c", ...}, {id:"b", ...}], nextCursor: "eyJ...B" }
+
+GET /api/admin/audit?limit=2&cursor=eyJ...B
+→ { data: [{id:"a", ...}], nextCursor: null }
+```
+
+All five rows are returned exactly once, even if all five share the same `created_at` timestamp.
+
+## Cursor format
+
+Cursors are **opaque** base64url strings. Their internal encoding is versioned and may change between releases. Never construct a cursor manually — always use the `nextCursor` value returned by the API. A missing or invalid cursor is treated as "start from the beginning" (first page).
+
+## Query parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `cursor` | string | Opaque cursor from the previous page's `nextCursor`. Omit for the first page. |
+| `limit` | integer | Rows per page. Defaults to 20, capped at 100. |
+| `action` | string | Exact-match filter on the `action` field. |
+| `actor` | string | Exact-match filter on `wallet_address`. |
+| `startDate` | ISO 8601 | Include rows with `created_at >= startDate`. |
+| `endDate` | ISO 8601 | Include rows with `created_at <= endDate`. |
+
+## Stream export
+
+`GET /api/admin/audit/export` streams all matching rows as NDJSON, also ordered `(created_at DESC, id DESC)`. This endpoint does not paginate — it streams the full result set up to the configured `maxRecords` limit (default 100 000). Use filters (`startDate`, `endDate`, `action`, `actor`) to narrow the export.
+
+## Migration
+
+Migration `0025_audit_logs_cursor_index.sql` applied the following change:
+
+```sql
+-- Replaced:
+DROP INDEX IF EXISTS audit_logs_created_at_idx;
+
+-- With:
+CREATE INDEX IF NOT EXISTS audit_logs_created_at_id_idx
+  ON audit_logs (created_at DESC, id DESC);
+```
+
+The old single-column index is superseded by the composite index, which covers the same queries and additionally accelerates the cursor tie-breaker predicate.
+
+## See also
+
+- [`src/repositories/auditLogRepo.ts`](../src/repositories/auditLogRepo.ts) — keyset predicate implementation
+- [`src/utils/cursor.ts`](../src/utils/cursor.ts) — cursor encode/decode
+- [`drizzle/migrations/0025_audit_logs_cursor_index.sql`](../drizzle/migrations/0025_audit_logs_cursor_index.sql) — migration
+- [`tests/auditLogCursorStability.test.ts`](../tests/auditLogCursorStability.test.ts) — cursor stability tests

openapi.yaml

@@ -918,10 +918,18 @@ components:
         - totals
     AuditEntry:
       type: object
+      description: >
+        A single audit log entry. Entries are always returned ordered by
+        `created_at DESC, id DESC`. The `(created_at, id)` pair forms the
+        composite keyset cursor key — both fields are present in every entry.
       properties:
         id:
           type: string
           format: uuid
+          description: >
+            Unique entry identifier (UUID). Acts as the tie-breaker in the
+            keyset cursor when multiple entries share the same `createdAt`
+            timestamp (common under concurrent writes).
         action:
           type: string
         actor:
@@ -931,6 +939,10 @@ components:
         createdAt:
           type: string
           format: date-time
+          description: >
+            ISO 8601 timestamp of when the event was recorded. Primary sort
+            key for cursor pagination (DESC). Sub-millisecond precision is
+            preserved in the cursor encoding.
       required:
         - id
         - action
@@ -3480,6 +3492,13 @@ paths:
       tags:
         - Admin
       summary: List audit log entries (admin only)
+      description: >
+        Returns a paginated list of audit log entries ordered by
+        `created_at DESC, id DESC`. The composite sort key `(created_at, id)`
+        is unique and monotone, so pagination is stable even when multiple rows
+        share the same millisecond timestamp (a common occurrence under
+        concurrent writes). Pass the `nextCursor` value from one response as
+        the `cursor` parameter of the next request to advance through pages.
       security:
         - bearerAuth: []
       parameters:
@@ -3488,35 +3507,46 @@ paths:
           required: false
           name: action
           in: query
+          description: Filter by audit action string (exact match).
         - schema:
             type: string
           required: false
           name: actor
           in: query
+          description: Filter by wallet address of the actor (exact match).
         - schema:
             type: string
             format: date-time
           required: false
           name: startDate
           in: query
+          description: 'Include entries at or after this ISO 8601 datetime (e.g. `2026-07-01T00:00:00Z`).'
         - schema:
             type: string
             format: date-time
           required: false
           name: endDate
           in: query
+          description: 'Include entries at or before this ISO 8601 datetime (e.g. `2026-07-31T23:59:59Z`).'
         - schema:
             type: string
           required: false
           name: cursor
           in: query
+          description: >
+            Opaque keyset cursor returned as `nextCursor` in the previous page.
+            The cursor encodes the `(created_at, id)` of the last row on the
+            preceding page. Rows are ordered `DESC` on both columns, so the
+            next page begins strictly after that pair. Do not construct cursors
+            manually — always use the value returned by the API.
         - schema:
             type: integer
             minimum: 0
             exclusiveMinimum: true
           required: false
           name: limit
           in: query
+          description: Maximum number of entries to return per page (default 20).
       responses:
         '200':
           description: Paginated audit log