@xylex-group/athena 2.1.2 → 2.3.0

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `2.1.2`
+current version: `2.3.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
@@ -24,66 +24,144 @@ 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("characters").select(`
-    id,
-    name,
-    from:sender_id(name),
-    to:receiver_id(name)
-  `);
-
-if (error) {
-  console.error("gateway error", error);
-} else {
-  console.table(data);
-}
-```
-
-### Auth client (Athena Auth server)
-
-If your auth backend is now Athena Auth, you can keep core login/session flows in this SDK:
-
-```ts
-import { createClient } from "@xylex-group/athena";
-
-const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
+const athenaClient = createClient(ATHENA_URL, ATHENA_API_KEY, {
   client: "CLIENT_NAME",
-  auth: {
-    baseUrl: "http://localhost:3001/api/auth",
-    // optional: bearer token if you are not using cookie-based sessions
-    bearerToken: process.env.AUTH_BEARER_TOKEN,
-  },
+  backend: { type: "athena" },
 });
 
-const login = await athena.auth.signIn.email({
-  email: "demo@example.com",
-  password: "super-secret",
-  rememberMe: true,
+const { data, error } = await athenaClient.from("orchestral_sections").findMany({
+  select: {
+    name: true,
+    instruments: {
+      select: {
+        name: true,
+      },
+    },
+  },
 });
 
-const session = await athena.auth.getSession();
-const sessions = await athena.auth.session.list();
-
-// clear one session
-await athena.auth.session.revoke({ token: "session_token_here" });
-// or clear all sessions
-await athena.auth.session.revoke([{ token: "session_token_here" }, { token: "session_token_2" }]);
-
-await athena.auth.signOut();
-
-// additional core flows
-await athena.auth.forgetPassword({ email: "demo@example.com", redirectTo: "https://app/reset-password" });
-await athena.auth.resetPassword({ newPassword: "new-secret", token: "reset_token" });
-await athena.auth.verifyEmail({ token: "verify_token", callbackURL: "https://app/verified" });
-await athena.auth.changePassword({ currentPassword: "old-secret", newPassword: "new-secret" });
-await athena.auth.user.update({ name: "Demo User" });
+if (error) {
+  console.error("gateway error", error);
+} else {
+  console.table(data);
+}
 ```
 
-Auth responses follow the same envelope style: `{ ok, status, data, error, errorDetails, raw }`.
+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).
+
+### Auth client (Athena Auth server)
+
+If your auth backend is now Athena Auth, you can keep core login/session flows in this SDK:
+
+```ts
+import { createClient } from "@xylex-group/athena";
+
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  client: "CLIENT_NAME",
+  auth: {
+    baseUrl: "http://localhost:3001/api/auth",
+    // optional: bearer token if you are not using cookie-based sessions
+    bearerToken: process.env.AUTH_BEARER_TOKEN,
+  },
+});
+
+const login = await athena.auth.signIn.email({
+  email: "demo@example.com",
+  password: "super-secret",
+  rememberMe: true,
+});
+
+const session = await athena.auth.getSession();
+const sessions = await athena.auth.session.list();
+
+// clear one session
+await athena.auth.session.revoke({ token: "session_token_here" });
+// or clear all sessions
+await athena.auth.session.revoke([{ token: "session_token_here" }, { token: "session_token_2" }]);
+
+await athena.auth.signOut();
+
+// additional core flows
+await athena.auth.forgetPassword({ email: "demo@example.com", redirectTo: "https://app/reset-password" });
+await athena.auth.resetPassword({ newPassword: "new-secret", token: "reset_token" });
+await athena.auth.verifyEmail({ token: "verify_token", callbackURL: "https://app/verified" });
+await athena.auth.changePassword({ currentPassword: "old-secret", newPassword: "new-secret" });
+await athena.auth.user.update({ name: "Demo User" });
+```
+
+#### React Email templates for admin HTML routes
+
+If you use `@react-email/components`, you can pass component+props payloads directly on admin email/template routes:
+
+```ts
+import { Body, Html, Text } from "@react-email/components";
+
+function WelcomeEmail(props: { name: string }) {
+  return (
+    <Html lang="en">
+      <Body>
+        <Text>Welcome {props.name}</Text>
+      </Body>
+    </Html>
+  );
+}
+
+await athena.auth.admin.email.template.create({
+  templateKey: "welcome",
+  subjectTemplate: "Welcome",
+  react: {
+    component: WelcomeEmail,
+    props: { name: "Ava" },
+  },
+});
+```
+
+For reusable templates, use `defineAuthEmailTemplate(...)`:
+
+```ts
+import { defineAuthEmailTemplate } from "@xylex-group/athena";
+
+const welcomeTemplate = defineAuthEmailTemplate({
+  component: WelcomeEmail,
+  templateKey: "welcome",
+  subjectTemplate: "Welcome",
+});
+
+await athena.auth.admin.email.template.create(
+  welcomeTemplate.toTemplateCreate({
+    props: { name: "Ava" },
+  }),
+);
+```
+
+You can also observe render timing/errors:
+
+```ts
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  auth: {
+    baseUrl: AUTH_BASE_URL,
+    reactEmail: {
+      observe: (event) => {
+        console.log(JSON.stringify(event));
+      },
+    },
+  },
+});
+```
+
+Install support packages in your app:
+
+```bash
+pnpm add @react-email/components @react-email/render
+```
+
+Auth responses follow the same envelope style: `{ ok, status, data, error, errorDetails, raw }`.
 
 ### Typed schema registry (model-first)
 
@@ -125,6 +203,8 @@ await typed
 
 For full details, see [`docs/typed-schema-registry.md`](./docs/typed-schema-registry.md).
 
+For exhaustive method-by-method documentation with usage snippets (root client, runtime builders, auth bindings, react runtime, cookies, and utils), see [`docs/complete-method-reference.md`](./docs/complete-method-reference.md).
+
 ### Typed schema generator
 
 Schema generation is additive. Existing `createClient(...).from<T>(...)` usage remains valid while teams migrate to generated registry files.
@@ -165,9 +245,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, count?, raw }`. `data` is `null` on error; `error` is `null` on success.
-
-For richer handling, inspect `errorDetails` (`code`, `status`, `endpoint`, `method`, `requestId`, etc.) or use `AthenaGatewayError` / `isAthenaGatewayError` from the package exports.
+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
 
@@ -206,29 +296,78 @@ requireAffected(inserted, { min: 1 }, { table: "users", operation: "insert" });
 
 `requireAffected` uses `result.count`; request it on writes with `{ count: "exact" }` when you need enforced postconditions.
 
-### Error normalization
+### Structured errors by default
 
 ```ts
 import { createClient, normalizeAthenaError } from "@xylex-group/athena";
 
-const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
-  experimental: { enableErrorNormalization: true },
-});
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY);
 
-const result = await athena.from("users").insert({ id: 1 }).select();
-if (result.error) {
-  const err = normalizeAthenaError(result);
-  if (err.kind === "unique_violation") {
+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
   }
 }
 ```
 
-Normalized errors expose stable `kind` values (`unique_violation`, `validation`, `auth`, `rate_limit`, `transient`, etc.) plus operation metadata.
+`result.error` already carries normalized `kind` values (`unique_violation`, `validation`, `auth`, `rate_limit`, `transient`, etc.) plus operation metadata.
 
-`experimental.enableErrorNormalization` keeps the existing `AthenaResult<T>` shape intact and pre-attaches context-aware metadata so `normalizeAthenaError(result)` can resolve table/operation without extra per-call context objects.
+`normalizeAthenaError(result)` still exists when you need the normalized envelope from an arbitrary thrown value or mixed unknown input.
 
-### Numeric coercion
+### Query tracing (experimental)
+
+```ts
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  experimental: { traceQueries: true },
+});
+```
+
+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
 import { coerceInt, assertInt } from "@xylex-group/athena";
@@ -239,6 +378,38 @@ if (maybeCaseId == null) throw new Error("Invalid case id");
 const caseId = assertInt(req.query.case_id, "case_id", { min: 1 });
 ```
 
+### Utilities subpath
+
+Utilities that are intentionally not exported from the root package are available from `@xylex-group/athena/utils`.
+
+```ts
+import {
+  slugify,
+  trimTrailingSlashes,
+  parseBooleanFlag,
+  isLocalHostname,
+  clearAuthCookies,
+  proxyRequestHeaders,
+} from "@xylex-group/athena/utils";
+```
+
+Examples:
+
+```ts
+const slug = slugify("Customer Success / Q4 Report"); // customer-success-q4-report
+const local = isLocalHostname("api.localhost"); // true
+const normalized = trimTrailingSlashes("https://example.com///"); // https://example.com
+const enabled = parseBooleanFlag(process.env.FEATURE_FLAG, false);
+
+// Browser-only helper (safe no-op on server runtimes)
+clearAuthCookies();
+
+// Preserve forwarded headers when proxying auth requests
+const upstreamHeaders = proxyRequestHeaders(request);
+```
+
+`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.
+
 ### Retry helper
 
 ```ts
@@ -257,31 +428,31 @@ const result = await withRetry(
 
 By default, retries target transient/rate-limit failures; use `shouldRetry` for custom policies.
 
-## Query builder
-
-### DB module namespace
-
-`createClient()` keeps root methods (`from`, `rpc`, `query`) and now also exposes `db` as an additive namespace.
-
-```ts
-const athena = createClient(ATHENA_URL, ATHENA_API_KEY);
-
-await athena.db.from("users").select("id,name").eq("active", true).limit(20);
-
-await athena.db.select("users", "id,name").eq("id", 1).single();
-
-await athena.db.insert("users", { id: 1, name: "Alice" }).select("id");
-await athena.db.update("users", { name: "Updated" }).eq("id", 1).select("id,name");
-await athena.db.delete("users", { resourceId: "r-1" }).select("id");
-```
-
-`db` mirrors the existing query builder semantics while providing a module seam for future database-surface expansion.
-
-### Reading rows
-
-```ts
-// select all columns
-const { data } = await athena.from("users").select();
+## Query builder
+
+### DB module namespace
+
+`createClient()` keeps root methods (`from`, `rpc`, `query`) and now also exposes `db` as an additive namespace.
+
+```ts
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY);
+
+await athena.db.from("users").select("id,name").eq("active", true).limit(20);
+
+await athena.db.select("users", "id,name").eq("id", 1).single();
+
+await athena.db.insert("users", { id: 1, name: "Alice" }).select("id");
+await athena.db.update("users", { name: "Updated" }).eq("id", 1).select("id,name");
+await athena.db.delete("users", { resourceId: "r-1" }).select("id");
+```
+
+`db` mirrors the existing query builder semantics while providing a module seam for future database-surface expansion.
+
+### Reading rows
+
+```ts
+// select all columns
+const { data } = await athena.from("users").select();
 
 // select specific columns
 const { data } = await athena.from("users").select("id, name, email");
@@ -408,23 +579,23 @@ const { data: user } = await athena
   .single();
 ```
 
-`maybeSingle` behaves identically — both return the first element of the result set.
-
-### Table schema targeting
-
-Use `schema` in table call options to qualify unqualified table names:
-
-```ts
-const { data } = await athena
-  .from("users")
-  .select("id,email", { schema: "public" });
-```
-
-This resolves the table target to `public.users`.
-
-### RPC
-
-Use `athena.rpc(...)` for Postgres function calls. By default it calls `POST /gateway/rpc`, and with `{ get: true }` it uses the compatibility route `GET /rpc/{function_name}`.
+`maybeSingle` behaves identically — both return the first element of the result set.
+
+### Table schema targeting
+
+Use `schema` in table call options to qualify unqualified table names:
+
+```ts
+const { data } = await athena
+  .from("users")
+  .select("id,email", { schema: "public" });
+```
+
+This resolves the table target to `public.users`.
+
+### RPC
+
+Use `athena.rpc(...)` for Postgres function calls. By default it calls `POST /gateway/rpc`, and with `{ get: true }` it uses the compatibility route `GET /rpc/{function_name}`.
 
 ```ts
 const { data, count } = await athena
@@ -458,12 +629,12 @@ RPC options: `schema`, `count` (`"exact" | "planned" | "estimated"`), `head`, `g
 
 Pass options as the second argument to `.select()`:
 
-| Option       | Type                                  | Description                                  |
-| ------------ | ------------------------------------- | -------------------------------------------- |
-| `schema`     | `string`                              | qualify unqualified table names for table calls |
-| `count`      | `"exact" \| "planned" \| "estimated"` | request a row count alongside the data       |
-| `head`       | `boolean`                             | return response headers only (no rows)       |
-| `stripNulls` | `boolean`                             | strip null values from rows (default `true`) |
+| Option       | Type                                  | Description                                  |
+| ------------ | ------------------------------------- | -------------------------------------------- |
+| `schema`     | `string`                              | qualify unqualified table names for table calls |
+| `count`      | `"exact" \| "planned" \| "estimated"` | request a row count alongside the data       |
+| `head`       | `boolean`                             | return response headers only (no rows)       |
+| `stripNulls` | `boolean`                             | strip null values from rows (default `true`) |
 
 ```ts
 const { data } = await athena