Overview

Install @xylex-group/athena (v1.4.0), create a client, and jump into focused guides for reads, filters, pagination, sorting, and writes.

Athena is a database driver and API gateway SDK. Use these pages for how the builder maps to gateway payloads (limit, offset, sort_by, current_page, and so on).

Note: The Athena Web Explorer may still use internal TypeScript helpers under apps/web/app/lib/api.ts. For product and app integrations, prefer the @xylex-group/athena npm package documented here.

Install

npm install @xylex-group/athena
# or
pnpm add @xylex-group/athena
# or
yarn add @xylex-group/athena

Install React only if you use useAthenaGateway (React hook):

npm install react  # React >=17

Create a client

createClient returns a query builder bound to your Athena server URL and API key.

import { createClient } from "@xylex-group/athena";

const athena = createClient(
  "https://athena-db.com",
  process.env.ATHENA_API_KEY,
);

Optional defaults for every request:

const athena = createClient(
  "https://athena-db.com",
  process.env.ATHENA_API_KEY,
  {
    client: "your_client",
    headers: {
      "X-User-Id": currentUser.id ?? "",
    },
  },
);

Guides

Topic	What you will find
Queries and results	`.select()`, columns, `.single()` / `.maybeSingle()`, TypeScript row types
Filtering	`.eq`, `.ilike`, `.in`, `.or`, `.not`, array operators — maps to `conditions`
Pagination and limits	`.limit`, `.offset`, `.range`, page-based `.currentPage` / `.pageSize` / `.totalPages` — maps to gateway body fields
Sorting	`.order()` and `sort_by: { field, direction }` on fetch, update, and delete
Mutations	`.insert`, `.update`, `.upsert`, `.delete` and safety rules
RPC	`.rpc()` — `POST /gateway/rpc` vs `GET /rpc/{name}`
React hook	`useAthenaGateway` and gateway helpers
Errors and retries	`AthenaResult`, `errorDetails`, reliability helpers

Minimal read

const { data, error } = await athena
  .from("users")
  .select("id, name")
  .eq("active", true)
  .limit(25);

if (error) throw new Error(error);

Local validation (SDK repo)

When contributing to the npm package itself:

pnpm typecheck
pnpm check:all

Next steps

API reference — every export, option, and payload type