@xylex-group/athena 1.7.0 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `1.7.0`
+current version: `2.0.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
@@ -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)
 
@@ -390,11 +387,23 @@ const { data: user } = await athena
   .single();
 ```
 
-`maybeSingle` behaves identically — both return the first element of the result set.
-
-### 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
@@ -428,11 +437,12 @@ RPC options: `schema`, `count` (`"exact" | "planned" | "estimated"`), `head`, `g
 
 Pass options as the second argument to `.select()`:
 
-| Option       | Type                                  | Description                                  |
-| ------------ | ------------------------------------- | -------------------------------------------- |
-| `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