@xylex-group/athena 0.2.1 → 1.0.4

package/README.md

@@ -1,103 +1,294 @@
-# athena-js
-
-Athena is a database driver + API gateway SDK that lets you interact with SQL backends using the familiar `supabase-js` syntax.
-
-## Gateway query builder
-
-```ts
-import { createClient } from "athena-js";
-
-const athena = createClient(
-  "https://athena-db.com",
-  process.env.ATHENA_API_KEY,
-);
-
-const { data, error } = await athena.from("characters").select(`
-    id,
-    name,
-    from:sender_id(name),
-    to:receiver_id(name)
-  `);
-
-if (error) {
-  console.error("gateway error", error);
-} else {
-  console.table(data);
-}
-```
-
-Use `select`, `insert`, `update`, `delete`, and `upsert` just like Supabase. The builder now exposes Supabase-style helpers such as `.range()`, `.gt()`, `.lt()`, `.ilike()`, `.contains()`, `.not()`, `.or()`, and `.maybeSingle()` so existing Supabase code runs without changes.
-
-### Filters & modifiers
-
-Filters are cumulative and stack on the query builder:
-
-```ts
-const { data } = await athena
-  .from('characters')
-  .select('id, name')
-  .gt('level', 5)
-  .lte('created_at', '2024-01-01')
-  .contains('tags', ['hero'])
-  .range(0, 49)
-```
-
-Modifiers like `.limit()`, `.offset()`, `.range()`, and `.match()` behave the same as in Supabase. The fetch call automatically sends `strip_nulls`, `count`, `head`, and `defaultToNull` options when provided.
-
-### Mutations
-
-Mutation methods return a Supabase-compatible `MutationQuery` so you can chain `.select()`, `.single()`, and `.returning()` after invoking them:
-
-```ts
-const { data: inserted, error } = await athena
-  .from('countries')
-  .insert({ id: 1, name: 'Mordor' })
-  .select('id, name')
-
-const { data: updated } = await athena
-  .from('countries')
-  .update({ name: 'Gondor' })
-  .eq('id', 1)
-  .select()
-
-const { data: upserted } = await athena
-  .from('countries')
-  .upsert({ id: 2, name: 'Rohan' }, { updateBody: { name: 'Rohan' }, onConflict: 'id' })
-  .select()
-```
-
-Insert and upsert calls accept Supabase-compatible options such as `defaultToNull`, `count`, `head`, and `onConflict`. Delete operations allow filtering by `.eq()` or by passing `options.resourceId` as in Supabase.
-
-## React hook
-
-```tsx
-"use client";
-
-import { useAthenaGateway } from "athena-js/react";
-import { useEffect } from "react";
-
-export function UsersPanel() {
-  const { fetchGateway, lastResponse, isLoading, error } = useAthenaGateway({
-    baseUrl: "https://athena-db.com",
-    apiKey: process.env.NEXT_PUBLIC_ATHENA_API_KEY,
-  });
-
-  useEffect(() => {
-    fetchGateway({
-      table_name: "users",
-      columns: ["id", "email"],
-      limit: 25,
-    });
-  }, [fetchGateway]);
-
-  if (error) return <div>Error: {error}</div>;
-  if (isLoading) return <div>Loading…</div>;
-
-  return <pre>{JSON.stringify(lastResponse?.data, null, 2)}</pre>;
-}
-```
-
-## Learn more
-
-- [API reference](docs/api-reference.md)
-- [Getting started](docs/getting-started.md)
+# athena-js
+
+`@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 and a React hook for client-side use.
+
+## Install
+
+```bash
+npm install @xylex-group/athena
+# or
+pnpm add @xylex-group/athena
+# or
+yarn add @xylex-group/athena
+```
+
+React peer dependency is optional — only needed if you use `useAthenaGateway`.
+
+```bash
+npm install react  # React >=17 required for the hook
+```
+
+## Quick start
+
+```ts
+import { createClient } from "@xylex-group/athena";
+
+const athena = createClient(
+  "https://athena-db.com",
+  process.env.ATHENA_API_KEY,
+);
+
+const { data, error } = await athena.from("characters").select(`
+    id,
+    name,
+    from:sender_id(name),
+    to:receiver_id(name)
+  `);
+
+if (error) {
+  console.error("gateway error", error);
+} else {
+  console.table(data);
+}
+```
+
+Every query resolves to `{ data, error, status, raw }`. `data` is `null` on error; `error` is `null` on success.
+
+## Query builder
+
+### 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");
+
+// select with type annotation
+const { data } = await athena.from<User>("users").select("id, name");
+```
+
+### Filters
+
+Filters accumulate on the builder and are sent together when the query executes.
+
+```ts
+const { data } = await athena
+  .from("characters")
+  .select("id, name")
+  .eq("active", true)           // column = value
+  .neq("role", "guest")         // column != value
+  .gt("level", 5)               // column > value
+  .gte("score", 100)            // column >= value
+  .lt("age", 30)                // column < value
+  .lte("created_at", "2024-01-01") // column <= value
+  .like("name", "Ali%")         // SQL LIKE (case-sensitive)
+  .ilike("email", "%@example%") // SQL ILIKE (case-insensitive)
+  .is("deleted_at", null)       // IS NULL / IS TRUE etc.
+  .in("status", ["active", "pending"])    // IN (…)
+  .contains("tags", ["hero"])             // array contains value
+  .containedBy("tags", ["hero", "villain"]) // array is subset of value
+  .match({ role: "admin", active: true }) // multiple eq filters at once
+  .not("role", "eq", "banned")  // NOT col op val
+  .or("status.eq.active,status.eq.pending"); // OR expression
+```
+
+### Pagination
+
+```ts
+// explicit limit and offset
+const { data } = await athena.from("users").select().limit(25).offset(50);
+
+// range shorthand — equivalent to offset(from).limit(to - from + 1)
+const { data } = await athena.from("users").select().range(0, 24);
+```
+
+### Single row
+
+```ts
+// returns the first row or null instead of an array
+const { data: user } = await athena
+  .from("users")
+  .select("id, name")
+  .eq("id", 42)
+  .single();
+```
+
+`maybeSingle` behaves identically — both return the first element of the result set.
+
+### Options
+
+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`) |
+
+```ts
+const { data } = await athena
+  .from("orders")
+  .select("id", { count: "exact", stripNulls: false });
+```
+
+## Mutations
+
+Insert, update, upsert, and delete all return a `MutationQuery` that you can await directly or chain further calls onto before the request fires.
+
+### Insert
+
+```ts
+const { data: inserted } = await athena
+  .from("countries")
+  .insert({ name: "Mordor" })
+  .select("id, name");
+
+// insert multiple rows
+const { data } = await athena
+  .from("characters")
+  .insert([{ name: "Frodo" }, { name: "Sam" }])
+  .select();
+```
+
+### Update
+
+```ts
+const { data: updated } = await athena
+  .from("countries")
+  .update({ name: "Gondor" })
+  .eq("id", 1)
+  .select();
+```
+
+Filters (`.eq()`, `.match()`, etc.) applied before `.update()` are used as `WHERE` conditions.
+
+### Upsert
+
+```ts
+const { data } = await athena
+  .from("countries")
+  .upsert(
+    { id: 2, name: "Rohan" },
+    { updateBody: { name: "Rohan" }, onConflict: "id" },
+  )
+  .select();
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `onConflict` | `string \| string[]` | column(s) that determine a conflict |
+| `updateBody` | `object` | fields to apply when a conflict occurs |
+| `defaultToNull` | `boolean` | write explicit `null` for missing fields |
+| `count` | `"exact" \| "planned" \| "estimated"` | request a row count |
+| `head` | `boolean` | return headers only |
+
+### Delete
+
+```ts
+// delete by id filter
+await athena.from("countries").eq("id", 1).delete();
+
+// delete with explicit resourceId option
+await athena.from("countries").delete({ resourceId: "abc-123" });
+
+// chain .select() to get the deleted row back
+const { data: deleted } = await athena
+  .from("countries")
+  .eq("resource_id", "abc-123")
+  .delete()
+  .select("id, name");
+```
+
+Delete requires either `.eq("resource_id", …)`, `.eq("id", …)`, or `options.resourceId` — calling `.delete()` without any of these throws an error.
+
+### MutationQuery chaining
+
+All mutation methods return a `MutationQuery` which supports:
+
+```ts
+const mutation = athena.from("users").insert({ name: "Alice" });
+
+await mutation.select("id, name");        // fire request, return rows
+await mutation.returning("id");           // alias for .select()
+await mutation.single("id");              // return first row or null
+await mutation.maybeSingle("id");         // same as .single()
+await mutation;                           // fire request, return default columns
+mutation.then(({ data }) => …);           // thenable
+mutation.catch(err => …);
+mutation.finally(() => …);
+```
+
+The request fires only once regardless of how many times you call `.then()` or await the object.
+
+## React hook
+
+```tsx
+"use client";
+
+import { useAthenaGateway } from "@xylex-group/athena/react";
+import { useEffect } from "react";
+
+export function UsersPanel() {
+  const { fetchGateway, lastResponse, isLoading, error } = useAthenaGateway({
+    baseUrl: "https://athena-db.com",
+    apiKey: process.env.NEXT_PUBLIC_ATHENA_API_KEY,
+  });
+
+  useEffect(() => {
+    fetchGateway({
+      table_name: "users",
+      columns: ["id", "email"],
+      limit: 25,
+    });
+  }, [fetchGateway]);
+
+  if (error) return <div>Error: {error}</div>;
+  if (isLoading) return <div>Loading…</div>;
+
+  return <pre>{JSON.stringify(lastResponse?.data, null, 2)}</pre>;
+}
+```
+
+The hook returns `fetchGateway`, `insertGateway`, `updateGateway`, `deleteGateway`, `isLoading`, `error`, `lastRequest`, `lastResponse`, and `baseUrl`.
+
+Hook config options mirror the client options: `baseUrl`, `apiKey`, `headers`, `userId`, `organizationId`, `publishEvent`.
+
+## User context headers
+
+Pass user and tenant context to every request without repeating it on each call:
+
+```ts
+const athena = createClient("https://athena-db.com", process.env.ATHENA_API_KEY, {
+  headers: {
+    "X-User-Id": currentUser.id,
+    "X-Organization-Id": currentUser.organizationId ?? "",
+  },
+});
+```
+
+Or pass per-call via options. The Athena server interprets `url` and `key` based on the backend type (Supabase, PostgREST, etc.).
+
+## Custom headers
+
+```ts
+const athena = createClient("https://athena-db.com", process.env.ATHENA_API_KEY, {
+  headers: {
+    "X-Custom-Header": "value",
+  },
+});
+```
+
+Per-call headers are merged with the client-level headers, with per-call values winning on conflict.
+
+## TypeScript
+
+The package is written in TypeScript and ships declaration files. Pass a row type to `.from()` for fully-typed builder methods and results:
+
+```ts
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  active: boolean;
+}
+
+const { data } = await athena.from<User>("users").select("id, name").eq("active", true);
+// data is User[] | null
+```
+
+## Learn more
+
+- [Getting started](docs/getting-started.md) — step-by-step walkthrough
+- [API reference](docs/api-reference.md) — complete method and type reference

package/bin/athena-js.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import('../dist/cli/index.js').then(({ runCLI }) => {
   runCLI(process.argv.slice(2))

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { A as AthenaGatewayCallOptions, a as AthenaConditionValue, b as AthenaConditionArrayValue, c as AthenaConditionOperator } from './types-DzCf3v76.mjs';
-export { d as AthenaDeletePayload, e as AthenaFetchPayload, f as AthenaGatewayBaseOptions, g as AthenaGatewayCallLog, h as AthenaGatewayCondition, i as AthenaGatewayEndpointPath, j as AthenaGatewayHookConfig, k as AthenaGatewayHookResult, l as AthenaGatewayMethod, m as AthenaGatewayResponse, n as AthenaGatewayResponseLog, o as AthenaInsertPayload, p as AthenaUpdatePayload } from './types-DzCf3v76.mjs';
+import { B as BackendConfig, a as BackendType, A as AthenaConditionValue, b as AthenaConditionArrayValue, c as AthenaConditionOperator, d as AthenaGatewayCallOptions } from './types-D0uYdUea.mjs';
+export { e as Backend } from './types-D0uYdUea.mjs';
 
 interface SupabaseResult<T> {
     data: T | null;
@@ -17,35 +17,46 @@ interface MutationQuery<Result> extends PromiseLike<SupabaseResult<Result>> {
     catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | undefined | null): Promise<SupabaseResult<Result> | TResult>;
     finally(onfinally?: (() => void) | undefined | null): Promise<SupabaseResult<Result>>;
 }
-interface TableQueryBuilder<Row> {
-    select<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<T>>;
+/** Shared filter chain - supports eq, limit, etc. in any order relative to select/update */
+interface FilterChain<Self> {
+    eq(column: string, value: AthenaConditionValue): Self;
+    match(filters: Record<string, AthenaConditionValue>): Self;
+    range(from: number, to: number): Self;
+    limit(count: number): Self;
+    offset(count: number): Self;
+    gt(column: string, value: AthenaConditionValue): Self;
+    gte(column: string, value: AthenaConditionValue): Self;
+    lt(column: string, value: AthenaConditionValue): Self;
+    lte(column: string, value: AthenaConditionValue): Self;
+    neq(column: string, value: AthenaConditionValue): Self;
+    like(column: string, value: AthenaConditionValue): Self;
+    ilike(column: string, value: AthenaConditionValue): Self;
+    is(column: string, value: AthenaConditionValue): Self;
+    in(column: string, values: AthenaConditionArrayValue): Self;
+    contains(column: string, values: AthenaConditionArrayValue): Self;
+    containedBy(column: string, values: AthenaConditionArrayValue): Self;
+    not(columnOrExpression: string, operator?: AthenaConditionOperator, value?: AthenaConditionValue): Self;
+    or(expression: string): Self;
+}
+/** Chain returned by select() - supports filters and single/maybeSingle before execution */
+interface SelectChain<Row> extends FilterChain<SelectChain<Row>>, PromiseLike<SupabaseResult<Row[]>> {
+    single<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<T | null>>;
+    maybeSingle<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<T | null>>;
+}
+/** Chain returned by update() - supports filters before execution, plus select/returning */
+interface UpdateChain<Row> extends FilterChain<UpdateChain<Row>>, MutationQuery<Row[]> {
+}
+interface TableQueryBuilder<Row> extends FilterChain<TableQueryBuilder<Row>> {
+    select<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): SelectChain<T>;
     insert(values: Row | Row[], options?: AthenaGatewayCallOptions): MutationQuery<Row | Row[]>;
     upsert(values: Row | Row[], options?: AthenaGatewayCallOptions & {
         updateBody?: Partial<Row>;
         onConflict?: string | string[];
     }): MutationQuery<Row | Row[]>;
-    update(values: Partial<Row>, options?: AthenaGatewayCallOptions): MutationQuery<Row[]>;
+    update(values: Partial<Row>, options?: AthenaGatewayCallOptions): UpdateChain<Row>;
     delete(options?: AthenaGatewayCallOptions & {
         resourceId?: string;
     }): MutationQuery<Row | null>;
-    eq(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    match(filters: Record<string, AthenaConditionValue>): TableQueryBuilder<Row>;
-    range(from: number, to: number): TableQueryBuilder<Row>;
-    limit(count: number): TableQueryBuilder<Row>;
-    offset(count: number): TableQueryBuilder<Row>;
-    gt(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    gte(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    lt(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    lte(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    neq(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    like(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    ilike(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    is(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    in(column: string, values: AthenaConditionArrayValue): TableQueryBuilder<Row>;
-    contains(column: string, values: AthenaConditionArrayValue): TableQueryBuilder<Row>;
-    containedBy(column: string, values: AthenaConditionArrayValue): TableQueryBuilder<Row>;
-    not(columnOrExpression: string, operator?: AthenaConditionOperator, value?: AthenaConditionValue): TableQueryBuilder<Row>;
-    or(expression: string): TableQueryBuilder<Row>;
     single<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<T | null>>;
     maybeSingle<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<T | null>>;
     reset(): TableQueryBuilder<Row>;
@@ -53,6 +64,21 @@ interface TableQueryBuilder<Row> {
 interface SupabaseClient {
     from<Row = unknown>(table: string): TableQueryBuilder<Row>;
 }
-declare function createClient(url: string, apiKey: string, options?: AthenaGatewayCallOptions): SupabaseClient;
+interface AthenaClientBuilder {
+    url(url: string): AthenaClientBuilder;
+    key(apiKey: string): AthenaClientBuilder;
+    backend(backend: BackendConfig | BackendType): AthenaClientBuilder;
+    client(clientName: string): AthenaClientBuilder;
+    headers(headers: Record<string, string>): AthenaClientBuilder;
+    healthTracking(enabled: boolean): AthenaClientBuilder;
+    build(): SupabaseClient;
+}
+declare const AthenaClient: {
+    builder(): AthenaClientBuilder;
+    /** Build client from env: ATHENA_SUPABASE_URL, ATHENA_SUPABASE_KEY (or SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY) */
+    fromSupabaseEnv(): SupabaseClient;
+};
+/** Create client (convenience wrapper; use AthenaClient.builder() for full control) */
+declare function createClient(url: string, apiKey: string, options?: Pick<AthenaGatewayCallOptions, 'client' | 'headers' | 'backend'>): SupabaseClient;
 
-export { AthenaGatewayCallOptions, type SupabaseClient, type SupabaseResult, type TableQueryBuilder, createClient };
+export { AthenaClient, AthenaGatewayCallOptions, BackendConfig, BackendType, type SupabaseClient, type SupabaseResult, type TableQueryBuilder, createClient };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AthenaGatewayCallOptions, a as AthenaConditionValue, b as AthenaConditionArrayValue, c as AthenaConditionOperator } from './types-DzCf3v76.js';
-export { d as AthenaDeletePayload, e as AthenaFetchPayload, f as AthenaGatewayBaseOptions, g as AthenaGatewayCallLog, h as AthenaGatewayCondition, i as AthenaGatewayEndpointPath, j as AthenaGatewayHookConfig, k as AthenaGatewayHookResult, l as AthenaGatewayMethod, m as AthenaGatewayResponse, n as AthenaGatewayResponseLog, o as AthenaInsertPayload, p as AthenaUpdatePayload } from './types-DzCf3v76.js';
+import { B as BackendConfig, a as BackendType, A as AthenaConditionValue, b as AthenaConditionArrayValue, c as AthenaConditionOperator, d as AthenaGatewayCallOptions } from './types-D0uYdUea.js';
+export { e as Backend } from './types-D0uYdUea.js';
 
 interface SupabaseResult<T> {
     data: T | null;
@@ -17,35 +17,46 @@ interface MutationQuery<Result> extends PromiseLike<SupabaseResult<Result>> {
     catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | undefined | null): Promise<SupabaseResult<Result> | TResult>;
     finally(onfinally?: (() => void) | undefined | null): Promise<SupabaseResult<Result>>;
 }
-interface TableQueryBuilder<Row> {
-    select<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<T>>;
+/** Shared filter chain - supports eq, limit, etc. in any order relative to select/update */
+interface FilterChain<Self> {
+    eq(column: string, value: AthenaConditionValue): Self;
+    match(filters: Record<string, AthenaConditionValue>): Self;
+    range(from: number, to: number): Self;
+    limit(count: number): Self;
+    offset(count: number): Self;
+    gt(column: string, value: AthenaConditionValue): Self;
+    gte(column: string, value: AthenaConditionValue): Self;
+    lt(column: string, value: AthenaConditionValue): Self;
+    lte(column: string, value: AthenaConditionValue): Self;
+    neq(column: string, value: AthenaConditionValue): Self;
+    like(column: string, value: AthenaConditionValue): Self;
+    ilike(column: string, value: AthenaConditionValue): Self;
+    is(column: string, value: AthenaConditionValue): Self;
+    in(column: string, values: AthenaConditionArrayValue): Self;
+    contains(column: string, values: AthenaConditionArrayValue): Self;
+    containedBy(column: string, values: AthenaConditionArrayValue): Self;
+    not(columnOrExpression: string, operator?: AthenaConditionOperator, value?: AthenaConditionValue): Self;
+    or(expression: string): Self;
+}
+/** Chain returned by select() - supports filters and single/maybeSingle before execution */
+interface SelectChain<Row> extends FilterChain<SelectChain<Row>>, PromiseLike<SupabaseResult<Row[]>> {
+    single<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<T | null>>;
+    maybeSingle<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<T | null>>;
+}
+/** Chain returned by update() - supports filters before execution, plus select/returning */
+interface UpdateChain<Row> extends FilterChain<UpdateChain<Row>>, MutationQuery<Row[]> {
+}
+interface TableQueryBuilder<Row> extends FilterChain<TableQueryBuilder<Row>> {
+    select<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): SelectChain<T>;
     insert(values: Row | Row[], options?: AthenaGatewayCallOptions): MutationQuery<Row | Row[]>;
     upsert(values: Row | Row[], options?: AthenaGatewayCallOptions & {
         updateBody?: Partial<Row>;
         onConflict?: string | string[];
     }): MutationQuery<Row | Row[]>;
-    update(values: Partial<Row>, options?: AthenaGatewayCallOptions): MutationQuery<Row[]>;
+    update(values: Partial<Row>, options?: AthenaGatewayCallOptions): UpdateChain<Row>;
     delete(options?: AthenaGatewayCallOptions & {
         resourceId?: string;
     }): MutationQuery<Row | null>;
-    eq(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    match(filters: Record<string, AthenaConditionValue>): TableQueryBuilder<Row>;
-    range(from: number, to: number): TableQueryBuilder<Row>;
-    limit(count: number): TableQueryBuilder<Row>;
-    offset(count: number): TableQueryBuilder<Row>;
-    gt(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    gte(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    lt(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    lte(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    neq(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    like(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    ilike(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    is(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
-    in(column: string, values: AthenaConditionArrayValue): TableQueryBuilder<Row>;
-    contains(column: string, values: AthenaConditionArrayValue): TableQueryBuilder<Row>;
-    containedBy(column: string, values: AthenaConditionArrayValue): TableQueryBuilder<Row>;
-    not(columnOrExpression: string, operator?: AthenaConditionOperator, value?: AthenaConditionValue): TableQueryBuilder<Row>;
-    or(expression: string): TableQueryBuilder<Row>;
     single<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<T | null>>;
     maybeSingle<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<T | null>>;
     reset(): TableQueryBuilder<Row>;
@@ -53,6 +64,21 @@ interface TableQueryBuilder<Row> {
 interface SupabaseClient {
     from<Row = unknown>(table: string): TableQueryBuilder<Row>;
 }
-declare function createClient(url: string, apiKey: string, options?: AthenaGatewayCallOptions): SupabaseClient;
+interface AthenaClientBuilder {
+    url(url: string): AthenaClientBuilder;
+    key(apiKey: string): AthenaClientBuilder;
+    backend(backend: BackendConfig | BackendType): AthenaClientBuilder;
+    client(clientName: string): AthenaClientBuilder;
+    headers(headers: Record<string, string>): AthenaClientBuilder;
+    healthTracking(enabled: boolean): AthenaClientBuilder;
+    build(): SupabaseClient;
+}
+declare const AthenaClient: {
+    builder(): AthenaClientBuilder;
+    /** Build client from env: ATHENA_SUPABASE_URL, ATHENA_SUPABASE_KEY (or SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY) */
+    fromSupabaseEnv(): SupabaseClient;
+};
+/** Create client (convenience wrapper; use AthenaClient.builder() for full control) */
+declare function createClient(url: string, apiKey: string, options?: Pick<AthenaGatewayCallOptions, 'client' | 'headers' | 'backend'>): SupabaseClient;
 
-export { AthenaGatewayCallOptions, type SupabaseClient, type SupabaseResult, type TableQueryBuilder, createClient };
+export { AthenaClient, AthenaGatewayCallOptions, BackendConfig, BackendType, type SupabaseClient, type SupabaseResult, type TableQueryBuilder, createClient };