@xylex-group/athena 2.1.2 → 2.4.0

package/dist/react.cjs

@@ -65,8 +65,74 @@ function isAthenaGatewayError(error) {
   return error instanceof AthenaGatewayError;
 }
 
+// src/gateway/url.ts
+var ATHENA_DEFAULT_BASE_URL = "https://athena-db.com";
+function describeReceivedValue(value) {
+  if (value === void 0) return "undefined";
+  if (value === null) return "null";
+  if (typeof value === "string") {
+    return value.trim().length > 0 ? JSON.stringify(value) : "an empty string";
+  }
+  return `${typeof value} ${JSON.stringify(value)}`;
+}
+function invalidBaseUrlError(message, hint) {
+  return new AthenaGatewayError({
+    code: "INVALID_URL",
+    message,
+    status: 0,
+    hint
+  });
+}
+function normalizeAthenaGatewayBaseUrl(input, options = {}) {
+  const label = options.label ?? "Athena gateway base URL";
+  const candidate = input ?? options.defaultBaseUrl;
+  if (candidate === void 0 || candidate === null) {
+    throw invalidBaseUrlError(
+      `${label} must be a non-empty absolute http(s) URL. Received ${describeReceivedValue(input)}.`,
+      'Set ATHENA_URL (or pass createClient(url, ...)) to a full URL such as "https://mirror3.athena-db.com".'
+    );
+  }
+  const trimmed = candidate.trim();
+  if (!trimmed) {
+    throw invalidBaseUrlError(
+      `${label} must be a non-empty absolute http(s) URL. Received ${describeReceivedValue(candidate)}.`,
+      'Set ATHENA_URL (or pass createClient(url, ...)) to a full URL such as "https://mirror3.athena-db.com".'
+    );
+  }
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw invalidBaseUrlError(
+      `${label} must be a valid absolute http(s) URL. Received ${describeReceivedValue(candidate)}.`,
+      'Use a full URL including the protocol, for example "https://mirror3.athena-db.com".'
+    );
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw invalidBaseUrlError(
+      `${label} must use http or https. Received ${JSON.stringify(trimmed)}.`,
+      'Use an Athena gateway URL such as "https://mirror3.athena-db.com".'
+    );
+  }
+  if (parsed.search || parsed.hash) {
+    throw invalidBaseUrlError(
+      `${label} must not include query parameters or hash fragments. Received ${JSON.stringify(trimmed)}.`,
+      'Pass only the base URL. Endpoint paths such as "/gateway/fetch" are appended by the SDK.'
+    );
+  }
+  return parsed.toString().replace(/\/+$/, "");
+}
+function buildAthenaGatewayUrl(baseUrl, path) {
+  if (!path.startsWith("/")) {
+    throw invalidBaseUrlError(
+      `Athena gateway path must start with "/". Received ${JSON.stringify(path)}.`,
+      'Use a leading slash such as "/gateway/fetch" or "/".'
+    );
+  }
+  return `${baseUrl}${path}`;
+}
+
 // src/gateway/client.ts
-var DEFAULT_BASE_URL = "https://athena-db.com";
 var DEFAULT_CLIENT = "railway_direct";
 var FALLBACK_SDK_VERSION = "1.3.0";
 var SDK_NAME = "xylex-group/athena";
@@ -93,23 +159,39 @@ function normalizeHeaderValue(value) {
 function isRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function resolveStructuredErrorPayload(payload) {
+  if (!isRecord(payload)) return null;
+  return isRecord(payload.error) ? payload.error : payload;
+}
 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];
+  const structuredPayload = resolveStructuredErrorPayload(payload);
+  if (structuredPayload) {
+    const messageCandidates = [structuredPayload.message, structuredPayload.error, structuredPayload.details];
     for (const candidate of messageCandidates) {
-      if (typeof candidate === "string" && candidate.trim().length > 0) {
-        return candidate.trim();
-      }
+      const resolved = nonEmptyString(candidate);
+      if (resolved) return resolved;
     }
   }
-  if (typeof payload === "string" && payload.trim().length > 0) {
-    return payload.trim();
-  }
+  const rawMessage = nonEmptyString(payload);
+  if (rawMessage) return rawMessage;
   return fallback;
 }
+function resolveErrorHint(payload) {
+  const structuredPayload = resolveStructuredErrorPayload(payload);
+  return structuredPayload ? nonEmptyString(structuredPayload.hint) : void 0;
+}
+function resolveStatusText(response, payload) {
+  const rawStatusText = nonEmptyString(response.statusText);
+  if (rawStatusText) return rawStatusText;
+  const payloadRecord = isRecord(payload) ? payload : null;
+  return payloadRecord ? nonEmptyString(payloadRecord.statusText) ?? null : null;
+}
 function detailsFromError(error) {
   return error.toDetails();
 }
@@ -247,9 +329,168 @@ function buildHeaders(config, options) {
   });
   return headers;
 }
+function toInvalidUrlResponse(error, endpoint, method) {
+  const message = error instanceof Error ? error.message : String(error);
+  const gatewayError = error instanceof AthenaGatewayError ? error : new AthenaGatewayError({
+    code: "INVALID_URL",
+    message,
+    status: 0,
+    endpoint,
+    method,
+    cause: message,
+    hint: "Set ATHENA_URL to a full http(s) URL before running queries."
+  });
+  return {
+    ok: false,
+    status: 0,
+    statusText: null,
+    data: null,
+    error: gatewayError.message,
+    errorDetails: detailsFromError(
+      new AthenaGatewayError({
+        code: gatewayError.code,
+        message: gatewayError.message,
+        status: gatewayError.status,
+        endpoint,
+        method,
+        requestId: gatewayError.requestId,
+        hint: gatewayError.hint,
+        cause: gatewayError.causeDetail
+      })
+    ),
+    raw: null
+  };
+}
+function resolveGatewayBaseUrl(input) {
+  return normalizeAthenaGatewayBaseUrl(input, {
+    defaultBaseUrl: ATHENA_DEFAULT_BASE_URL
+  });
+}
+function resolveProbePath(path) {
+  if (!path) return "/";
+  if (!path.startsWith("/")) {
+    throw new AthenaGatewayError({
+      code: "INVALID_URL",
+      message: `Athena gateway probe path must start with "/". Received ${JSON.stringify(path)}.`,
+      status: 0,
+      hint: 'Use a leading slash such as "/" or "/health".'
+    });
+  }
+  return path;
+}
+function mergeConnectionHeaders(baseHeaders, headers) {
+  const merged = {
+    ...baseHeaders,
+    ...headers ?? {}
+  };
+  if (!merged["X-Athena-Sdk"] && !merged["x-athena-sdk"]) {
+    merged["X-Athena-Sdk"] = SDK_HEADER_VALUE;
+  }
+  return merged;
+}
+async function performConnectionCheck(baseUrl, requestHeaders, options) {
+  const path = resolveProbePath(options?.path);
+  const url = buildAthenaGatewayUrl(baseUrl, path);
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      headers: mergeConnectionHeaders(requestHeaders, options?.headers),
+      signal: options?.signal
+    });
+    const rawText = await response.text();
+    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 probe returned malformed JSON",
+        status: response.status,
+        method: "GET",
+        requestId,
+        hint: "Verify the gateway response body is valid JSON.",
+        cause: rawText.slice(0, 300)
+      });
+      return {
+        ok: false,
+        reachable: true,
+        status: response.status,
+        statusText: resolveStatusText(response, parsedBody.parsed),
+        baseUrl,
+        url,
+        error: invalidJsonError.message,
+        errorDetails: detailsFromError(invalidJsonError),
+        raw: parsedBody.parsed
+      };
+    }
+    const parsed = parsedBody.parsed;
+    if (!response.ok) {
+      const httpError = new AthenaGatewayError({
+        code: "HTTP_ERROR",
+        message: resolveErrorMessage(
+          parsed,
+          `Athena gateway GET ${path} failed with status ${response.status}`
+        ),
+        status: response.status,
+        method: "GET",
+        requestId,
+        hint: resolveErrorHint(parsed)
+      });
+      return {
+        ok: false,
+        reachable: true,
+        status: response.status,
+        statusText: resolveStatusText(response, parsed),
+        baseUrl,
+        url,
+        error: httpError.message,
+        errorDetails: detailsFromError(httpError),
+        raw: parsed
+      };
+    }
+    return {
+      ok: true,
+      reachable: true,
+      status: response.status,
+      statusText: resolveStatusText(response, parsed),
+      baseUrl,
+      url,
+      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 probing Athena gateway ${url}: ${message}`,
+      method: "GET",
+      cause: message,
+      hint: "Check gateway URL, DNS, and network reachability."
+    });
+    return {
+      ok: false,
+      reachable: false,
+      status: 0,
+      statusText: null,
+      baseUrl,
+      url,
+      error: networkError.message,
+      errorDetails: detailsFromError(networkError),
+      raw: null
+    };
+  }
+}
 async function callAthena(config, endpoint, method, payload, options) {
-  const baseUrl = (options?.baseUrl ?? config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
-  const url = `${baseUrl}${endpoint}`;
+  let baseUrl;
+  try {
+    baseUrl = resolveGatewayBaseUrl(options?.baseUrl ?? config.baseUrl);
+  } catch (error) {
+    return toInvalidUrlResponse(error, endpoint, method);
+  }
+  const url = buildAthenaGatewayUrl(baseUrl, endpoint);
   const headers = buildHeaders(config, options);
   try {
     const requestInit = {
@@ -280,6 +521,7 @@ async function callAthena(config, endpoint, method, payload, options) {
       return {
         ok: false,
         status: response.status,
+        statusText: resolveStatusText(response, parsedBody.parsed),
         data: null,
         error: invalidJsonError.message,
         errorDetails: detailsFromError(invalidJsonError),
@@ -298,11 +540,13 @@ async function callAthena(config, endpoint, method, payload, options) {
         status: response.status,
         endpoint,
         method,
-        requestId
+        requestId,
+        hint: resolveErrorHint(parsed)
       });
       return {
         ok: false,
         status: response.status,
+        statusText: resolveStatusText(response, parsed),
         data: null,
         error: httpError.message,
         errorDetails: detailsFromError(httpError),
@@ -314,6 +558,7 @@ async function callAthena(config, endpoint, method, payload, options) {
     return {
       ok: true,
       status: response.status,
+      statusText: resolveStatusText(response, parsed),
       data: payloadData ?? null,
       count: payloadCount,
       error: void 0,
@@ -333,6 +578,7 @@ async function callAthena(config, endpoint, method, payload, options) {
     return {
       ok: false,
       status: 0,
+      statusText: null,
       data: null,
       error: networkError.message,
       errorDetails: detailsFromError(networkError),
@@ -341,32 +587,44 @@ async function callAthena(config, endpoint, method, payload, options) {
   }
 }
 function createAthenaGatewayClient(config = {}) {
+  const normalizedBaseUrl = resolveGatewayBaseUrl(config.baseUrl);
+  const normalizedConfig = {
+    ...config,
+    baseUrl: normalizedBaseUrl
+  };
   return {
-    baseUrl: (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, ""),
+    baseUrl: normalizedBaseUrl,
     buildHeaders(options) {
-      return buildHeaders(config, options);
+      return buildHeaders(normalizedConfig, options);
+    },
+    verifyConnection(options) {
+      return performConnectionCheck(
+        normalizedBaseUrl,
+        buildHeaders(normalizedConfig),
+        options
+      );
     },
     fetchGateway(payload, options) {
-      return callAthena(config, "/gateway/fetch", "POST", payload, options);
+      return callAthena(normalizedConfig, "/gateway/fetch", "POST", payload, options);
     },
     insertGateway(payload, options) {
-      return callAthena(config, "/gateway/insert", "PUT", payload, options);
+      return callAthena(normalizedConfig, "/gateway/insert", "PUT", payload, options);
     },
     updateGateway(payload, options) {
-      return callAthena(config, "/gateway/update", "POST", payload, options);
+      return callAthena(normalizedConfig, "/gateway/update", "POST", payload, options);
     },
     deleteGateway(payload, options) {
-      return callAthena(config, "/gateway/delete", "DELETE", payload, options);
+      return callAthena(normalizedConfig, "/gateway/delete", "DELETE", payload, options);
     },
     rpcGateway(payload, options) {
       if (options?.get) {
         const endpoint = buildRpcGetEndpoint(payload);
-        return callAthena(config, endpoint, "GET", null, options);
+        return callAthena(normalizedConfig, endpoint, "GET", null, options);
       }
-      return callAthena(config, "/gateway/rpc", "POST", payload, options);
+      return callAthena(normalizedConfig, "/gateway/rpc", "POST", payload, options);
     },
     queryGateway(payload, options) {
-      return callAthena(config, "/gateway/query", "POST", payload, options);
+      return callAthena(normalizedConfig, "/gateway/query", "POST", payload, options);
     }
   };
 }