@xylex-group/athena 2.4.0 → 2.6.0

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `2.4.0`
+current version: `2.6.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 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)
 
@@ -163,6 +188,56 @@ pnpm add @react-email/components @react-email/render
 
 Auth responses follow the same envelope style: `{ ok, status, data, error, errorDetails, raw }`.
 
+#### Native auth bootstrap helpers
+
+If you want to remove `better-auth` from an app that is already aligned to
+Athena Auth session semantics, the SDK now ships a native bootstrap layer with
+an Athena-native `athenaAuth({...})` export that matches the Better Auth
+top-level contract:
+
+```ts
+import { athenaAuth } from "@xylex-group/athena";
+
+export function getAuth(env: {
+  DB: unknown;
+  ATHENA_AUTH_URL: string;
+  ATHENA_AUTH_SECRET: string;
+  GITHUB_CLIENT_ID: string;
+  GITHUB_CLIENT_SECRET: string;
+}) {
+  return athenaAuth({
+    baseURL: env.ATHENA_AUTH_URL,
+    secret: env.ATHENA_AUTH_SECRET,
+    database: env.DB,
+    socialProviders: {
+      github: {
+        clientId: env.GITHUB_CLIENT_ID,
+        clientSecret: env.GITHUB_CLIENT_SECRET,
+        scope: ["repo", "read:org", "user:email"],
+      },
+    },
+  });
+}
+```
+
+The returned auth object now carries the Better Auth-style top-level contract:
+
+- `handler(request)`
+- `api`
+- `options`
+- `$context`
+- `$ERROR_CODES`
+
+This native layer currently covers:
+
+- typed auth bootstrap config
+- session cookie set/clear helpers via the SDK cookie primitives
+
+It also supports dynamic `baseURL` host resolution plus static/dynamic
+`trustedOrigins` and `trustedProviders` on the native server bootstrap.
+
+For the full details and current scope, see [`docs/auth/server-bootstrap.mdx`](docs/auth/server-bootstrap.mdx).
+
 ### Typed schema registry (model-first)
 
 You can keep `createClient(...).from<T>(...)` as-is, or opt into a typed registry:
@@ -226,6 +301,7 @@ Generator supports:
 - Multiple schema syncs such as `public` plus `athena`, with schema-safe default output paths
 - Placeholder-driven output paths
 - Feature flags (`features.emitRegistry`, `features.emitRelations`)
+- Typed env-backed config fields via `generatorEnv(...)` for connection strings, schema lists, naming styles, flags, and placeholder maps
 
 For full generator configuration and troubleshooting, see [`docs/generator-config.md`](./docs/generator-config.md).
 For full CLI commands, help behavior, and troubleshooting, see [`docs/cli-command-reference.md`](./docs/cli-command-reference.md).
@@ -350,6 +426,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 +452,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 +479,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 +510,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