@xylex-group/athena 2.9.0 → 2.11.0

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `2.9.0`
+current version: `2.11.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
@@ -51,30 +51,38 @@ if (error) {
 }
 ```
 
-`createClient(url, key)` is the canonical SDK shape. The SDK treats `url` as the public unified Athena base URL and derives:
-
-- DB: `${url}/db`
-- Auth: `${url}/auth`
-- Storage: `${url}/storage`
+`createClient(url, key)` is the canonical SDK shape. The SDK treats `url` as the public unified Athena base URL and derives:
+
+- DB: `${url}/db`
+- Auth: `${url}/auth`
+- Chat: `${url}/chat`
+- Chat realtime: `${url}` converted to `ws:` / `wss:` plus `/chat/ws`
+- Storage: `${url}/storage`
 
 You can still override individual services when needed:
 
 ```ts
-const athena = createClient({
-  key: ATHENA_API_KEY,
-  db: { url: process.env.ATHENA_DB_URL },
-  auth: { url: process.env.ATHENA_AUTH_URL },
-  storage: { url: process.env.ATHENA_STORAGE_URL },
-});
-```
+const athena = createClient({
+  key: ATHENA_API_KEY,
+  db: { url: process.env.ATHENA_DB_URL },
+  auth: { url: process.env.ATHENA_AUTH_URL },
+  chat: {
+    url: process.env.ATHENA_CHAT_URL,
+    wsUrl: process.env.ATHENA_CHAT_WS_URL,
+  },
+  storage: { url: process.env.ATHENA_STORAGE_URL },
+});
+```
 
 Legacy top-level aliases are also supported:
 
 ```ts
 const athena = createClient({
-  key: ATHENA_API_KEY,
-  gatewayUrl: process.env.ATHENA_DB_URL,
-  authUrl: process.env.ATHENA_AUTH_URL,
+  key: ATHENA_API_KEY,
+  gatewayUrl: process.env.ATHENA_DB_URL,
+  authUrl: process.env.ATHENA_AUTH_URL,
+  chatUrl: process.env.ATHENA_CHAT_URL,
+  chatWsUrl: process.env.ATHENA_CHAT_WS_URL,
   storageUrl: process.env.ATHENA_STORAGE_URL,
 });
 ```
@@ -115,6 +123,42 @@ Use `withOptions(...)` only when you intentionally need to re-target the client
 
 If you already pass `client: "web-dashboard"`, the SDK sends `X-Athena-Client` for you. You do not need to duplicate that header manually.
 
+### Low-level request hatch
+
+If you need to hit a route the fluent SDK has not wrapped yet, use `client.request(...)`:
+
+```ts
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  auth: {
+    baseUrl: AUTH_BASE_URL,
+    credentials: "include",
+  },
+});
+
+const response = await athena.request<{
+  ok: boolean;
+}>({
+  service: "chat",
+  method: "POST",
+  path: "/rooms",
+  body: {
+    slug: "support",
+    name: "Support",
+  },
+});
+
+if (!response.ok) {
+  throw new Error(`chat route failed: ${response.status}`);
+}
+```
+
+Rules:
+
+- use `service: "db" | "auth" | "chat" | "storage"` plus `path` for configured SDK services
+- use `url` for absolute one-off targets
+- `query`, `headers`, `body`, `signal`, `credentials`, and `responseType` are supported
+- auth/session, API key, org/user context, and client headers are mirrored onto configured service calls automatically
+
 ### Next.js and React shortcuts
 
 If you are in a Next.js app, use the higher-level adapters instead of rebuilding request context by hand:
@@ -248,12 +292,12 @@ function WelcomeEmail(props: { name: string }) {
   );
 }
 
-await athena.auth.admin.email.template.create({
-  templateKey: "welcome",
-  subjectTemplate: "Welcome",
-  react: {
-    component: WelcomeEmail,
-    props: { name: "Ava" },
+await athena.auth.admin.email.template.create({
+  template_key: "welcome",
+  subject_template: "Welcome",
+  react: {
+    component: WelcomeEmail,
+    props: { name: "Ava" },
   },
 });
 ```
@@ -263,11 +307,11 @@ For reusable templates, use `defineAuthEmailTemplate(...)`:
 ```ts
 import { defineAuthEmailTemplate } from "@xylex-group/athena";
 
-const welcomeTemplate = defineAuthEmailTemplate({
-  component: WelcomeEmail,
-  templateKey: "welcome",
-  subjectTemplate: "Welcome",
-});
+const welcomeTemplate = defineAuthEmailTemplate({
+  component: WelcomeEmail,
+  templateKey: "welcome",
+  subjectTemplate: "Welcome",
+});
 
 await athena.auth.admin.email.template.create(
   welcomeTemplate.toTemplateCreate({
@@ -297,7 +341,47 @@ Install support packages in your app:
 pnpm add @react-email/components @react-email/render
 ```
 
-Auth responses follow the same envelope style: `{ ok, status, data, error, errorDetails, raw }`.
+Auth responses follow the same envelope style: `{ ok, status, data, error, errorDetails, raw }`.
+
+#### Chat module
+
+The root client now exposes `client.chat` for room, message, search, and realtime flows:
+
+```ts
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  chatWsUrl: process.env.ATHENA_CHAT_WS_URL,
+});
+
+const rooms = await athena.chat.room.list({ limit: 20 });
+const created = await athena.chat.room.create({
+  slug: "engineering",
+  name: "Engineering",
+});
+
+await athena.chat.room.message.send(created.data?.id ?? "room_1", {
+  body: "Hello team",
+});
+
+const socket = athena.chat.realtime.connect({
+  token: "chat_token",
+  onMessage(event) {
+    console.log(event);
+  },
+});
+
+socket.ping();
+socket.close();
+```
+
+Available chat surfaces:
+
+- `chat.room.list/create/get/update/archive`
+- `chat.room.readCursor.upTo`
+- `chat.room.member.list/add/remove`
+- `chat.room.message.list/send/update/delete`
+- `chat.message.reaction.add/remove`
+- `chat.message.search`
+- `chat.realtime.info/connect`
 
 #### Native auth bootstrap helpers