@xylex-group/athena 1.1.2 → 1.2.0

package/dist/index.cjs

@@ -1,19 +1,195 @@
 'use strict';
 
+// src/gateway/errors.ts
+var AthenaGatewayError = class _AthenaGatewayError extends Error {
+  code;
+  status;
+  endpoint;
+  method;
+  requestId;
+  hint;
+  causeDetail;
+  constructor(input) {
+    super(input.message);
+    this.name = "AthenaGatewayError";
+    this.code = input.code;
+    this.status = input.status ?? 0;
+    this.endpoint = input.endpoint;
+    this.method = input.method;
+    this.requestId = input.requestId;
+    this.hint = input.hint;
+    this.causeDetail = input.cause;
+  }
+  toDetails() {
+    return {
+      code: this.code,
+      message: this.message,
+      status: this.status,
+      endpoint: this.endpoint,
+      method: this.method,
+      requestId: this.requestId,
+      hint: this.hint,
+      cause: this.causeDetail
+    };
+  }
+  static fromResponse(response, fallback) {
+    const details = response.errorDetails;
+    if (details) {
+      return new _AthenaGatewayError({
+        code: details.code,
+        message: details.message,
+        status: details.status,
+        endpoint: details.endpoint ?? fallback.endpoint,
+        method: details.method ?? fallback.method,
+        requestId: details.requestId ?? fallback.requestId,
+        hint: details.hint,
+        cause: details.cause
+      });
+    }
+    return new _AthenaGatewayError({
+      code: "HTTP_ERROR",
+      message: response.error ?? "Gateway request failed",
+      status: response.status,
+      endpoint: fallback.endpoint,
+      method: fallback.method,
+      requestId: fallback.requestId
+    });
+  }
+};
+function isAthenaGatewayError(error) {
+  return error instanceof AthenaGatewayError;
+}
+
 // src/gateway/client.ts
 var DEFAULT_BASE_URL = "https://athena-db.com";
 var DEFAULT_CLIENT = "railway_direct";
-function parseResponseText(text) {
-  if (!text) return null;
+function parseResponseBody(rawText, contentType) {
+  if (!rawText) {
+    return { parsed: null, parseFailed: false };
+  }
+  const contentTypeSuggestsJson = contentType?.toLowerCase().includes("application/json") ?? false;
+  const looksJson = contentTypeSuggestsJson || rawText.startsWith("{") || rawText.startsWith("[");
+  if (!looksJson) {
+    return { parsed: rawText, parseFailed: false };
+  }
   try {
-    return JSON.parse(text);
+    return { parsed: JSON.parse(rawText), parseFailed: false };
   } catch {
-    return text;
+    return { parsed: rawText, parseFailed: true };
   }
 }
 function normalizeHeaderValue(value) {
   return value ? value : void 0;
 }
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function resolveRequestId(headers) {
+  return headers.get("x-request-id") ?? headers.get("x-correlation-id") ?? headers.get("x-athena-request-id") ?? void 0;
+}
+function resolveErrorMessage(payload, fallback) {
+  if (isRecord(payload)) {
+    const messageCandidates = [payload.error, payload.message, payload.details];
+    for (const candidate of messageCandidates) {
+      if (typeof candidate === "string" && candidate.trim().length > 0) {
+        return candidate.trim();
+      }
+    }
+  }
+  if (typeof payload === "string" && payload.trim().length > 0) {
+    return payload.trim();
+  }
+  return fallback;
+}
+function detailsFromError(error) {
+  return error.toDetails();
+}
+function toQueryScalar(value) {
+  if (value === null || value === void 0) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return Number.isFinite(value) ? String(value) : "null";
+  return String(value);
+}
+function toQueryArray(values) {
+  return `{${values.map(toQueryScalar).join(",")}}`;
+}
+function toRpcArgumentQueryValue(value) {
+  if (Array.isArray(value)) return toQueryArray(value);
+  if (value && typeof value === "object") return JSON.stringify(value);
+  return toQueryScalar(value);
+}
+function toRpcFilterQueryValue(filter) {
+  const value = filter.value;
+  switch (filter.operator) {
+    case "in": {
+      if (!Array.isArray(value)) {
+        throw new AthenaGatewayError({
+          code: "UNKNOWN_ERROR",
+          message: `RPC filter "${filter.column}" with operator "in" requires an array value`,
+          status: 0
+        });
+      }
+      return `in.${toQueryArray(value)}`;
+    }
+    case "is":
+      return `is.${toQueryScalar(value)}`;
+    case "eq":
+    case "neq":
+    case "gt":
+    case "gte":
+    case "lt":
+    case "lte":
+    case "like":
+    case "ilike":
+      return `${filter.operator}.${toQueryScalar(value)}`;
+  }
+}
+function buildRpcGetEndpoint(payload) {
+  const functionName = (payload.function_name ?? payload.function).trim();
+  if (!functionName) {
+    throw new AthenaGatewayError({
+      code: "UNKNOWN_ERROR",
+      message: "rpc requires a function name",
+      status: 0,
+      endpoint: "/gateway/rpc",
+      method: "GET"
+    });
+  }
+  const query = new URLSearchParams();
+  if (payload.schema) query.set("schema", payload.schema);
+  if (payload.select) query.set("select", payload.select);
+  if (payload.count) query.set("count", payload.count);
+  if (payload.head) query.set("head", "true");
+  if (typeof payload.limit === "number") query.set("limit", String(payload.limit));
+  if (typeof payload.offset === "number") query.set("offset", String(payload.offset));
+  if (payload.order?.column) {
+    query.set(
+      "order",
+      payload.order.ascending === false ? `${payload.order.column}.desc` : payload.order.column
+    );
+  }
+  if (payload.args) {
+    for (const [key, value] of Object.entries(payload.args)) {
+      query.set(key, toRpcArgumentQueryValue(value));
+    }
+  }
+  if (payload.filters?.length) {
+    for (const filter of payload.filters) {
+      if (payload.args && Object.prototype.hasOwnProperty.call(payload.args, filter.column)) {
+        throw new AthenaGatewayError({
+          code: "UNKNOWN_ERROR",
+          message: `RPC filter "${filter.column}" conflicts with RPC argument "${filter.column}" in GET mode`,
+          status: 0
+        });
+      }
+      query.set(filter.column, toRpcFilterQueryValue(filter));
+    }
+  }
+  const endpoint = `/rpc/${encodeURIComponent(functionName)}`;
+  const queryText = query.toString();
+  const withQuery = queryText ? `${endpoint}?${queryText}` : endpoint;
+  return withQuery;
+}
 function buildHeaders(config, options) {
   const mergedStripNulls = options?.stripNulls ?? true;
   const extraHeaders = {
@@ -66,31 +242,90 @@ async function callAthena(config, endpoint, method, payload, options) {
   const url = `${baseUrl}${endpoint}`;
   const headers = buildHeaders(config, options);
   try {
-    const response = await fetch(url, {
+    const requestInit = {
       method,
-      headers,
-      body: JSON.stringify(payload)
-    });
+      headers
+    };
+    if (method !== "GET") {
+      requestInit.body = JSON.stringify(payload);
+    }
+    const response = await fetch(url, requestInit);
     const rawText = await response.text();
-    const parsed = parseResponseText(rawText ?? "");
-    const parsedPayload = parsed;
-    const parsedError = parsedPayload && typeof parsedPayload === "object" ? parsedPayload.error ?? parsedPayload.message : void 0;
-    const hasError = !response.ok && typeof parsedError === "string" && parsedError.length > 0 ? parsedError : void 0;
-    const payloadData = parsedPayload && typeof parsedPayload === "object" && "data" in parsedPayload ? parsedPayload.data : parsed;
+    const requestId = resolveRequestId(response.headers);
+    const parsedBody = parseResponseBody(
+      rawText ?? "",
+      response.headers.get("content-type")
+    );
+    if (parsedBody.parseFailed) {
+      const invalidJsonError = new AthenaGatewayError({
+        code: "INVALID_JSON",
+        message: "Gateway returned malformed JSON",
+        status: response.status,
+        endpoint,
+        method,
+        requestId,
+        hint: "Verify the gateway response body is valid JSON.",
+        cause: rawText.slice(0, 300)
+      });
+      return {
+        ok: false,
+        status: response.status,
+        data: null,
+        error: invalidJsonError.message,
+        errorDetails: detailsFromError(invalidJsonError),
+        raw: parsedBody.parsed
+      };
+    }
+    const parsed = parsedBody.parsed;
+    const parsedPayload = isRecord(parsed) ? parsed : null;
+    if (!response.ok) {
+      const httpError = new AthenaGatewayError({
+        code: "HTTP_ERROR",
+        message: resolveErrorMessage(
+          parsed,
+          `Athena gateway ${method} ${endpoint} failed with status ${response.status}`
+        ),
+        status: response.status,
+        endpoint,
+        method,
+        requestId
+      });
+      return {
+        ok: false,
+        status: response.status,
+        data: null,
+        error: httpError.message,
+        errorDetails: detailsFromError(httpError),
+        raw: parsed
+      };
+    }
+    const payloadData = parsedPayload && "data" in parsedPayload ? parsedPayload.data : parsed;
+    const payloadCount = parsedPayload && "count" in parsedPayload ? typeof parsedPayload.count === "number" || parsedPayload.count === null ? parsedPayload.count : void 0 : void 0;
     return {
-      ok: response.ok,
+      ok: true,
       status: response.status,
       data: payloadData ?? null,
-      error: hasError,
+      count: payloadCount,
+      error: void 0,
+      errorDetails: null,
       raw: parsed
     };
   } catch (callError) {
     const message = callError instanceof Error ? callError.message : String(callError);
+    const networkError = new AthenaGatewayError({
+      code: "NETWORK_ERROR",
+      message: `Network error while calling ${method} ${endpoint}: ${message}`,
+      endpoint,
+      method,
+      cause: message,
+      hint: "Check gateway URL, DNS, and network reachability."
+    });
     return {
       ok: false,
       status: 0,
       data: null,
-      error: message,
+      error: networkError.message,
+      errorDetails: detailsFromError(networkError),
       raw: null
     };
   }
@@ -112,19 +347,34 @@ function createAthenaGatewayClient(config = {}) {
     },
     deleteGateway(payload, options) {
       return callAthena(config, "/gateway/delete", "DELETE", payload, options);
+    },
+    rpcGateway(payload, options) {
+      if (options?.get) {
+        const endpoint = buildRpcGetEndpoint(payload);
+        return callAthena(config, endpoint, "GET", null, options);
+      }
+      return callAthena(config, "/gateway/rpc", "POST", payload, options);
+    },
+    queryGateway(payload, options) {
+      return callAthena(config, "/gateway/query", "POST", payload, options);
     }
   };
 }
 
-// src/supabase.ts
+// src/client.ts
 var DEFAULT_COLUMNS = "*";
 function formatResult(response) {
-  return {
+  const result = {
     data: response.data ?? null,
     error: response.error ?? null,
+    errorDetails: response.errorDetails ?? null,
     status: response.status,
     raw: response.raw
   };
+  if (response.count !== void 0) {
+    result.count = response.count;
+  }
+  return result;
 }
 function toSingleResult(response) {
   const payload = response.data;
@@ -274,6 +524,133 @@ function createFilterMethods(state, addCondition, self) {
     }
   };
 }
+function toRpcSelect(columns) {
+  if (!columns) return void 0;
+  return Array.isArray(columns) ? columns.join(",") : columns;
+}
+function createRpcFilterMethods(filters, self) {
+  const addFilter = (operator, column, value) => {
+    filters.push({ column, operator, value });
+  };
+  return {
+    eq(column, value) {
+      addFilter("eq", column, value);
+      return self;
+    },
+    neq(column, value) {
+      addFilter("neq", column, value);
+      return self;
+    },
+    gt(column, value) {
+      addFilter("gt", column, value);
+      return self;
+    },
+    gte(column, value) {
+      addFilter("gte", column, value);
+      return self;
+    },
+    lt(column, value) {
+      addFilter("lt", column, value);
+      return self;
+    },
+    lte(column, value) {
+      addFilter("lte", column, value);
+      return self;
+    },
+    like(column, value) {
+      addFilter("like", column, value);
+      return self;
+    },
+    ilike(column, value) {
+      addFilter("ilike", column, value);
+      return self;
+    },
+    is(column, value) {
+      addFilter("is", column, value);
+      return self;
+    },
+    in(column, values) {
+      addFilter("in", column, values);
+      return self;
+    }
+  };
+}
+function createRpcBuilder(functionName, args, baseOptions, client) {
+  const state = {
+    filters: []
+  };
+  let selectedColumns;
+  let selectedOptions;
+  let promise = null;
+  const executeRpc = async (columns, options) => {
+    const mergedOptions = mergeOptions(baseOptions, options);
+    const payload = {
+      function: functionName,
+      args,
+      schema: mergedOptions?.schema,
+      select: toRpcSelect(columns),
+      filters: state.filters.length ? [...state.filters] : void 0,
+      count: mergedOptions?.count,
+      head: mergedOptions?.head,
+      limit: state.limit,
+      offset: state.offset,
+      order: state.order
+    };
+    const response = await client.rpcGateway(payload, mergedOptions);
+    return formatResult(response);
+  };
+  const run = (columns, options) => {
+    const payloadColumns = columns ?? selectedColumns;
+    const payloadOptions = options ?? selectedOptions;
+    if (!promise) {
+      promise = executeRpc(payloadColumns, payloadOptions);
+    }
+    return promise;
+  };
+  const builder = {};
+  const filterMethods = createRpcFilterMethods(state.filters, builder);
+  Object.assign(builder, filterMethods, {
+    select(columns = selectedColumns, options) {
+      selectedColumns = columns;
+      selectedOptions = options ?? selectedOptions;
+      return run(columns, options);
+    },
+    async single(columns, options) {
+      const result = await run(columns, options);
+      return toSingleResult(result);
+    },
+    maybeSingle(columns, options) {
+      return builder.single(columns, options);
+    },
+    order(column, options) {
+      state.order = { column, ascending: options?.ascending ?? true };
+      return builder;
+    },
+    limit(count) {
+      state.limit = count;
+      return builder;
+    },
+    offset(count) {
+      state.offset = count;
+      return builder;
+    },
+    range(from, to) {
+      state.offset = from;
+      state.limit = to - from + 1;
+      return builder;
+    },
+    then(onfulfilled, onrejected) {
+      return run(selectedColumns, selectedOptions).then(onfulfilled, onrejected);
+    },
+    catch(onrejected) {
+      return run(selectedColumns, selectedOptions).catch(onrejected);
+    },
+    finally(onfinally) {
+      return run(selectedColumns, selectedOptions).finally(onfinally);
+    }
+  });
+  return builder;
+}
 function createTableBuilder(tableName, client) {
   const state = {
     conditions: []
@@ -468,6 +845,16 @@ function createTableBuilder(tableName, client) {
   });
   return builder;
 }
+function createQueryBuilder(client) {
+  return async function query(query, options) {
+    const normalizedQuery = query.trim();
+    if (!normalizedQuery) {
+      throw new Error("query requires a non-empty string");
+    }
+    const response = await client.queryGateway({ query: normalizedQuery }, options);
+    return formatResult(response);
+  };
+}
 function createClientFromConfig(config) {
   const gateway = createAthenaGatewayClient({
     baseUrl: config.baseUrl,
@@ -479,7 +866,20 @@ function createClientFromConfig(config) {
   return {
     from(table) {
       return createTableBuilder(table, gateway);
-    }
+    },
+    rpc(fn, args, options) {
+      const normalizedFn = fn.trim();
+      if (!normalizedFn) {
+        throw new Error("rpc requires a function name");
+      }
+      return createRpcBuilder(
+        normalizedFn,
+        args,
+        options,
+        gateway
+      );
+    },
+    query: createQueryBuilder(gateway)
   };
 }
 var DEFAULT_BACKEND = { type: "athena" };
@@ -487,61 +887,66 @@ function toBackendConfig(b) {
   if (!b) return DEFAULT_BACKEND;
   return typeof b === "string" ? { type: b } : b;
 }
-var AthenaClient = {
-  builder() {
-    let url;
-    let key;
-    let backend = DEFAULT_BACKEND;
-    let clientName;
-    let headers;
-    const builder = {
-      url(u) {
-        url = u;
-        return builder;
-      },
-      key(k) {
-        key = k;
-        return builder;
-      },
-      backend(b) {
-        backend = toBackendConfig(b);
-        return builder;
-      },
-      client(c) {
-        clientName = c;
-        return builder;
-      },
-      headers(h) {
-        headers = h;
-        return builder;
-      },
-      healthTracking(enabled) {
-        return builder;
-      },
-      build() {
-        if (!url || !key) {
-          throw new Error("AthenaClient requires url and key; call .url() and .key() before .build()");
-        }
-        return createClientFromConfig({
-          baseUrl: url,
-          apiKey: key,
-          client: clientName,
-          backend,
-          headers});
-      }
-    };
-    return builder;
-  },
-  /** Build client from env: ATHENA_SUPABASE_URL, ATHENA_SUPABASE_KEY (or SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY) */
-  fromSupabaseEnv() {
-    const url = process.env.ATHENA_SUPABASE_URL ?? process.env.SUPABASE_URL;
-    const key = process.env.ATHENA_SUPABASE_KEY ?? process.env.SUPABASE_SERVICE_ROLE_KEY;
+var AthenaClientBuilderImpl = class {
+  baseUrl;
+  apiKey;
+  backendConfig = DEFAULT_BACKEND;
+  clientName;
+  defaultHeaders;
+  isHealthTrackingEnabled = false;
+  url(url) {
+    this.baseUrl = url;
+    return this;
+  }
+  key(apiKey) {
+    this.apiKey = apiKey;
+    return this;
+  }
+  backend(backend) {
+    this.backendConfig = toBackendConfig(backend);
+    return this;
+  }
+  client(clientName) {
+    this.clientName = clientName;
+    return this;
+  }
+  headers(headers) {
+    this.defaultHeaders = headers;
+    return this;
+  }
+  healthTracking(enabled) {
+    this.isHealthTrackingEnabled = enabled;
+    return this;
+  }
+  build() {
+    if (!this.baseUrl || !this.apiKey) {
+      throw new Error("AthenaClient requires url and key; call .url() and .key() before .build()");
+    }
+    return createClientFromConfig({
+      baseUrl: this.baseUrl,
+      apiKey: this.apiKey,
+      client: this.clientName,
+      backend: this.backendConfig,
+      headers: this.defaultHeaders,
+      healthTracking: this.isHealthTrackingEnabled
+    });
+  }
+};
+var AthenaClient = class _AthenaClient {
+  /** Create a fluent builder for a strongly-typed Athena SDK client. */
+  static builder() {
+    return new AthenaClientBuilderImpl();
+  }
+  /** Build a client from process environment variables. */
+  static fromEnvironment() {
+    const url = process.env.ATHENA_URL ?? process.env.ATHENA_GATEWAY_URL;
+    const key = process.env.ATHENA_API_KEY ?? process.env.ATHENA_GATEWAY_API_KEY;
     if (!url || !key) {
       throw new Error(
-        "ATHENA_SUPABASE_URL and ATHENA_SUPABASE_KEY (or SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY) are required"
+        "ATHENA_URL and ATHENA_API_KEY (or ATHENA_GATEWAY_URL and ATHENA_GATEWAY_API_KEY) are required"
       );
     }
-    return AthenaClient.builder().backend({ type: "supabase" }).url(url).key(key).build();
+    return _AthenaClient.builder().url(url).key(key).build();
   }
 };
 function createClient(url, apiKey, options) {
@@ -554,14 +959,15 @@ function createClient(url, apiKey, options) {
 // src/gateway/types.ts
 var Backend = {
   Athena: { type: "athena" },
-  Supabase: { type: "supabase" },
   Postgrest: { type: "postgrest" },
   PostgreSQL: { type: "postgresql" },
   ScyllaDB: { type: "scylladb" }
 };
 
 exports.AthenaClient = AthenaClient;
+exports.AthenaGatewayError = AthenaGatewayError;
 exports.Backend = Backend;
 exports.createClient = createClient;
+exports.isAthenaGatewayError = isAthenaGatewayError;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map