@xylex-group/athena 1.9.0 → 2.1.2

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `1.9.0`
+current version: `2.1.2`
 `@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
@@ -45,48 +45,45 @@ if (error) {
 
 ### 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 { createAuthClient } from "@xylex-group/athena";
-
-const auth = createAuthClient({
-  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 auth.signIn.email({
-  email: "demo@example.com",
-  password: "super-secret",
-  rememberMe: true,
-});
-
-const session = await auth.getSession();
-const sessions = await auth.listSessions();
-
-// clear one session
-await auth.revokeSession({ token: "session_token_here" });
-// or clear all sessions
-await auth.revokeSessions();
-
-await auth.signOut();
-
-// additional core flows
-await auth.forgetPassword({ email: "demo@example.com", redirectTo: "https://app/reset-password" });
-await auth.resetPassword({ newPassword: "new-secret", token: "reset_token" });
-await auth.verifyEmail({ token: "verify_token", callbackURL: "https://app/verified" });
-await auth.changePassword({ currentPassword: "old-secret", newPassword: "new-secret" });
-await auth.updateUser({ name: "Demo User" });
-
-// escape hatch for any endpoint on your Athena Auth instance
-await auth.request({
-  endpoint: "/ok",
-  query: { ping: "pong" },
-});
-```
-
-Auth responses follow the same envelope style: `{ ok, status, data, error, errorDetails, raw }`.
+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" });
+```
+
+Auth responses follow the same envelope style: `{ ok, status, data, error, errorDetails, raw }`.
 
 ### Typed schema registry (model-first)
 
@@ -209,24 +206,27 @@ 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
-
-```ts
-import { normalizeAthenaError } from "@xylex-group/athena";
-
-const result = await athena.from("users").insert({ id: 1 }).select();
-if (result.error) {
-  const err = normalizeAthenaError(result, {
-    table: "users",
-    operation: "insert",
-  });
-  if (err.kind === "unique_violation") {
-    // deterministic conflict handling
-  }
-}
-```
-
-Normalized errors expose stable `kind` values (`unique_violation`, `validation`, `auth`, `rate_limit`, `transient`, etc.) plus operation metadata.
+### Error normalization
+
+```ts
+import { createClient, normalizeAthenaError } from "@xylex-group/athena";
+
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  experimental: { enableErrorNormalization: true },
+});
+
+const result = await athena.from("users").insert({ id: 1 }).select();
+if (result.error) {
+  const err = normalizeAthenaError(result);
+  if (err.kind === "unique_violation") {
+    // deterministic conflict handling
+  }
+}
+```
+
+Normalized errors expose stable `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.
 
 ### Numeric coercion
 
@@ -257,13 +257,31 @@ const result = await withRetry(
 
 By default, retries target transient/rate-limit failures; use `shouldRetry` for custom policies.
 
-## Query builder
-
-### 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");