@xylex-group/athena 2.3.0 → 2.4.1

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `2.3.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
@@ -24,36 +24,61 @@ npm install react  # React >=17 required for the hook
 ```ts
 import { createClient } from "@xylex-group/athena";
 
-const athenaClient = createClient(ATHENA_URL, ATHENA_API_KEY, {
-  client: "CLIENT_NAME",
-  backend: { type: "athena" },
-});
-
-const { data, error } = await athenaClient.from("orchestral_sections").findMany({
-  select: {
-    name: true,
-    instruments: {
-      select: {
-        name: true,
-      },
-    },
-  },
-});
-
-if (error) {
-  console.error("gateway error", error);
-} else {
-  console.table(data);
-}
-```
-
-Example version baseline: SDK `@xylex-group/athena` `2.3.0`, Athena server `3.12.3` verified on 2026-06-04.
-
-`.findMany({ select, where, orderBy, limit })` is the clean canonical read surface.
-The existing string-based `.select(...)` chain remains fully supported for compatibility,
-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).
+const athenaClient = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  client: "CLIENT_NAME",
+  backend: { type: "athena" },
+});
+
+const { data, error } = await athenaClient.from("orchestral_sections").findMany({
+  select: {
+    name: true,
+    instruments: {
+      select: {
+        name: true,
+      },
+    },
+  },
+});
+
+if (error) {
+  console.error("gateway error", error);
+} else {
+  console.table(data);
+}
+```
+
+Example version baseline: SDK `@xylex-group/athena` `2.4.0`, Athena server `3.12.3` verified on 2026-06-04.
+
+`.findMany({ select, where, orderBy, limit })` is the clean canonical read surface.
+The existing string-based `.select(...)` chain remains fully supported for compatibility,
+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)
 
@@ -245,19 +270,19 @@ For prompt-ready documentation handoff text, see [`docs/generator-codex-handoff-
 - `athena-rs` for Rust backend throughput
 - `athena-js` for app/tooling layers that need TypeScript contracts and frontend-facing ergonomics
 
-Every query resolves to `{ data, error, errorDetails?, status, statusText?, count?, raw }`. `data` is `null` on error; `error` is `null` on success.
-
-Failed results now include a structured `error` object with the useful fields inline:
-
-- `message`
-- `code`
-- `details`
-- `hint`
-- `status`
-- `statusText`
-- normalized metadata such as `kind`, `table`, `operation`, and `retryable`
-
-`errorDetails` is still present as a compatibility alias for low-level gateway metadata (`gatewayCode`, `endpoint`, `method`, `requestId`, etc.).
+Every query resolves to `{ data, error, errorDetails?, status, statusText?, count?, raw }`. `data` is `null` on error; `error` is `null` on success.
+
+Failed results now include a structured `error` object with the useful fields inline:
+
+- `message`
+- `code`
+- `details`
+- `hint`
+- `status`
+- `statusText`
+- normalized metadata such as `kind`, `table`, `operation`, and `retryable`
+
+`errorDetails` is still present as a compatibility alias for low-level gateway metadata (`gatewayCode`, `endpoint`, `method`, `requestId`, etc.).
 
 ## Reliability helper APIs
 
@@ -296,26 +321,26 @@ requireAffected(inserted, { min: 1 }, { table: "users", operation: "insert" });
 
 `requireAffected` uses `result.count`; request it on writes with `{ count: "exact" }` when you need enforced postconditions.
 
-### Structured errors by default
-
-```ts
-import { createClient, normalizeAthenaError } from "@xylex-group/athena";
-
-const athena = createClient(ATHENA_URL, ATHENA_API_KEY);
-
-const { data, error, status, statusText } = await athena.from("users").insert({ id: 1 }).select();
-if (error) {
-  console.error(error);
-  console.error(error.hint ?? error.message, status, statusText);
-  if (error.kind === "unique_violation") {
-    // deterministic conflict handling
-  }
-}
-```
-
-`result.error` already carries normalized `kind` values (`unique_violation`, `validation`, `auth`, `rate_limit`, `transient`, etc.) plus operation metadata.
-
-`normalizeAthenaError(result)` still exists when you need the normalized envelope from an arbitrary thrown value or mixed unknown input.
+### Structured errors by default
+
+```ts
+import { createClient, normalizeAthenaError } from "@xylex-group/athena";
+
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY);
+
+const { data, error, status, statusText } = await athena.from("users").insert({ id: 1 }).select();
+if (error) {
+  console.error(error);
+  console.error(error.hint ?? error.message, status, statusText);
+  if (error.kind === "unique_violation") {
+    // deterministic conflict handling
+  }
+}
+```
+
+`result.error` already carries normalized `kind` values (`unique_violation`, `validation`, `auth`, `rate_limit`, `transient`, etc.) plus operation metadata.
+
+`normalizeAthenaError(result)` still exists when you need the normalized envelope from an arbitrary thrown value or mixed unknown input.
 
 ### Query tracing (experimental)
 
@@ -325,49 +350,68 @@ const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
 });
 ```
 
-With `traceQueries: true`, the SDK logs every runtime execution (`select`, `insert`, `upsert`, `update`, `delete`, `rpc`, `query`) and includes:
-
-- the gateway endpoint used
-- synthesized SQL (or raw SQL for `query(...)` and SQL fallback reads)
-- payload and call options
-- full outcome (`status`, `error`, `count`, `data`, `raw`)
-- callsite metadata (`filePath`, `fileName`, `line`, `column`)
-
-For deferred chains, Athena captures that callsite from the public SDK seam that declared or finalized the operation and reuses it for the eventual network execution. That keeps traces pinned to user code instead of drifting into SDK internals when async stack shapes differ between local runs and CI.
+With `traceQueries: true`, the SDK logs every runtime execution (`select`, `insert`, `upsert`, `update`, `delete`, `rpc`, `query`) and includes:
+
+- the gateway endpoint used
+- synthesized SQL (or raw SQL for `query(...)` and SQL fallback reads)
+- payload and call options
+- full outcome (`status`, `error`, `count`, `data`, `raw`)
+- callsite metadata (`filePath`, `fileName`, `line`, `column`)
+
+For deferred chains, Athena captures that callsite from the public SDK seam that declared or finalized the operation and reuses it for the eventual network execution. That keeps traces pinned to user code instead of drifting into SDK internals when async stack shapes differ between local runs and CI.
 
 Use a custom sink:
 
-```ts
-const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
-  experimental: {
-    traceQueries: {
-      logger(event) {
-        // Forward into your logger/observability sink
-        console.log(event.operation, event.endpoint, event.sql, event.callsite);
-      },
-    },
-  },
-});
-```
-
-### findMany AST transport (experimental)
-
-```ts
-const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
-  experimental: {
-    findManyAst: true,
-  },
-});
-```
-
-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.
-
-- this is opt-in and meant for gateways that explicitly support direct AST bodies
-- existing compiled `findMany(...)` transport remains the default
-- 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
-
-### Numeric coercion
+```ts
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  experimental: {
+    traceQueries: {
+      logger(event) {
+        // Forward into your logger/observability sink
+        console.log(event.operation, event.endpoint, event.sql, event.callsite);
+      },
+    },
+  },
+});
+```
+
+### 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
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  experimental: {
+    findManyAst: true,
+  },
+});
+```
+
+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
+
+### Numeric coercion
 
 ```ts
 import { coerceInt, assertInt } from "@xylex-group/athena";
@@ -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
 
@@ -583,15 +654,33 @@ const { data: user } = await athena
 
 ### Table schema targeting
 
-Use `schema` in table call options to qualify unqualified table names:
+Use `schema` either on `from(...)` itself or in table call options to qualify unqualified table names:
 
 ```ts
 const { data } = await athena
+  .from("users", { schema: "public" })
+  .select("id,email");
+
+const { data: sameTarget } = await athena
   .from("users")
   .select("id,email", { schema: "public" });
+
+const { data: crossSchema } = await athena
+  .from("chat_subscriptions", { schema: "private" })
+  .findMany({
+    select: {
+      user_id: true,
+      user: {
+        schema: "athena",
+        select: {
+          id: true,
+        },
+      },
+    },
+  });
 ```
 
-This resolves the table target to `public.users`.
+Both resolve the table target to `public.users`.
 
 ### RPC