Athena JS

https://github.com/xylex-group/athena-js
Admin
Type-safe TypeScript infrastructure SDK for data, auth, authorization, migrations, organizations,...
Tokens:937,457
Snippets:4,320
Trust Score:7.5
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Setup commands: pnpm build, install

Source: https://github.com/xylex-group/athena-js/blob/main/test-sdk/README.md

Run from the repository root to build the package and install dependencies for the test SDK.

```bash
pnpm build
cd test-sdk
pnpm install
```

--------------------------------

### Quick start (edge-only): createClient with D1 and R2

Source: https://github.com/xylex-group/athena-js/blob/main/docs/cloudflare-edge-local.md

Edge-only setup using createClient with D1 binding and optional R2 storage and auth. The configuration conditionally includes storage and auth based on environment variables. The example runs a SQL query and returns the result or an error response.

```TypeScript
import { createClient } from '@xylex-group/athena'

export interface Env {
  DB: D1Database
  FILES?: R2Bucket
  ATHENA_AUTH_URL?: string
  ATHENA_API_KEY?: string
}

export default {
  async fetch(_request: Request, env: Env): Promise<Response> {
    const athena = createClient({
      db: { d1: env.DB },
      ...(env.FILES ? { storage: { r2: env.FILES, prefix: 'app/' } } : {}),
      ...(env.ATHENA_AUTH_URL
        ? { auth: { url: env.ATHENA_AUTH_URL }, key: env.ATHENA_API_KEY }
        : {}),
    })

    const { data, error } = await athena.admin.query<Array<{ ok: number }>>({
      expectedShape: "rows",
      operation: "select",
      sql: "SELECT 1 AS ok",
    })
    if (error) {
      return Response.json({ error: error.message }, { status: 500 })
    }
    return Response.json({ data, capabilities: athena.capabilities })
  },
}
```

--------------------------------

### Development setup commands

Source: https://github.com/xylex-group/athena-js/blob/main/CONTRIBUTING.md

Clone the repository, navigate to the athena-js package, install dependencies, and build the project.

```bash
git clone https://github.com/xylex-group/athena.git
cd athena/packages/athena-js

pnpm install
pnpm build
```

--------------------------------

### Auth API Key Methods Example

Source: https://github.com/xylex-group/athena-js/blob/main/docs/auth/api-key.mdx

Shows how to use the auth.apiKey methods to create, get, update, delete, list, verify, and delete all expired API keys. The example imports a client from "./auth-client" and calls each method with the required parameters.

```ts
import { client } from "./auth-client"

await client.auth.apiKey.create({
  name: "mobile-client-key",
  expiresIn: "3600",
  remaining: "1000",
})

await client.auth.apiKey.get({
  query: { id: "api_key_id" },
})

await client.auth.apiKey.update({
  keyId: "api_key_id",
  name: "mobile-client-key-updated",
  expiresIn: "3600",
  permissions: "{}",
})

await client.auth.apiKey.delete({ keyId: "api_key_id" })

await client.auth.apiKey.list()

await client.auth.apiKey.verify({
  key: "prefix.secret",
})

await client.auth.apiKey.deleteAllExpired()
```

--------------------------------

### Run the test SDK server

Source: https://github.com/xylex-group/athena-js/blob/main/test-sdk/README.md

Start the Express server. Use pnpm start for production or pnpm dev for development mode.

```bash
pnpm start
# or
pnpm dev
```

--------------------------------

### Quick server setup with createExampleServerSessionResolver

Source: https://github.com/xylex-group/athena-js/blob/main/examples/session/README.md

Quick server setup for RSC or route handlers. Creates a server session resolver and uses it to require a session, returning the user data.

```ts
import { createClient } from '@xylex-group/athena'
import { createExampleServerSessionResolver } from './server-session'

const athena = createClient({ url, key, auth: { url } })
const session = createExampleServerSessionResolver(athena)

export async function loadAccount() {
  const data = await session.require()
  return data.user
}
```

--------------------------------

### ERR_MODULE_NOT_FOUND example

Source: https://github.com/xylex-group/athena-js/blob/main/docs/cli-command-reference.md

Example error pattern for `ERR_MODULE_NOT_FOUND` when the global package install is missing generated CLI bundle files. Common with old/broken published versions or stale shims. Fix by reinstalling globally with pnpm or running from project-local dependency with `pnpm exec`.

```text
Cannot find module .../@xylex-group/athena/dist/cli/index.js
```

--------------------------------

### Build, install, and check the Expo fixture

Source: https://github.com/xylex-group/athena-js/blob/main/test/fixtures/expo/README.md

Run these commands in order to build the package, install fixture dependencies, and typecheck the Expo fixture.

```bash
pnpm --dir packages/athena-js build
pnpm --dir packages/athena-js/test/fixtures/expo install
pnpm --dir packages/athena-js/test/fixtures/expo check
```

--------------------------------

### createClient usage examples

Source: https://github.com/xylex-group/athena-js/blob/main/docs/cloudflare-edge-local.md

Shows various configurations for createClient: gateway HTTP, edge bindings, top-level aliases, hybrid, and auto-switching. Includes usage examples for querying and storage operations.

```TypeScript
import { createClient } from '@xylex-group/athena'

// Gateway HTTP
const gateway = createClient({ url: env.ATHENA_URL, key: env.ATHENA_API_KEY })

// Edge bindings (nested — preferred in shared code)
const edge = createClient({
  db: { d1: env.DB },
  storage: { r2: env.FILES, prefix: 'app/' },
})

// Top-level aliases (Worker DX; same as nested)
const edgeAlias = createClient({
  d1: env.DB,
  r2: env.FILES,
  storagePrefix: 'app/',
})

// Hybrid: local D1 + remote auth/billing
const hybrid = createClient({
  db: { d1: env.DB },
  url: env.ATHENA_URL,
  key: env.ATHENA_API_KEY,
})

// Switch when BOTH binding and URL exist
const switched = createClient({
  d1: env.DB,
  r2: env.FILES,
  url: env.ATHENA_URL,
  key: env.ATHENA_API_KEY,
  mode: 'auto', // edge | gateway | auto (env ATHENA_EXECUTION_MODE)
  prefer: 'edge', // when both: edge | gateway (env ATHENA_EXECUTION_PREFER)
})

await edge.from('users').select('id,email')
await edge.storage.putObject({ key: 'a.txt', body: 'hello' })
```

--------------------------------

### Install and set up @xylex-group/athena with Cloudflare Workers

Source: https://github.com/xylex-group/athena-js/blob/main/examples/cloudflare/README.md

Commands to install the package, copy app.ts and wrangler.example.jsonc, create a D1 database, set the database_id, execute the schema, and run the dev server.

```bash
pnpm add @xylex-group/athena
# copy app.ts + wrangler.example.jsonc into your Worker
npx wrangler d1 create my-edge-db
# set database_id
npx wrangler d1 execute my-edge-db --local --file=./schema/users.sql
npx wrangler dev
```

--------------------------------

### OpenAPI documented success example

Source: https://github.com/xylex-group/athena-js/blob/main/docs/findmany-ast-and-server-contract.md

Shows the OpenAPI-documented success example for `POST /gateway/fetch` and `POST /gateway/query`, which currently uses `data.rows` and `data.row_count`.

```json
{
  "status": "success",
  "message": "Fetched 25 rows",
  "data": {
    "rows": [],
    "row_count": 25
  }
}
```

--------------------------------

### athena-js init usage examples

Source: https://github.com/xylex-group/athena-js/blob/main/docs/cli-command-reference.md

Examples of using athena-js init: bootstrap a config from environment variables, explicitly use the gateway template with live schema auto-fill, and preview the planned action without writing.

```bash
# Bootstrap a committed config from env
athena-js init

# Explicit gateway template + live schema auto-fill
ATHENA_URL=https://athena.example.com ATHENA_API_KEY=secret \
  athena-js init --mode gateway

# Preview only
athena-js init --dry-run
```

--------------------------------

### Install @xylex-group/athena with pnpm

Source: https://github.com/xylex-group/athena-js/blob/main/README.md

Installs the Athena JavaScript SDK package.

```bash
pnpm add @xylex-group/athena

```

--------------------------------

### Quick client setup with useSession

Source: https://github.com/xylex-group/athena-js/blob/main/examples/session/README.md

Quick client setup for a Next.js page using the useSession hook. Creates an Athena client with environment-based configuration and renders a SessionStatusPanel component.

```tsx
import { createClient } from '@xylex-group/athena'
import { SessionStatusPanel } from './use-session-panel'

const athena = createClient({
  url: process.env.NEXT_PUBLIC_ATHENA_URL!,
  key: process.env.NEXT_PUBLIC_ATHENA_API_KEY,
  auth: { url: process.env.NEXT_PUBLIC_ATHENA_AUTH_URL ?? '/api/auth' },
})

export default function AccountPage() {
  return <SessionStatusPanel authClient={athena} />
}
```

--------------------------------

### Install @xylex-group/athena 3.4.0

Source: https://github.com/xylex-group/athena-js/blob/main/docs/releases/3.4.0.md

Install the 3.4.0 release of the Athena JS client with pnpm.

```bash
pnpm add @xylex-group/athena@3.4.0
```

--------------------------------

### Install @xylex-group/athena@3.2.0

Source: https://github.com/xylex-group/athena-js/blob/main/docs/releases/3.2.0.md

Install the 3.2.0 release of the Athena package using pnpm.

```bash
pnpm add @xylex-group/athena@3.2.0
```

--------------------------------

### Auth Sign-In and Sign-Up Examples

Source: https://github.com/xylex-group/athena-js/blob/main/docs/auth/sign-in-up.mdx

Shows how to call the auth endpoints for social, email, and username sign-in, plus email sign-up, using the client from "./auth-client". Each call is awaited and passes the required parameters such as provider, callbackURL, email, password, rememberMe, and name.

```ts
import { client } from "./auth-client"

await client.auth.signIn.social({
  provider: "google",
  callbackURL: "https://app.example.com/auth/callback",
})

await client.auth.signIn.email({
  email: "user@example.com",
  password: "password",
  rememberMe: true,
})

await client.auth.signIn.username({
  username: "user1",
  password: "password",
  rememberMe: true,
})

await client.auth.signUp.email({
  name: "New User",
  email: "new-user@example.com",
  password: "password",
  callbackURL: "https://app.example.com/onboarding",
})
```

--------------------------------

### Probe endpoint with GET request

Source: https://github.com/xylex-group/athena-js/blob/main/_autodocs/api-reference/request.md

Example of probing an endpoint and reading the response envelope.

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

const athena = createClient({ url, key });

const response = await athena.request({
  path: "/gateway/health",
  method: "GET",
  service: "db",
});

console.log(response.status, response.ok, response.data);
```

--------------------------------

### Cancel, accept, get, reject, and list organization invitations

Source: https://github.com/xylex-group/athena-js/blob/main/docs/auth/organization-invitations.mdx

Use these methods to manage organization invitations. The example shows how to cancel, accept, get, reject, and list invitations using the client. The get and list methods use a query parameter, while the others use an invitationId.

```TypeScript
import { client } from "./auth-client"

await client.auth.organization.invitation.cancel({
  invitationId: "inv_1",
})

await client.auth.organization.invitation.accept({
  invitationId: "inv_1",
})

await client.auth.organization.invitation.get({
  query: { id: "inv_1" },
})

await client.auth.organization.invitation.reject({
  invitationId: "inv_1",
})

await client.auth.organization.invitation.list({
  query: { organizationId: "org_1" },
})
```

--------------------------------

### Basic Gateway Client with createClient

Source: https://github.com/xylex-group/athena-js/blob/main/_autodocs/api-reference/create-client.md

Basic gateway client example from `examples/node/create-client.ts`. Creates a client with environment variables and performs a simple query with limit and select.

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

const athena = createClient({
  client: process.env.ATHENA_CLIENT ?? "my-app",
  key: process.env.ATHENA_API_KEY!,
  url: process.env.ATHENA_URL!,
});

const users = await athena.from("users").limit(5).select("id,email");
console.log(users.data, users.error?.message);
```

--------------------------------

### Development setup and test commands

Source: https://github.com/xylex-group/athena-js/blob/main/README.md

Builds the package and runs the finality test suite.

```bash
pnpm install
pnpm build
pnpm test:finality

```

--------------------------------

### Auth config reactEmail example

Source: https://github.com/xylex-group/athena-js/blob/main/docs/auth/react-email-api.mdx

Configures auth.reactEmail defaults and observability once on the client. The observe callback receives events with phases render:start, render:success, and render:error.

```ts
const client = createClient({
  url: ATHENA_URL,
  key: ATHENA_API_KEY,
  auth: {
    url: AUTH_BASE_URL,
    reactEmail: {
      defaults: {
        includePlainText: true,
      },
      observe: event => {
        console.log(JSON.stringify(event))
      },
    },
  },
})
```

--------------------------------

### Multi-statement rejection and SQL classification

Source: https://github.com/xylex-group/athena-js/blob/main/_autodocs/api-reference/admin-query.md

Example showing how to detect multiple SQL statements and classify the raw SQL operation. It uses sqlLooksLikeMultipleStatements to check for multi-statement SQL and classifyRawSqlOperation to get the operation type. The comment notes that the default admin.query path rejects multi-statement SQL unless allowMultiStatement is set.

```ts
import { createAdminQuery, classifyRawSqlOperation, sqlLooksLikeMultipleStatements } from "@xylex-group/athena";

if (sqlLooksLikeMultipleStatements("select 1; select 2")) {
  // the default admin.query path rejects this unless allowMultiStatement
}
const operation = classifyRawSqlOperation("INSERT INTO users (email) VALUES ($1)");
console.log(operation); // "insert"
```

--------------------------------

### Social and Account SDK Methods

Source: https://github.com/xylex-group/athena-js/blob/main/docs/auth/social-account.mdx

Demonstrates the public SDK methods for social and account management: link, list, unlink, deleteUser.callback, refreshToken, getAccessToken, health, ok, and error. Each method corresponds to a specific endpoint (e.g., POST /link-social, GET /list-accounts). The example uses a pre-configured client from "./auth-client".

```ts
import { client } from "./auth-client"

await client.auth.social.link({
  provider: "google",
  callbackURL: "https://app.example.com/auth/callback",
})

await client.auth.account.list()

await client.auth.account.unlink({
  providerId: "google",
  accountId: "acc_123",
})

await client.auth.deleteUser.callback({
  token: "delete_callback_token",
  callbackURL: "https://app.example.com/delete-callback",
})

await client.auth.refreshToken({
  providerId: "google",
  accountId: "acc_123",
  userId: "usr_123",
})

await client.auth.getAccessToken({
  providerId: "google",
  accountId: "acc_123",
  userId: "usr_123",
})

await client.auth.health()
await client.auth.ok()
await client.auth.error()
```

--------------------------------

### Named mapper function examples (mapAToB)

Source: https://github.com/xylex-group/athena-js/blob/main/docs/adr/0021-layered-contract-policy.md

Three example mapper function calls following the mapAToB convention. Commented lines are not executable code; they are illustrative examples.

```ts
mapStorageFileRowToManagedFileView(row)
mapNormalizedAthenaErrorToErrorResponse(error)
mapLimitPlusOneToPage(items, limit)

```

--------------------------------

### Migrate command examples

Source: https://github.com/xylex-group/athena-js/blob/main/docs/cli-command-reference.md

Shows the various migrate subcommands and options, including applying migrations, dry-run, status, plan, check, graph, explain, drift, reconcile, auth sync, and configuration options.

```bash
athena-js migrate
athena-js migrate --dry-run
athena-js migrate status
athena-js migrate plan
athena-js migrate check --strict
athena-js migrate graph
athena-js migrate explain 0007
athena-js migrate drift
athena-js migrate reconcile
athena-js migrate reconcile --apply --yes
athena-js migrate --config ./athena.config.ts
athena-js migrate auth sync
athena-js migrate --help
```

--------------------------------

### Middleware example using hasAuthSessionCookie

Source: https://github.com/xylex-group/athena-js/blob/main/docs/auth-cookies.md

Example middleware that redirects to /sign-in when no session cookie is present.

```typescript
import { hasAuthSessionCookie } from "@xylex-group/athena/cookies"

export function middleware(request: Request) {
  if (!hasAuthSessionCookie(request.headers.get("cookie"))) {
    return Response.redirect(new URL("/sign-in", request.url))
  }
  // continue
}
```

--------------------------------

### Create browser client with topology.discover: 'next'

Source: https://github.com/xylex-group/athena-js/blob/main/docs/next-js.md

Creates a browser client for the Local Runtime using topology discovery. Requires a Next.js Client Component ('use client') and imports from '@xylex-group/athena/next/client'. No url, key, auth.routing, or DATABASE_URL needed.

```typescript
// src/lib/athena/browser.ts
'use client'

import { createClient } from '@xylex-group/athena/next/client'

export const athena = createClient({
  topology: { discover: 'next' },
})
```

--------------------------------

### Configure storage with direct upload

Source: https://github.com/xylex-group/athena-js/blob/main/docs/client-v3-consolidation-report.md

Example of moving storage-specific tuning out of the experimental gate. Shows storage URL and direct upload bucket configuration.

```ts
createClient({
  storage: {
    url: 'https://athena.example.com/storage',
    directUpload: {
      bucket: 'files',
    },
  },
})
```

--------------------------------

### Client setup with createClient

Source: https://github.com/xylex-group/athena-js/blob/main/docs/athena-client-bindings.md

Creates an Athena client with a gateway API key and auth URL. The auth client surface is exposed via client.auth.*.

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

const client = createClient({
  key: "gateway_api_key",
  auth: { url: "http://localhost:3001/api/auth" },
})
```

--------------------------------

### Create Athena client and render DemoProductsPanel

Source: https://github.com/xylex-group/athena-js/blob/main/test-sdk/examples/react-hooks/README.md

Create an Athena client using environment variables and pass it to the DemoProductsPanel component. Requires NEXT_PUBLIC_ATHENA_URL and NEXT_PUBLIC_ATHENA_API_KEY; NEXT_PUBLIC_ATHENA_CLIENT is optional.

```tsx
import { createExampleAthenaClient } from './shared'

const athena = createExampleAthenaClient({
  athenaUrl: process.env.NEXT_PUBLIC_ATHENA_URL!,
  apiKey: process.env.NEXT_PUBLIC_ATHENA_API_KEY!,
  client: process.env.NEXT_PUBLIC_ATHENA_CLIENT,
})
```

```tsx
import { DemoProductsPanel } from './products-panel'

export default function Page() {
  return <DemoProductsPanel athena={athena} />
}
```

--------------------------------

### Next.js page example

Source: https://github.com/xylex-group/athena-js/blob/main/docs/auth-routes.md

Example of a Next.js page that resolves the auth view from the URL segment and redirects authenticated users to the app home.

```typescript
// app/auth/[segment]/page.tsx
import {
  resolveAuthViewFromSegment,
  shouldRedirectAuthenticatedAuthView,
  AUTH_ROUTES,
} from "@xylex-group/athena/utils"
import { hasAuthSessionCookie } from "@xylex-group/athena/cookies"
import { redirect, notFound } from "next/navigation"
import { cookies } from "next/headers"

export default async function AuthSegmentPage({
  params,
}: {
  params: Promise<{ segment?: string }>
}) {
  const { segment } = await params
  const view = resolveAuthViewFromSegment(segment)
  if (!view) notFound()

  const cookieHeader = (await cookies()).toString()
  if (
    hasAuthSessionCookie(cookieHeader) &&
    shouldRedirectAuthenticatedAuthView(view)
  ) {
    redirect(AUTH_ROUTES.appHome)
  }

  // render Auth UI for `view`
}
```

--------------------------------

### athena-js init command options

Source: https://github.com/xylex-group/athena-js/blob/main/docs/cli-command-reference.md

Shows the init command with its available options: --mode, --force, --dry-run, --no-discover-schemas, --config, and --help. Use these to bootstrap or update the Athena configuration.

```bash
athena-js init
athena-js init --mode direct
athena-js init --mode gateway
athena-js init --force
athena-js init --dry-run
athena-js init --no-discover-schemas
athena-js init --config ./athena.config.ts
athena-js init --help
```

--------------------------------

### Install athena-js globally

Source: https://github.com/xylex-group/athena-js/blob/main/docs/cli-command-reference.md

Installs the athena-js CLI globally via pnpm. Use this when you need a global binary instead of local execution.

```bash
pnpm add -g @xylex-group/athena
```

--------------------------------

### Switch output format and preset via env

Source: https://github.com/xylex-group/athena-js/blob/main/docs/generator-quickstart.md

Environment variables to switch the output format and preset.

```bash
ATHENA_GENERATOR_OUTPUT_FORMAT=table-builder
ATHENA_GENERATOR_OUTPUT_PRESET=athena-direct
```

--------------------------------

### Install @react-email/components and @react-email/render

Source: https://github.com/xylex-group/athena-js/blob/main/docs/auth/react-email.mdx

Install the required React Email packages to use React Email elements or components with athena-js admin email/template routes.

```bash
pnpm add @react-email/components @react-email/render
```

--------------------------------

### Next server migration: createAthenaServerClient() to createClient() with context

Source: https://github.com/xylex-group/athena-js/blob/main/docs/client-v3-consolidation-report.md

Shows the before and after for replacing createAthenaServerClient() with a long-lived createClient() that uses a per-request context resolver.

```ts
// Before
const athena = await createAthenaServerClient({
  url,
  key,
})

// After: long-lived client with per-request context
const athena = createClient({
  url,
  key,
  context: resolveNextRequestContext,
})
```

--------------------------------

### Run end-to-end tests for generator examples

Source: https://github.com/xylex-group/athena-js/blob/main/test-sdk/examples/generator/README.md

Executes the end-to-end test suite from the test-sdk directory, which validates the generator full utilization and feature matrix examples.

```bash
pnpm test:e2e
```

--------------------------------

### Run anti-stale session tests

Source: https://github.com/xylex-group/athena-js/blob/main/examples/session/README.md

Command to run the anti-stale tests for the session examples. These tests import the example modules to catch renames or export drift in CI.

```bash
pnpm test -- test/examples-session.test.ts
```

--------------------------------

### Pack and install @xylex-group/athena tarball

Source: https://github.com/xylex-group/athena-js/blob/main/test/fixtures/next-embedded/README.md

Pack the @xylex-group/athena tarball into .tmp/packages and install it into this fixture directory. Required before running test:finality; do not import ../../src.

```text
pnpm pack --pack-destination .tmp/packages
# install .tmp/packages/*.tgz into this directory
```

--------------------------------

### Athena-js migrate help commands

Source: https://github.com/xylex-group/athena-js/blob/main/docs/migrations.md

Show help for the main CLI and specific migrate subcommands.

```bash
athena-js --help
athena-js migrate --help
athena-js migrate status --help
```

--------------------------------

### GET / live response subset

Source: https://github.com/xylex-group/athena-js/blob/main/docs/findmany-ast-and-server-contract.md

Observed response subset from GET / on 2026-06-04. Shows the server version and the available POST routes. Useful as a live version probe.

```json
{
  "message": "athena is online",
  "athena_api": "online",
  "version": "3.12.3",
  "routes": [
    {
      "methods": ["POST"],
      "path": "/gateway/fetch"
    },
    {
      "methods": ["POST"],
      "path": "/gateway/query"
    }
  ]
}
```

--------------------------------

### Set direct-upstream env vars in next-heroui-example

Source: https://github.com/xylex-group/athena-js/blob/main/docs/auth-routing-proxy-and-direct-upstream.md

Environment variables for the next-heroui-example to enable direct-upstream mode and set the upstream URL. Both prefixed and non-prefixed variants are shown.

```bash
ATHENA_AUTH_ROUTING_MODE=direct-upstream
# or NEXT_PUBLIC_ATHENA_AUTH_ROUTING_MODE=direct-upstream

ATHENA_AUTH_UPSTREAM_URL=https://auth.example.com
# / NEXT_PUBLIC_ATHENA_AUTH_UPSTREAM_URL=...
```
Tokens:
Raw