@xylex-group/athena 1.3.0 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `1.3.0`
+current version: `1.4.0`
 `@xylex-group/athena` is a database driver and API gateway SDK that lets you interact with SQL backends over HTTP through a fluent builder API. It ships a typed query builder for Node.js / server environments and a React hook for client-side use.
 
 ## Install
@@ -183,14 +183,73 @@ const { data } = await athena
 
 ### Pagination
 
+Two styles, pick whichever matches your UI / backend. Both live on the shared `FilterChain`, so they work before or after `.select()`.
+
 ```ts
-// explicit limit and offset
+// 1. offset / limit — contiguous windows
 const { data } = await athena.from("users").select().limit(25).offset(50);
 
-// range shorthand — equivalent to offset(from).limit(to - from + 1)
-const { data } = await athena.from("users").select().range(0, 24);
+// range shorthand: offset = from, limit = to - from + 1
+const { data: firstTwentyFive } = await athena.from("users").select().range(0, 24);
+
+// 2. page based — maps to current_page / page_size / total_pages
+const { data: page2 } = await athena
+  .from("orders")
+  .select("id, total")
+  .currentPage(2)
+  .pageSize(25);
+
+// .totalPages() is an optional hint some backends use in the response envelope
+const { data: hinted } = await athena
+  .from("orders")
+  .select("id, total")
+  .currentPage(1)
+  .pageSize(25)
+  .totalPages(10);
+```
+
+| Method | Body field |
+|--------|------------|
+| `.limit(n)` | `limit` |
+| `.offset(n)` | `offset` |
+| `.range(from, to)` | `offset` + `limit` |
+| `.currentPage(n)` | `current_page` |
+| `.pageSize(n)` | `page_size` |
+| `.totalPages(n)` | `total_pages` |
+
+### Ordering
+
+`.order(column, { ascending? })` is available on the table builder, select chain, update chain, and delete — before or after the operation terminator. It serializes to `sort_by: { field, direction }` on the gateway payload and defaults to ascending.
+
+```ts
+// descending + limit
+// SELECT * FROM rsf_messages WHERE room_id = $1 ORDER BY created_at DESC LIMIT 100
+const { data } = await athena
+  .from("rsf_messages")
+  .eq("room_id", roomId)
+  .select("*", { stripNulls: false })
+  .order("created_at", { ascending: false })
+  .limit(100);
+
+// ascending (default) + page-based pagination
+const { data: page } = await athena
+  .from("orders")
+  .select("id, total, created_at")
+  .order("created_at")
+  .currentPage(1)
+  .pageSize(25);
+
+// combine with .single() to grab the newest / oldest row
+const { data: latest } = await athena
+  .from("messages")
+  .eq("room_id", roomId)
+  .select("*")
+  .order("created_at", { ascending: false })
+  .single();
 ```
 
+Only the last `.order()` wins — the SDK does not support multi-column ordering on the table builder. Use `.rpc()` or `.query()` for that.
+
 ### Single row
 
 ```ts
@@ -417,6 +476,10 @@ const athena = createClient(
 
 Per-call headers are merged with the client-level headers, with per-call values winning on conflict.
 
+The SDK also sends a standard identification header on every request:
+
+- `X-Athena-Sdk: xylex-group/athena <version>`
+
 ## TypeScript
 
 The package is written in TypeScript and ships declaration files. Pass a row type to `.from()` for fully-typed builder methods and results:

package/dist/{errors-DHmpYG46.d.cts → errors-CB-eJQ7x.d.cts}

@@ -17,6 +17,11 @@ interface AthenaGatewayCondition {
     eq_column?: string;
     eq_value?: AthenaConditionValue | AthenaConditionArrayValue | string;
 }
+type AthenaSortDirection = 'ascending' | 'descending';
+interface AthenaSortBy {
+    field: string;
+    direction: AthenaSortDirection;
+}
 interface AthenaFetchPayload {
     view_name?: string;
     table_name?: string;
@@ -33,6 +38,7 @@ interface AthenaFetchPayload {
     aggregation_column?: string;
     aggregation_strategy?: 'cumulative_sum';
     aggregation_dedup?: boolean;
+    sort_by?: AthenaSortBy;
 }
 interface AthenaInsertPayload {
     table_name: string;
@@ -49,6 +55,10 @@ interface AthenaDeletePayload {
     resource_id?: string;
     columns?: string[] | string;
     conditions?: AthenaGatewayCondition[];
+    sort_by?: AthenaSortBy;
+    current_page?: number;
+    page_size?: number;
+    total_pages?: number;
 }
 interface AthenaUpdatePayload extends AthenaFetchPayload {
     set?: Record<string, unknown>;

package/dist/{errors-DHmpYG46.d.ts → errors-CB-eJQ7x.d.ts}

@@ -17,6 +17,11 @@ interface AthenaGatewayCondition {
     eq_column?: string;
     eq_value?: AthenaConditionValue | AthenaConditionArrayValue | string;
 }
+type AthenaSortDirection = 'ascending' | 'descending';
+interface AthenaSortBy {
+    field: string;
+    direction: AthenaSortDirection;
+}
 interface AthenaFetchPayload {
     view_name?: string;
     table_name?: string;
@@ -33,6 +38,7 @@ interface AthenaFetchPayload {
     aggregation_column?: string;
     aggregation_strategy?: 'cumulative_sum';
     aggregation_dedup?: boolean;
+    sort_by?: AthenaSortBy;
 }
 interface AthenaInsertPayload {
     table_name: string;
@@ -49,6 +55,10 @@ interface AthenaDeletePayload {
     resource_id?: string;
     columns?: string[] | string;
     conditions?: AthenaGatewayCondition[];
+    sort_by?: AthenaSortBy;
+    current_page?: number;
+    page_size?: number;
+    total_pages?: number;
 }
 interface AthenaUpdatePayload extends AthenaFetchPayload {
     set?: Record<string, unknown>;

package/dist/index.cjs

@@ -63,6 +63,10 @@ function isAthenaGatewayError(error) {
 // src/gateway/client.ts
 var DEFAULT_BASE_URL = "https://athena-db.com";
 var DEFAULT_CLIENT = "railway_direct";
+var FALLBACK_SDK_VERSION = "1.3.0";
+var SDK_NAME = "xylex-group/athena";
+var SDK_VERSION = typeof process !== "undefined" && process?.env?.npm_package_version ? process.env.npm_package_version : FALLBACK_SDK_VERSION;
+var SDK_HEADER_VALUE = `${SDK_NAME} ${SDK_VERSION}`;
 function parseResponseBody(rawText, contentType) {
   if (!rawText) {
     return { parsed: null, parseFailed: false };
@@ -201,7 +205,8 @@ function buildHeaders(config, options) {
   const finalApiKey = options?.apiKey ?? config.apiKey;
   const finalPublishEvent = options?.publishEvent ?? config.publishEvent;
   const headers = {
-    "Content-Type": "application/json"
+    "Content-Type": "application/json",
+    "X-Athena-Sdk": SDK_HEADER_VALUE
   };
   if (options?.userId ?? config.userId) {
     headers["X-User-Id"] = options?.userId ?? config.userId ?? "";
@@ -466,6 +471,25 @@ function createFilterMethods(state, addCondition, self) {
       state.offset = count;
       return self;
     },
+    currentPage(value) {
+      state.currentPage = value;
+      return self;
+    },
+    pageSize(value) {
+      state.pageSize = value;
+      return self;
+    },
+    totalPages(value) {
+      state.totalPages = value;
+      return self;
+    },
+    order(column, options) {
+      state.order = {
+        field: column,
+        direction: options?.ascending === false ? "descending" : "ascending"
+      };
+      return self;
+    },
     gt(column, value) {
       addCondition("gt", column, value);
       return self;
@@ -680,6 +704,10 @@ function createTableBuilder(tableName, client) {
       conditions: state.conditions.length ? [...state.conditions] : void 0,
       limit: state.limit,
       offset: state.offset,
+      current_page: state.currentPage,
+      page_size: state.pageSize,
+      total_pages: state.totalPages,
+      sort_by: state.order,
       strip_nulls: options?.stripNulls ?? true,
       count: options?.count,
       head: options?.head
@@ -715,6 +743,10 @@ function createTableBuilder(tableName, client) {
       state.conditions = [];
       state.limit = void 0;
       state.offset = void 0;
+      state.order = void 0;
+      state.currentPage = void 0;
+      state.pageSize = void 0;
+      state.totalPages = void 0;
       return builder;
     },
     select(columns = DEFAULT_COLUMNS, options) {
@@ -806,6 +838,10 @@ function createTableBuilder(tableName, client) {
           conditions: filters,
           strip_nulls: mergedOptions?.stripNulls ?? true
         };
+        if (state.order) payload.sort_by = state.order;
+        if (state.currentPage !== void 0) payload.current_page = state.currentPage;
+        if (state.pageSize !== void 0) payload.page_size = state.pageSize;
+        if (state.totalPages !== void 0) payload.total_pages = state.totalPages;
         if (columns) payload.columns = columns;
         const response = await client.updateGateway(payload, mergedOptions);
         return formatResult(response);
@@ -829,6 +865,10 @@ function createTableBuilder(tableName, client) {
           resource_id: resourceId,
           conditions: filters
         };
+        if (state.order) payload.sort_by = state.order;
+        if (state.currentPage !== void 0) payload.current_page = state.currentPage;
+        if (state.pageSize !== void 0) payload.page_size = state.pageSize;
+        if (state.totalPages !== void 0) payload.total_pages = state.totalPages;
         if (columns) payload.columns = columns;
         const response = await client.deleteGateway(payload, mergedOptions);
         return formatResult(response);