@xylex-group/athena 1.1.1 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `1.1.1`
+current version: `1.2.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 and a React hook for client-side use.
 
 ## Install
@@ -43,7 +43,9 @@ if (error) {
 }
 ```
 
-Every query resolves to `{ data, error, status, raw }`. `data` is `null` on error; `error` is `null` on success.
+Every query resolves to `{ data, error, errorDetails?, status, count?, raw }`. `data` is `null` on error; `error` is `null` on success.
+
+For richer handling, inspect `errorDetails` (`code`, `status`, `endpoint`, `method`, `requestId`, etc.) or use `AthenaGatewayError` / `isAthenaGatewayError` from the package exports.
 
 ## Query builder
 
@@ -62,10 +64,10 @@ 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
+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
@@ -82,8 +84,17 @@ const { data } = await athena
   .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
-```
+  .or("status.eq.active,status.eq.pending"); // OR expression
+```
+
+Canonical style for reads is to call `.select(...)` first, then apply filters:
+
+```ts
+const { data } = await athena
+  .from("instruments")
+  .select("name, section_id")
+  .eq("name", "violin");
+```
 
 ### Pagination
 
@@ -108,7 +119,32 @@ const { data: user } = await athena
 
 `maybeSingle` behaves identically — both return the first element of the result set.
 
-### Options
+### 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
+  .rpc("list_users", { role: "admin" }, { count: "exact", schema: "public" })
+  .eq("active", true)
+  .order("created_at", { ascending: false })
+  .range(0, 24)
+  .select(["id", "email"]);
+
+const { data: firstUser } = await athena
+  .rpc<{ id: number; email: string }>("list_users", { role: "admin" })
+  .single("id,email");
+
+const { data: readOnlyUser } = await athena
+  .rpc<{ id: number; email: string }>("list_users", { role: "admin" }, { get: true, count: "planned", head: true })
+  .eq("id", 1)
+  .single("id,email");
+```
+
+RPC chain methods: `.eq()`, `.neq()`, `.gt()`, `.gte()`, `.lt()`, `.lte()`, `.like()`, `.ilike()`, `.is()`, `.in()`, `.order()`, `.limit()`, `.offset()`, `.range()`, `.select()`, `.single()`, `.maybeSingle()`.
+RPC options: `schema`, `count` (`"exact" | "planned" | "estimated"`), `head`, `get`.
+
+### Options
 
 Pass options as the second argument to `.select()`:
 
@@ -142,9 +178,9 @@ const { data } = await athena
   .insert([{ name: "Frodo" }, { name: "Sam" }])
   .select();
 
-// Type inference differs by payload shape:
-// - insert(one) => SupabaseResult<Row>
-// - insert(many) => SupabaseResult<Row[]>
+// Type inference differs by payload shape:
+// - insert(one) => AthenaResult<Row>
+// - insert(many) => AthenaResult<Row[]>
 ```
 
 ### Update
@@ -170,9 +206,9 @@ const { data } = await athena
   )
   .select();
 
-// Type inference differs by payload shape:
-// - upsert(one) => SupabaseResult<Row>
-// - upsert(many) => SupabaseResult<Row[]>
+// Type inference differs by payload shape:
+// - upsert(one) => AthenaResult<Row>
+// - upsert(many) => AthenaResult<Row[]>
 ```
 
 | Option | Type | Description |
@@ -250,7 +286,7 @@ export function UsersPanel() {
 }
 ```
 
-The hook returns `fetchGateway`, `insertGateway`, `updateGateway`, `deleteGateway`, `isLoading`, `error`, `lastRequest`, `lastResponse`, and `baseUrl`.
+The hook returns `fetchGateway`, `insertGateway`, `updateGateway`, `deleteGateway`, `rpcGateway`, `isLoading`, `error`, `lastRequest`, `lastResponse`, and `baseUrl`.
 
 Hook config options mirror the client options: `baseUrl`, `apiKey`, `headers`, `userId`, `organizationId`, `publishEvent`.
 
@@ -267,7 +303,7 @@ const athena = createClient("https://athena-db.com", process.env.ATHENA_API_KEY,
 });
 ```
 
-Or pass per-call via options. The Athena server interprets `url` and `key` based on the backend type (Supabase, PostgREST, etc.).
+Or pass per-call via options. The Athena server interprets `url` and `key` based on the configured backend type.
 
 ## Custom headers
 

package/dist/{types-DorEXMAz.d.cts → errors-DKNcLa5O.d.cts}

@@ -3,8 +3,8 @@
  *
  * type definitions for the athena gateway api client and react hook
  */
-type AthenaGatewayMethod = 'POST' | 'PUT' | 'DELETE';
-type AthenaGatewayEndpointPath = '/gateway/fetch' | '/gateway/insert' | '/gateway/update' | '/gateway/delete';
+type AthenaGatewayMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+type AthenaGatewayEndpointPath = '/gateway/fetch' | '/gateway/insert' | '/gateway/update' | '/gateway/delete' | '/gateway/rpc' | '/gateway/query' | `/rpc/${string}`;
 type AthenaCountOption = 'exact' | 'planned' | 'estimated';
 type AthenaConditionValue = string | number | boolean | null;
 type AthenaConditionArrayValue = Array<AthenaConditionValue>;
@@ -53,8 +53,31 @@ interface AthenaDeletePayload {
 interface AthenaUpdatePayload extends AthenaFetchPayload {
     update_body?: Record<string, unknown>;
 }
+type AthenaRpcFilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'is' | 'in';
+interface AthenaRpcFilter {
+    column: string;
+    operator: AthenaRpcFilterOperator;
+    value?: AthenaConditionValue | AthenaConditionArrayValue | string;
+}
+interface AthenaRpcOrder {
+    column: string;
+    ascending?: boolean;
+}
+interface AthenaRpcPayload {
+    function: string;
+    function_name?: string;
+    schema?: string;
+    args?: Record<string, unknown>;
+    select?: string;
+    filters?: AthenaRpcFilter[];
+    count?: AthenaCountOption;
+    head?: boolean;
+    limit?: number;
+    offset?: number;
+    order?: AthenaRpcOrder;
+}
 /** Backend type for Athena client (aligns with athena-rs) */
-type BackendType = 'athena' | 'postgrest' | 'supabase' | 'postgresql' | 'scylladb';
+type BackendType = 'athena' | 'postgrest' | 'postgresql' | 'scylladb';
 /** Backend config: type from SDK + backend-scoped options */
 interface BackendConfig {
     type: BackendType;
@@ -65,9 +88,6 @@ declare const Backend: {
     readonly Athena: {
         readonly type: "athena";
     };
-    readonly Supabase: {
-        readonly type: "supabase";
-    };
     readonly Postgrest: {
         readonly type: "postgrest";
     };
@@ -98,13 +118,31 @@ interface AthenaGatewayCallOptions extends AthenaGatewayBaseOptions {
     onConflict?: string | string[];
     updateBody?: Record<string, unknown>;
 }
+interface AthenaRpcCallOptions extends AthenaGatewayCallOptions {
+    schema?: string;
+    count?: AthenaCountOption;
+    get?: boolean;
+}
 interface AthenaGatewayResponse<T = unknown> {
     ok: boolean;
     status: number;
     data: T | null;
+    count?: number | null;
     error?: string;
+    errorDetails?: AthenaGatewayErrorDetails | null;
     raw: unknown;
 }
+type AthenaGatewayErrorCode = 'NETWORK_ERROR' | 'HTTP_ERROR' | 'INVALID_JSON' | 'UNKNOWN_ERROR';
+interface AthenaGatewayErrorDetails {
+    code: AthenaGatewayErrorCode;
+    message: string;
+    status: number;
+    endpoint?: AthenaGatewayEndpointPath;
+    method?: AthenaGatewayMethod;
+    requestId?: string;
+    hint?: string;
+    cause?: string;
+}
 interface AthenaGatewayResponseLog extends AthenaGatewayResponse {
     timestamp: string;
 }
@@ -120,6 +158,7 @@ interface AthenaGatewayHookResult {
     insertGateway: <T = unknown>(payload: AthenaInsertPayload, options?: AthenaGatewayCallOptions) => Promise<AthenaGatewayResponse<T>>;
     updateGateway: <T = unknown>(payload: AthenaUpdatePayload, options?: AthenaGatewayCallOptions) => Promise<AthenaGatewayResponse<T>>;
     deleteGateway: <T = unknown>(payload: AthenaDeletePayload, options?: AthenaGatewayCallOptions) => Promise<AthenaGatewayResponse<T>>;
+    rpcGateway: <T = unknown>(payload: AthenaRpcPayload, options?: AthenaRpcCallOptions) => Promise<AthenaGatewayResponse<T>>;
     isLoading: boolean;
     error: string | null;
     lastRequest: AthenaGatewayCallLog | null;
@@ -127,4 +166,32 @@ interface AthenaGatewayHookResult {
     baseUrl: string;
 }
 
-export { type AthenaConditionValue as A, type BackendConfig as B, type BackendType as a, type AthenaConditionArrayValue as b, type AthenaConditionOperator as c, type AthenaGatewayCallOptions as d, Backend as e, type AthenaGatewayHookConfig as f, type AthenaGatewayHookResult as g, type AthenaDeletePayload as h, type AthenaFetchPayload as i, type AthenaGatewayResponse as j, type AthenaInsertPayload as k, type AthenaUpdatePayload as l };
+interface AthenaGatewayErrorInput {
+    code: AthenaGatewayErrorCode;
+    message: string;
+    status?: number;
+    endpoint?: AthenaGatewayEndpointPath;
+    method?: AthenaGatewayMethod;
+    requestId?: string;
+    hint?: string;
+    cause?: string;
+}
+/**
+ * Canonical error for gateway failures.
+ * Holds request context and machine-readable classification.
+ */
+declare class AthenaGatewayError extends Error {
+    readonly code: AthenaGatewayErrorCode;
+    readonly status: number;
+    readonly endpoint?: AthenaGatewayEndpointPath;
+    readonly method?: AthenaGatewayMethod;
+    readonly requestId?: string;
+    readonly hint?: string;
+    readonly causeDetail?: string;
+    constructor(input: AthenaGatewayErrorInput);
+    toDetails(): AthenaGatewayErrorDetails;
+    static fromResponse<T>(response: AthenaGatewayResponse<T>, fallback: Omit<AthenaGatewayErrorInput, 'code' | 'message' | 'status'>): AthenaGatewayError;
+}
+declare function isAthenaGatewayError(error: unknown): error is AthenaGatewayError;
+
+export { type AthenaConditionValue as A, type BackendConfig as B, type BackendType as a, type AthenaConditionArrayValue as b, type AthenaConditionOperator as c, type AthenaGatewayCallOptions as d, type AthenaGatewayErrorDetails as e, type AthenaRpcCallOptions as f, AthenaGatewayError as g, type AthenaGatewayErrorCode as h, type AthenaRpcFilter as i, type AthenaRpcFilterOperator as j, type AthenaRpcOrder as k, type AthenaRpcPayload as l, Backend as m, isAthenaGatewayError as n, type AthenaGatewayHookConfig as o, type AthenaGatewayHookResult as p, type AthenaDeletePayload as q, type AthenaFetchPayload as r, type AthenaGatewayResponse as s, type AthenaInsertPayload as t, type AthenaUpdatePayload as u };

package/dist/{types-DorEXMAz.d.ts → errors-DKNcLa5O.d.ts}

@@ -3,8 +3,8 @@
  *
  * type definitions for the athena gateway api client and react hook
  */
-type AthenaGatewayMethod = 'POST' | 'PUT' | 'DELETE';
-type AthenaGatewayEndpointPath = '/gateway/fetch' | '/gateway/insert' | '/gateway/update' | '/gateway/delete';
+type AthenaGatewayMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+type AthenaGatewayEndpointPath = '/gateway/fetch' | '/gateway/insert' | '/gateway/update' | '/gateway/delete' | '/gateway/rpc' | '/gateway/query' | `/rpc/${string}`;
 type AthenaCountOption = 'exact' | 'planned' | 'estimated';
 type AthenaConditionValue = string | number | boolean | null;
 type AthenaConditionArrayValue = Array<AthenaConditionValue>;
@@ -53,8 +53,31 @@ interface AthenaDeletePayload {
 interface AthenaUpdatePayload extends AthenaFetchPayload {
     update_body?: Record<string, unknown>;
 }
+type AthenaRpcFilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'is' | 'in';
+interface AthenaRpcFilter {
+    column: string;
+    operator: AthenaRpcFilterOperator;
+    value?: AthenaConditionValue | AthenaConditionArrayValue | string;
+}
+interface AthenaRpcOrder {
+    column: string;
+    ascending?: boolean;
+}
+interface AthenaRpcPayload {
+    function: string;
+    function_name?: string;
+    schema?: string;
+    args?: Record<string, unknown>;
+    select?: string;
+    filters?: AthenaRpcFilter[];
+    count?: AthenaCountOption;
+    head?: boolean;
+    limit?: number;
+    offset?: number;
+    order?: AthenaRpcOrder;
+}
 /** Backend type for Athena client (aligns with athena-rs) */
-type BackendType = 'athena' | 'postgrest' | 'supabase' | 'postgresql' | 'scylladb';
+type BackendType = 'athena' | 'postgrest' | 'postgresql' | 'scylladb';
 /** Backend config: type from SDK + backend-scoped options */
 interface BackendConfig {
     type: BackendType;
@@ -65,9 +88,6 @@ declare const Backend: {
     readonly Athena: {
         readonly type: "athena";
     };
-    readonly Supabase: {
-        readonly type: "supabase";
-    };
     readonly Postgrest: {
         readonly type: "postgrest";
     };
@@ -98,13 +118,31 @@ interface AthenaGatewayCallOptions extends AthenaGatewayBaseOptions {
     onConflict?: string | string[];
     updateBody?: Record<string, unknown>;
 }
+interface AthenaRpcCallOptions extends AthenaGatewayCallOptions {
+    schema?: string;
+    count?: AthenaCountOption;
+    get?: boolean;
+}
 interface AthenaGatewayResponse<T = unknown> {
     ok: boolean;
     status: number;
     data: T | null;
+    count?: number | null;
     error?: string;
+    errorDetails?: AthenaGatewayErrorDetails | null;
     raw: unknown;
 }
+type AthenaGatewayErrorCode = 'NETWORK_ERROR' | 'HTTP_ERROR' | 'INVALID_JSON' | 'UNKNOWN_ERROR';
+interface AthenaGatewayErrorDetails {
+    code: AthenaGatewayErrorCode;
+    message: string;
+    status: number;
+    endpoint?: AthenaGatewayEndpointPath;
+    method?: AthenaGatewayMethod;
+    requestId?: string;
+    hint?: string;
+    cause?: string;
+}
 interface AthenaGatewayResponseLog extends AthenaGatewayResponse {
     timestamp: string;
 }
@@ -120,6 +158,7 @@ interface AthenaGatewayHookResult {
     insertGateway: <T = unknown>(payload: AthenaInsertPayload, options?: AthenaGatewayCallOptions) => Promise<AthenaGatewayResponse<T>>;
     updateGateway: <T = unknown>(payload: AthenaUpdatePayload, options?: AthenaGatewayCallOptions) => Promise<AthenaGatewayResponse<T>>;
     deleteGateway: <T = unknown>(payload: AthenaDeletePayload, options?: AthenaGatewayCallOptions) => Promise<AthenaGatewayResponse<T>>;
+    rpcGateway: <T = unknown>(payload: AthenaRpcPayload, options?: AthenaRpcCallOptions) => Promise<AthenaGatewayResponse<T>>;
     isLoading: boolean;
     error: string | null;
     lastRequest: AthenaGatewayCallLog | null;
@@ -127,4 +166,32 @@ interface AthenaGatewayHookResult {
     baseUrl: string;
 }
 
-export { type AthenaConditionValue as A, type BackendConfig as B, type BackendType as a, type AthenaConditionArrayValue as b, type AthenaConditionOperator as c, type AthenaGatewayCallOptions as d, Backend as e, type AthenaGatewayHookConfig as f, type AthenaGatewayHookResult as g, type AthenaDeletePayload as h, type AthenaFetchPayload as i, type AthenaGatewayResponse as j, type AthenaInsertPayload as k, type AthenaUpdatePayload as l };
+interface AthenaGatewayErrorInput {
+    code: AthenaGatewayErrorCode;
+    message: string;
+    status?: number;
+    endpoint?: AthenaGatewayEndpointPath;
+    method?: AthenaGatewayMethod;
+    requestId?: string;
+    hint?: string;
+    cause?: string;
+}
+/**
+ * Canonical error for gateway failures.
+ * Holds request context and machine-readable classification.
+ */
+declare class AthenaGatewayError extends Error {
+    readonly code: AthenaGatewayErrorCode;
+    readonly status: number;
+    readonly endpoint?: AthenaGatewayEndpointPath;
+    readonly method?: AthenaGatewayMethod;
+    readonly requestId?: string;
+    readonly hint?: string;
+    readonly causeDetail?: string;
+    constructor(input: AthenaGatewayErrorInput);
+    toDetails(): AthenaGatewayErrorDetails;
+    static fromResponse<T>(response: AthenaGatewayResponse<T>, fallback: Omit<AthenaGatewayErrorInput, 'code' | 'message' | 'status'>): AthenaGatewayError;
+}
+declare function isAthenaGatewayError(error: unknown): error is AthenaGatewayError;
+
+export { type AthenaConditionValue as A, type BackendConfig as B, type BackendType as a, type AthenaConditionArrayValue as b, type AthenaConditionOperator as c, type AthenaGatewayCallOptions as d, type AthenaGatewayErrorDetails as e, type AthenaRpcCallOptions as f, AthenaGatewayError as g, type AthenaGatewayErrorCode as h, type AthenaRpcFilter as i, type AthenaRpcFilterOperator as j, type AthenaRpcOrder as k, type AthenaRpcPayload as l, Backend as m, isAthenaGatewayError as n, type AthenaGatewayHookConfig as o, type AthenaGatewayHookResult as p, type AthenaDeletePayload as q, type AthenaFetchPayload as r, type AthenaGatewayResponse as s, type AthenaInsertPayload as t, type AthenaUpdatePayload as u };