@xylex-group/athena 2.4.0 → 2.4.1

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `2.4.0`
+current version: `2.4.1`
 `@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 plus Athena-native React hooks for client-side use.
 
 ## Install
@@ -54,6 +54,31 @@ The existing string-based `.select(...)` chain remains fully supported for compa
 including alias/FK patterns like `from:sender_id(name)`.
 For the full AST model, route contract, error behavior, and Athena server implications,
 see [`docs/findmany-ast-and-server-contract.md`](docs/findmany-ast-and-server-contract.md).
+For method-by-method runtime AST/state/payload models across `select(...)`, mutations,
+`rpc(...)`, `query(...)`, and fluent builder filters, see
+[`docs/runtime-method-ast-models.md`](docs/runtime-method-ast-models.md).
+
+### Gateway auth-session forwarding
+
+If you need Athena server-side auth rollout to inspect auth context on normal query requests, the SDK now mirrors available auth state into gateway headers while still forwarding the original headers too.
+
+Current behavior:
+
+- `headers.Cookie` containing an Athena auth session cookie keeps `Cookie` and also adds `X-Athena-Auth-Session-Token`
+- `headers.Authorization: Bearer ...` keeps `Authorization` and also adds `X-Athena-Auth-Bearer-Token`
+- `createClient(..., { auth: { bearerToken } })` mirrors that token onto gateway/query requests as `X-Athena-Auth-Bearer-Token`
+
+Server-side cookie forwarding example:
+
+```ts
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  headers: {
+    Cookie: request.headers.get("cookie") ?? "",
+  },
+});
+```
+
+For the full contract, precedence rules, browser/server caveats, and rollout guidance, see [`docs/auth-session-forwarding.md`](docs/auth-session-forwarding.md).
 
 ### Auth client (Athena Auth server)
 
@@ -350,6 +375,22 @@ const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
 });
 ```
 
+### Read retries (experimental)
+
+```ts
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  experimental: {
+    retryReads: true,
+  },
+});
+```
+
+With `retryReads: true`, the SDK automatically retries retryable read failures for `select`, `findMany(...)`, and `query(...)`.
+
+- two additional attempts are applied internally
+- retry classification follows the SDK's normalized `retryable` signal
+- writes (`insert`, `upsert`, `update`, `delete`) are not retried by this flag
+
 ### findMany AST transport (experimental)
 
 ```ts
@@ -360,10 +401,13 @@ const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
 });
 ```
 
-With `findManyAst: true`, clean `findMany(...)` calls send the original object AST body to `/gateway/fetch` instead of compiling the select tree down to `columns` and `conditions` first.
+With `findManyAst: true`, clean `findMany(...)` calls can send an AST-style body to `/gateway/fetch` instead of compiling the select tree down to `columns` and `conditions` first.
 
 - this is opt-in and meant for gateways that explicitly support direct AST bodies
 - existing compiled `findMany(...)` transport remains the default
+- shorthand `where` filters are normalized to explicit operator objects before the AST body is sent
+- UUID-like equality filters that need the SDK's `::text` comparison still fall back to the legacy query/compiled path
+- nested relation select strings stay off the SQL query fallback path and continue through `/gateway/fetch`
 - chained builder filters or pagination state that the AST body cannot represent losslessly yet continue to use the legacy compiled path
 - trace output still includes synthesized SQL so diagnostics stay readable
 
@@ -384,12 +428,27 @@ Utilities that are intentionally not exported from the root package are availabl
 
 ```ts
 import {
+  asString,
+  asBoolean,
+  asBooleanOrNull,
+  asRecord,
+  asIdentifier,
+  firstString,
+  readTrimmedString,
+  asNumber,
+  asStringArray,
   slugify,
   trimTrailingSlashes,
   parseBooleanFlag,
   isLocalHostname,
   clearAuthCookies,
   proxyRequestHeaders,
+  sqlText,
+  escapeLikePatternValue,
+  quoteSqlStringLiteral,
+  sqlNullableText,
+  sqlJsonbLiteral,
+  sqlBigInt,
 } from "@xylex-group/athena/utils";
 ```
 
@@ -400,15 +459,27 @@ const slug = slugify("Customer Success / Q4 Report"); // customer-success-q4-rep
 const local = isLocalHostname("api.localhost"); // true
 const normalized = trimTrailingSlashes("https://example.com///"); // https://example.com
 const enabled = parseBooleanFlag(process.env.FEATURE_FLAG, false);
+const count = asNumber("42"); // 42
+const label = asString("  ready "); // ready
+const active = asBooleanOrNull("yes"); // true
+const tags = asStringArray([" alpha ", "", "beta"]); // ["alpha", "beta"]
+const likePattern = escapeLikePatternValue("%admin_"); // \%admin\_
 
 // Browser-only helper (safe no-op on server runtimes)
 clearAuthCookies();
 
 // Preserve forwarded headers when proxying auth requests
 const upstreamHeaders = proxyRequestHeaders(request);
+
+// Safely embed raw SQL values when using athena.query(...)
+const emailLiteral = sqlText("floris@example.com");
+const metadataLiteral = sqlJsonbLiteral({ role: "admin" });
+const actorIdLiteral = sqlBigInt(42);
+const exactLiteral = quoteSqlStringLiteral("Athena's SDK");
 ```
 
 `clearAuthCookies()` clears cookies matching Athena/Better Auth prefixes (`athena-auth`, `__Secure-athena-auth`, `better-auth`, `__Secure-better-auth`) and also attempts parent-domain cleanup for subdomain deployments.
+For SQL identifiers, keep using `identifier(...)`; `sqlText(...)`-style helpers are for literal values only.
 
 ### Retry helper