@xylex-group/athena 2.3.0 → 2.4.1

package/dist/cli/index.cjs

@@ -499,6 +499,7 @@ function classifyKind(status, code, message) {
   if (status === 404 || hasNotFoundPattern) return "not_found";
   if (status === 401 || status === 403 || hasAuthPattern) return "auth";
   if (status === 429 || hasRateLimitPattern) return "rate_limit";
+  if (code === "INVALID_URL") return "validation";
   if (status === 400 || status === 422 || hasValidationPattern) return "validation";
   if (code === "NETWORK_ERROR" || status === 0 || status !== void 0 && status >= 500 || hasTransientPattern) {
     return "transient";
@@ -506,6 +507,9 @@ function classifyKind(status, code, message) {
   return "unknown";
 }
 function toAthenaErrorCode(kind, status, gatewayCode) {
+  if (gatewayCode === "INVALID_URL") {
+    return AthenaErrorCode.ValidationFailed;
+  }
   if (gatewayCode === "NETWORK_ERROR" || kind === "transient" && status === 0) {
     return AthenaErrorCode.NetworkUnavailable;
   }
@@ -659,6 +663,54 @@ function normalizeAthenaError(resultOrError, context) {
     raw: resultOrError
   };
 }
+function defaultShouldRetry(error) {
+  const normalized = normalizeAthenaError(error);
+  return normalized.kind === "transient" || normalized.kind === "rate_limit";
+}
+function computeDelayMs(attempt, error, config) {
+  const baseDelay = config.baseDelayMs;
+  const rawDelay = typeof config.backoff === "function" ? config.backoff(attempt, error) : config.backoff === "linear" ? baseDelay * attempt : baseDelay * Math.pow(2, attempt - 1);
+  const safeDelay = Number.isFinite(rawDelay) ? Math.max(0, rawDelay) : 0;
+  const clamped = Math.min(config.maxDelayMs, safeDelay);
+  const jitterFactor = typeof config.jitter === "number" ? Math.max(0, Math.min(1, config.jitter)) : config.jitter ? 0.2 : 0;
+  if (!jitterFactor) return clamped;
+  const deviation = clamped * jitterFactor;
+  const offset = (Math.random() * 2 - 1) * deviation;
+  return Math.max(0, clamped + offset);
+}
+function sleep(ms) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve3) => {
+    setTimeout(resolve3, ms);
+  });
+}
+async function withRetry(config, fn) {
+  const retries = Math.max(0, Math.trunc(config.retries));
+  const shouldRetry = config.shouldRetry ?? defaultShouldRetry;
+  const resolvedConfig = {
+    baseDelayMs: config.baseDelayMs ?? 100,
+    maxDelayMs: config.maxDelayMs ?? 1e4,
+    backoff: config.backoff ?? "exponential",
+    jitter: config.jitter ?? false
+  };
+  for (let attempts = 0; attempts <= retries; attempts += 1) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempts >= retries) {
+        throw error;
+      }
+      const currentAttempt = attempts + 1;
+      const retry = await shouldRetry(error, currentAttempt);
+      if (!retry) {
+        throw error;
+      }
+      const delay = computeDelayMs(currentAttempt, error, resolvedConfig);
+      await sleep(delay);
+    }
+  }
+  throw new Error("withRetry reached an unexpected state");
+}
 
 // src/generator/schema-selection.ts
 var DEFAULT_POSTGRES_SCHEMAS = ["public"];
@@ -1359,13 +1411,114 @@ function generateArtifactsFromSnapshot(snapshot, config) {
   return new ArtifactComposer(snapshot, normalizedConfig).compose();
 }
 
+// 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/cookies/cookie-utils.ts
+var SECURE_COOKIE_PREFIX = "__Secure-";
+function parseCookies(cookieHeader) {
+  const cookies = cookieHeader.split("; ");
+  const cookieMap = /* @__PURE__ */ new Map();
+  cookies.forEach((cookie) => {
+    const [name, value] = cookie.split(/=(.*)/s);
+    cookieMap.set(name, value);
+  });
+  return cookieMap;
+}
+var getSessionCookie = (request, config) => {
+  const cookies = (request instanceof Headers || !("headers" in request) ? request : request.headers).get("cookie");
+  if (!cookies) {
+    return null;
+  }
+  const { cookieName = "session_token", cookiePrefix = "athena-auth" } = {};
+  const parsedCookie = parseCookies(cookies);
+  const getCookie = (name) => parsedCookie.get(name) || parsedCookie.get(`${SECURE_COOKIE_PREFIX}${name}`);
+  const sessionToken = getCookie(`${cookiePrefix}.${cookieName}`) || getCookie(`${cookiePrefix}-${cookieName}`);
+  if (sessionToken) {
+    return sessionToken;
+  }
+  return null;
+};
+
+// package.json
+var package_default = {
+  version: "2.4.1"
+};
+
+// src/sdk-version.ts
+var PACKAGE_VERSION = package_default.version;
+function buildSdkHeaderValue(sdkName) {
+  return `${sdkName} ${PACKAGE_VERSION}`;
+}
+
 // 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";
-var SDK_VERSION = typeof process !== "undefined" && process?.env?.npm_package_version ? process.env.npm_package_version : FALLBACK_SDK_VERSION;
-var SDK_HEADER_VALUE = `${SDK_NAME} ${SDK_VERSION}`;
+var SDK_HEADER_VALUE = buildSdkHeaderValue(SDK_NAME);
 function parseResponseBody(rawText, contentType) {
   if (!rawText) {
     return { parsed: null, parseFailed: false };
@@ -1384,6 +1537,37 @@ function parseResponseBody(rawText, contentType) {
 function normalizeHeaderValue(value) {
   return value ? value : void 0;
 }
+function resolveHeaderValue(headers, candidates) {
+  for (const candidate of candidates) {
+    const direct = normalizeHeaderValue(headers[candidate]);
+    if (direct) return direct;
+  }
+  const loweredCandidates = new Set(candidates.map((candidate) => candidate.toLowerCase()));
+  for (const [key, value] of Object.entries(headers)) {
+    if (!loweredCandidates.has(key.toLowerCase())) {
+      continue;
+    }
+    const normalized = normalizeHeaderValue(value);
+    if (normalized) return normalized;
+  }
+  return void 0;
+}
+function resolveBearerTokenFromAuthorizationHeader(headers) {
+  const authorization = resolveHeaderValue(headers, ["Authorization"]);
+  if (!authorization) {
+    return void 0;
+  }
+  const match = authorization.match(/^Bearer\s+(.+)$/i);
+  const token = match?.[1]?.trim();
+  return token ? token : void 0;
+}
+function resolveSessionTokenFromCookieHeader(headers) {
+  const cookie = resolveHeaderValue(headers, ["Cookie"]);
+  if (!cookie) {
+    return void 0;
+  }
+  return getSessionCookie(new Headers({ cookie })) ?? void 0;
+}
 function isRecord2(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -1501,7 +1685,7 @@ function buildRpcGetEndpoint(payload) {
           status: 0
         });
       }
-      query.set(filter.column, toRpcFilterQueryValue(filter));
+      query.append(filter.column, toRpcFilterQueryValue(filter));
     }
   }
   const endpoint = `/rpc/${encodeURIComponent(functionName)}`;
@@ -1547,6 +1731,20 @@ function buildHeaders(config, options) {
     headers["apikey"] = finalApiKey;
     headers["x-api-key"] = headers["x-api-key"] ?? finalApiKey;
   }
+  const explicitSessionToken = resolveHeaderValue(extraHeaders, [
+    "X-Athena-Auth-Session-Token"
+  ]);
+  const derivedSessionToken = explicitSessionToken ?? resolveSessionTokenFromCookieHeader(extraHeaders);
+  if (derivedSessionToken) {
+    headers["X-Athena-Auth-Session-Token"] = derivedSessionToken;
+  }
+  const explicitBearerToken = resolveHeaderValue(extraHeaders, [
+    "X-Athena-Auth-Bearer-Token"
+  ]);
+  const derivedBearerToken = explicitBearerToken ?? resolveBearerTokenFromAuthorizationHeader(extraHeaders);
+  if (derivedBearerToken) {
+    headers["X-Athena-Auth-Bearer-Token"] = derivedBearerToken;
+  }
   const athenaClientKeys = ["x-athena-client", "X-Athena-Client"];
   Object.entries(extraHeaders).forEach(([key, value]) => {
     if (athenaClientKeys.includes(key)) return;
@@ -1557,9 +1755,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 = {
@@ -1656,32 +2013,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);
     }
   };
 }
@@ -2010,10 +2379,8 @@ async function resolveReactEmailPayloadFields(input, fields, options) {
 
 // src/auth/client.ts
 var DEFAULT_AUTH_BASE_URL = "http://localhost:3001/api/auth";
-var FALLBACK_SDK_VERSION2 = "1.0.0";
 var SDK_NAME2 = "xylex-group/athena-auth";
-var SDK_VERSION2 = typeof process !== "undefined" && process?.env?.npm_package_version ? process.env.npm_package_version : FALLBACK_SDK_VERSION2;
-var SDK_HEADER_VALUE2 = `${SDK_NAME2} ${SDK_VERSION2}`;
+var SDK_HEADER_VALUE2 = buildSdkHeaderValue(SDK_NAME2);
 function normalizeBaseUrl(baseUrl) {
   return (baseUrl ?? DEFAULT_AUTH_BASE_URL).replace(/\/$/, "");
 }
@@ -3086,8 +3453,8 @@ function createAuthClient(config = {}) {
 // src/db/module.ts
 function createDbModule(input) {
   const db = {
-    from(table) {
-      return input.from(table);
+    from(table, options) {
+      return input.from(table, options);
     },
     select(table, columns, options) {
       return input.from(table).select(columns, options);
@@ -3192,7 +3559,19 @@ function buildGatewayCondition(operator, column, value) {
 function compileRelationToken(key, node) {
   const nested = compileSelectShape(node.select);
   const propertyKey = normalizeIdentifier(key, "select relation key");
-  const relationToken = normalizeIdentifier(node.via ?? propertyKey, "select relation token");
+  if (node.schema && node.via) {
+    throw new Error(
+      `findMany relation "${propertyKey}" cannot combine schema and via yet; use schema with the relation key, or use via without schema`
+    );
+  }
+  const relationTokenBase = normalizeIdentifier(node.via ?? propertyKey, "select relation token");
+  if (node.schema && relationTokenBase.includes(".")) {
+    throw new Error(
+      `findMany relation "${propertyKey}" already resolves to a qualified relation token; do not also set schema`
+    );
+  }
+  const relationSchema = node.schema?.trim();
+  const relationToken = relationSchema ? `${normalizeIdentifier(relationSchema, "select relation schema")}.${relationTokenBase}` : relationTokenBase;
   const alias = node.as?.trim() || (relationToken !== propertyKey ? propertyKey : "");
   const prefix = alias ? `${alias}:` : "";
   return `${prefix}${relationToken}(${nested})`;
@@ -3221,6 +3600,23 @@ function compileSelectShape(select) {
   }
   return tokens.join(",");
 }
+function selectShapeUsesRelationSchema(select) {
+  if (!isRecord5(select)) {
+    return false;
+  }
+  for (const rawValue of Object.values(select)) {
+    if (!isRelationSelectNode(rawValue)) {
+      continue;
+    }
+    if (typeof rawValue.schema === "string" && rawValue.schema.trim().length > 0) {
+      return true;
+    }
+    if (selectShapeUsesRelationSchema(rawValue.select)) {
+      return true;
+    }
+  }
+  return false;
+}
 function compileColumnWhere(column, input) {
   const normalizedColumn = normalizeIdentifier(column, "where column");
   if (!isRecord5(input)) {
@@ -3357,6 +3753,356 @@ function compileOrderBy(orderBy) {
   };
 }
 
+// src/gateway/structured-select.ts
+var IDENTIFIER_SEGMENT_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isIdentifierPath(value) {
+  const segments = value.split(".").map((segment) => segment.trim());
+  return segments.length > 1 && segments.every((segment) => IDENTIFIER_SEGMENT_PATTERN.test(segment));
+}
+function extractRelationHead(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) return "";
+  const aliasIndex = trimmed.indexOf(":");
+  const withoutAlias = aliasIndex >= 0 ? trimmed.slice(aliasIndex + 1).trim() : trimmed;
+  const modifierIndex = withoutAlias.indexOf("!");
+  return (modifierIndex >= 0 ? withoutAlias.slice(0, modifierIndex) : withoutAlias).trim();
+}
+function hasSchemaQualifiedRelationToken(select) {
+  let singleQuoted = false;
+  let doubleQuoted = false;
+  let tokenStart = 0;
+  for (let index = 0; index < select.length; index += 1) {
+    const char = select[index];
+    const next = index + 1 < select.length ? select[index + 1] : "";
+    if (singleQuoted) {
+      if (char === "'" && next === "'") {
+        index += 1;
+        continue;
+      }
+      if (char === "'") {
+        singleQuoted = false;
+      }
+      continue;
+    }
+    if (doubleQuoted) {
+      if (char === '"' && next === '"') {
+        index += 1;
+        continue;
+      }
+      if (char === '"') {
+        doubleQuoted = false;
+      }
+      continue;
+    }
+    if (char === "'") {
+      singleQuoted = true;
+      continue;
+    }
+    if (char === '"') {
+      doubleQuoted = true;
+      continue;
+    }
+    if (char === "(") {
+      const relationHead = extractRelationHead(select.slice(tokenStart, index));
+      if (isIdentifierPath(relationHead)) {
+        return true;
+      }
+      tokenStart = index + 1;
+      continue;
+    }
+    if (char === "," || char === ")") {
+      tokenStart = index + 1;
+    }
+  }
+  return false;
+}
+function toStructuredSelectString(columns) {
+  return Array.isArray(columns) ? columns.join(",") : columns;
+}
+function buildStructuredWhere(conditions) {
+  if (!conditions?.length) return void 0;
+  const where = {};
+  for (const condition of conditions) {
+    if (!condition.column) {
+      return null;
+    }
+    if (condition.value_cast !== void 0) {
+      return null;
+    }
+    const operand = condition.value;
+    const operator = condition.operator;
+    if (operator === "eq") {
+      if (operand === void 0) return null;
+    } else if (operator === "neq" || operator === "gt" || operator === "lt") {
+      if (operand === void 0) return null;
+    } else if (operator === "in") {
+      if (!Array.isArray(operand)) return null;
+    } else {
+      return null;
+    }
+    const existing = where[condition.column];
+    if (existing !== void 0 && (typeof existing !== "object" || existing === null || Array.isArray(existing))) {
+      return null;
+    }
+    const next = existing ?? {};
+    if (Object.prototype.hasOwnProperty.call(next, operator)) {
+      return null;
+    }
+    next[operator] = operand;
+    where[condition.column] = next;
+  }
+  return where;
+}
+function buildStructuredOrderBy(order) {
+  if (!order?.field) return void 0;
+  return {
+    [order.field]: order.direction === "descending" ? "desc" : "asc"
+  };
+}
+function buildStructuredSelectTransport(input) {
+  const select = toStructuredSelectString(input.columns).trim();
+  if (!select || select === "*") {
+    return null;
+  }
+  if (!hasSchemaQualifiedRelationToken(select)) {
+    return null;
+  }
+  if (input.count !== void 0 || input.head !== void 0) {
+    return {
+      error: "Schema-qualified nested select strings require structured select transport, which does not support count/head options in athena-js yet."
+    };
+  }
+  const where = buildStructuredWhere(input.conditions);
+  if (where === null) {
+    return {
+      error: "Schema-qualified nested select strings only support eq, neq, gt, lt, and in filters in athena-js structured select transport."
+    };
+  }
+  return {
+    select,
+    payload: {
+      table_name: input.tableName,
+      select,
+      where,
+      orderBy: buildStructuredOrderBy(input.order),
+      limit: input.limit,
+      offset: input.offset,
+      strip_nulls: input.stripNulls
+    }
+  };
+}
+
+// src/query-transport.ts
+function canUseFindManyAstTransport(state) {
+  return state.conditions.length === 0 && state.offset === void 0 && state.currentPage === void 0 && state.pageSize === void 0 && state.totalPages === void 0;
+}
+function toFindManyAstOrder(order) {
+  if (!order) {
+    return void 0;
+  }
+  return {
+    column: order.field,
+    ascending: order.direction !== "descending"
+  };
+}
+function isRecord6(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeFindManyAstColumnPredicate(value) {
+  if (!isRecord6(value)) {
+    return {
+      eq: value
+    };
+  }
+  const normalized = {};
+  for (const [key, operand] of Object.entries(value)) {
+    if (operand !== void 0) {
+      normalized[key] = operand;
+    }
+  }
+  return normalized;
+}
+function normalizeFindManyAstBooleanOperand(clause) {
+  const normalized = {};
+  for (const [column, value] of Object.entries(clause)) {
+    if (value === void 0) {
+      continue;
+    }
+    normalized[column] = normalizeFindManyAstColumnPredicate(value);
+  }
+  return normalized;
+}
+function normalizeFindManyAstWhere(where) {
+  if (!where || !isRecord6(where)) {
+    return where;
+  }
+  const normalized = {};
+  for (const [key, value] of Object.entries(where)) {
+    if (value === void 0) {
+      continue;
+    }
+    if (key === "or" && Array.isArray(value)) {
+      normalized.or = value.map(
+        (clause) => normalizeFindManyAstBooleanOperand(clause)
+      );
+      continue;
+    }
+    if (key === "not" && isRecord6(value)) {
+      normalized.not = normalizeFindManyAstBooleanOperand(
+        value
+      );
+      continue;
+    }
+    normalized[key] = normalizeFindManyAstColumnPredicate(value);
+  }
+  return normalized;
+}
+function predicateRequiresUuidQueryFallback(column, value) {
+  if (!isRecord6(value)) {
+    return shouldUseUuidTextComparison(column, value);
+  }
+  const eqValue = value.eq;
+  return eqValue !== void 0 && shouldUseUuidTextComparison(column, eqValue);
+}
+function booleanOperandRequiresUuidQueryFallback(clause) {
+  for (const [column, value] of Object.entries(clause)) {
+    if (value === void 0) {
+      continue;
+    }
+    if (predicateRequiresUuidQueryFallback(column, value)) {
+      return true;
+    }
+  }
+  return false;
+}
+function findManyAstWhereRequiresLegacyTransport(where) {
+  if (!where || !isRecord6(where)) {
+    return false;
+  }
+  for (const [key, value] of Object.entries(where)) {
+    if (value === void 0) {
+      continue;
+    }
+    if (key === "or" && Array.isArray(value)) {
+      if (value.some(
+        (clause) => booleanOperandRequiresUuidQueryFallback(clause)
+      )) {
+        return true;
+      }
+      continue;
+    }
+    if (key === "not" && isRecord6(value)) {
+      if (booleanOperandRequiresUuidQueryFallback(value)) {
+        return true;
+      }
+      continue;
+    }
+    if (predicateRequiresUuidQueryFallback(key, value)) {
+      return true;
+    }
+  }
+  return false;
+}
+function resolvePagination(input) {
+  let limit = input.limit;
+  let offset = input.offset;
+  if (limit === void 0 && input.pageSize !== void 0) {
+    limit = Math.max(0, Math.trunc(input.pageSize));
+  }
+  if (offset === void 0 && input.pageSize !== void 0 && input.currentPage !== void 0 && input.currentPage > 0) {
+    offset = (Math.trunc(input.currentPage) - 1) * Math.max(0, Math.trunc(input.pageSize));
+  }
+  return { limit, offset };
+}
+function hasTypedEqualityComparison(conditions) {
+  return conditions?.some(
+    (condition) => condition.operator === "eq" && (condition.value_cast !== void 0 || condition.column_cast !== void 0)
+  ) ?? false;
+}
+function createSelectTransportPlan(input) {
+  const conditions = input.state.conditions.length ? input.state.conditions.map((condition) => ({ ...condition })) : void 0;
+  const pagination = resolvePagination({
+    limit: input.state.limit,
+    offset: input.state.offset,
+    currentPage: input.state.currentPage,
+    pageSize: input.state.pageSize
+  });
+  const stripNulls = input.options?.stripNulls ?? true;
+  const structuredSelectTransport = buildStructuredSelectTransport({
+    tableName: input.tableName,
+    columns: input.columns,
+    conditions,
+    limit: pagination.limit,
+    offset: pagination.offset,
+    order: input.state.order,
+    stripNulls,
+    count: input.options?.count,
+    head: input.options?.head
+  });
+  if (structuredSelectTransport && "error" in structuredSelectTransport) {
+    throw new Error(structuredSelectTransport.error);
+  }
+  if (structuredSelectTransport) {
+    const { payload, select } = structuredSelectTransport;
+    return {
+      kind: "fetch",
+      payload,
+      debug: {
+        columns: select,
+        conditions,
+        limit: pagination.limit,
+        offset: pagination.offset,
+        order: input.state.order
+      }
+    };
+  }
+  if (hasTypedEqualityComparison(conditions) && !input.options?.head && !input.options?.count && conditions) {
+    const query = input.buildTypedSelectQuery({
+      tableName: input.tableName,
+      columns: input.columns,
+      conditions,
+      limit: input.state.limit,
+      offset: input.state.offset,
+      currentPage: input.state.currentPage,
+      pageSize: input.state.pageSize,
+      order: input.state.order
+    });
+    if (query) {
+      return {
+        kind: "query",
+        query,
+        payload: { query }
+      };
+    }
+  }
+  return {
+    kind: "fetch",
+    payload: {
+      table_name: input.tableName,
+      columns: input.columns,
+      conditions,
+      limit: input.state.limit,
+      offset: input.state.offset,
+      current_page: input.state.currentPage,
+      page_size: input.state.pageSize,
+      total_pages: input.state.totalPages,
+      sort_by: input.state.order,
+      strip_nulls: stripNulls,
+      count: input.options?.count,
+      head: input.options?.head
+    },
+    debug: {
+      columns: input.columns,
+      conditions,
+      limit: input.state.limit,
+      offset: input.state.offset,
+      currentPage: input.state.currentPage,
+      pageSize: input.state.pageSize,
+      order: input.state.order
+    }
+  };
+}
+
 // src/client.ts
 var DEFAULT_COLUMNS = "*";
 var SAFE_CAST_PATTERN = /^[a-z_][a-z0-9_]*(?:\[\])?$/i;
@@ -3371,18 +4117,6 @@ var QUERY_TRACE_STACK_SKIP_PATTERNS = [
   "node:internal",
   "internal/process"
 ];
-function canUseFindManyAstTransport(state) {
-  return state.conditions.length === 0 && state.offset === void 0 && state.currentPage === void 0 && state.pageSize === void 0 && state.totalPages === void 0;
-}
-function toFindManyAstOrder(order) {
-  if (!order) {
-    return void 0;
-  }
-  return {
-    column: order.field,
-    ascending: order.direction !== "descending"
-  };
-}
 function formatResult(response) {
   const result = {
     data: response.data ?? null,
@@ -3397,6 +4131,13 @@ function formatResult(response) {
   }
   return result;
 }
+var EXPERIMENTAL_READ_RETRY_CONFIG = {
+  retries: 2,
+  baseDelayMs: 100,
+  maxDelayMs: 1e3,
+  backoff: "exponential",
+  jitter: true
+};
 function attachNormalizedError(result, normalizedError) {
   Object.defineProperty(result, ATHENA_NORMALIZED_ERROR_KEY, {
     value: normalizedError,
@@ -3423,7 +4164,36 @@ function createResultFormatter(experimental) {
     return result;
   };
 }
-function isRecord6(value) {
+async function executeExperimentalRead(experimental, runner) {
+  if (!experimental?.retryReads) {
+    return runner();
+  }
+  let lastRetryableResult;
+  let lastRetrySignal = null;
+  try {
+    return await withRetry(
+      {
+        ...EXPERIMENTAL_READ_RETRY_CONFIG,
+        shouldRetry: (error) => error === lastRetrySignal || normalizeAthenaError(error).retryable
+      },
+      async () => {
+        const result = await runner();
+        if (result.error?.retryable) {
+          lastRetryableResult = result;
+          lastRetrySignal = result.error;
+          throw lastRetrySignal;
+        }
+        return result;
+      }
+    );
+  } catch (error) {
+    if (lastRetryableResult && error === lastRetrySignal) {
+      return lastRetryableResult;
+    }
+    throw error;
+  }
+}
+function isRecord7(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function firstNonEmptyString2(...values) {
@@ -3435,8 +4205,8 @@ function firstNonEmptyString2(...values) {
   return void 0;
 }
 function resolveStructuredErrorPayload2(raw) {
-  if (!isRecord6(raw)) return null;
-  return isRecord6(raw.error) ? raw.error : raw;
+  if (!isRecord7(raw)) return null;
+  return isRecord7(raw.error) ? raw.error : raw;
 }
 function resolveStructuredErrorDetails(payload, message) {
   if (!payload || !("details" in payload)) {
@@ -3452,7 +4222,7 @@ function resolveStructuredErrorDetails(payload, message) {
   return details;
 }
 function createResultError(response, result, normalized) {
-  const rawRecord = isRecord6(response.raw) ? response.raw : null;
+  const rawRecord = isRecord7(response.raw) ? response.raw : null;
   const payload = resolveStructuredErrorPayload2(response.raw);
   const message = firstNonEmptyString2(
     response.error,
@@ -3647,7 +4417,14 @@ function toSingleResult(response) {
 function mergeOptions(...options) {
   return options.reduce((acc, next) => {
     if (!next) return acc;
-    return { ...acc, ...next };
+    const merged = { ...acc ?? {}, ...next };
+    if (acc?.headers || next.headers) {
+      merged.headers = {
+        ...acc?.headers ?? {},
+        ...next.headers ?? {}
+      };
+    }
+    return merged;
   }, void 0);
 }
 function asAthenaJsonObject(value) {
@@ -3928,17 +4705,6 @@ function conditionToDebugSqlClause(condition) {
       return `TRUE /* unsupported condition: ${rawCondition} */`;
   }
 }
-function resolvePagination(input) {
-  let limit = input.limit;
-  let offset = input.offset;
-  if (limit === void 0 && input.pageSize !== void 0) {
-    limit = input.pageSize;
-  }
-  if (offset === void 0 && input.pageSize !== void 0 && input.currentPage !== void 0 && input.currentPage > 0) {
-    offset = (input.currentPage - 1) * input.pageSize;
-  }
-  return { limit, offset };
-}
 function appendOrderLimitOffset(sqlParts, order, limit, offset) {
   if (order?.field) {
     const direction = order.direction === "descending" ? "DESC" : "ASC";
@@ -4442,80 +5208,56 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
   );
   const runSelect = async (columns = DEFAULT_COLUMNS, options, executionState = snapshotState(), callsite) => {
     const resolvedTableName = resolveTableNameForCall(tableName, options?.schema);
-    const conditions = executionState.conditions.length ? executionState.conditions.map((condition) => ({ ...condition })) : void 0;
-    const hasTypedEqualityComparison = conditions?.some(
-      (condition) => condition.operator === "eq" && (condition.value_cast !== void 0 || condition.column_cast !== void 0)
-    ) ?? false;
-    if (hasTypedEqualityComparison && !options?.head && !options?.count && conditions) {
-      const query = buildTypedSelectQuery({
-        tableName: resolvedTableName,
-        columns,
-        conditions,
-        limit: executionState.limit,
-        offset: executionState.offset,
-        currentPage: executionState.currentPage,
-        pageSize: executionState.pageSize,
-        order: executionState.order
-      });
-      if (query) {
-        const payload2 = { query };
-        return executeWithQueryTrace(
+    const plan = createSelectTransportPlan({
+      tableName: resolvedTableName,
+      columns,
+      state: executionState,
+      options,
+      buildTypedSelectQuery
+    });
+    if (plan.kind === "query") {
+      return executeExperimentalRead(
+        experimental,
+        () => executeWithQueryTrace(
           tracer,
           {
             operation: "select",
             endpoint: "/gateway/query",
             table: resolvedTableName,
-            sql: query,
-            payload: payload2,
+            sql: plan.query,
+            payload: plan.payload,
             options
           },
           async () => {
-            const queryResponse = await client.queryGateway(payload2, options);
+            const queryResponse = await client.queryGateway(plan.payload, options);
             return formatGatewayResult(queryResponse, { table: resolvedTableName, operation: "select" });
           },
           callsite
-        );
-      }
+        )
+      );
     }
-    const payload = {
-      table_name: resolvedTableName,
-      columns,
-      conditions,
-      limit: executionState.limit,
-      offset: executionState.offset,
-      current_page: executionState.currentPage,
-      page_size: executionState.pageSize,
-      total_pages: executionState.totalPages,
-      sort_by: executionState.order,
-      strip_nulls: options?.stripNulls ?? true,
-      count: options?.count,
-      head: options?.head
-    };
     const sql = buildDebugSelectQuery({
       tableName: resolvedTableName,
-      columns,
-      conditions,
-      limit: executionState.limit,
-      offset: executionState.offset,
-      currentPage: executionState.currentPage,
-      pageSize: executionState.pageSize,
-      order: executionState.order
+      ...plan.debug
     });
-    return executeWithQueryTrace(
-      tracer,
-      {
-        operation: "select",
-        endpoint: "/gateway/fetch",
-        table: resolvedTableName,
-        sql,
-        payload,
-        options
-      },
-      async () => {
-        const response = await client.fetchGateway(payload, options);
-        return formatGatewayResult(response, { table: resolvedTableName, operation: "select" });
-      },
-      callsite
+    return executeExperimentalRead(
+      experimental,
+      () => executeWithQueryTrace(
+        tracer,
+        {
+          operation: "select",
+          endpoint: "/gateway/fetch",
+          table: resolvedTableName,
+          sql,
+          payload: plan.payload,
+          options
+        },
+        async () => {
+          const response = await client.fetchGateway(plan.payload, options);
+          return formatGatewayResult(response, { table: resolvedTableName, operation: "select" });
+        },
+        callsite
+      )
     );
   };
   const createSelectChain = (columns, options, initialCallsite) => {
@@ -4585,14 +5327,14 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
       if (options.limit !== void 0) {
         executionState.limit = options.limit;
       }
-      if (experimental?.findManyAst && canUseFindManyAstTransport(baseState)) {
+      if (experimental?.findManyAst && canUseFindManyAstTransport(baseState) && !selectShapeUsesRelationSchema(options.select) && !findManyAstWhereRequiresLegacyTransport(options.where)) {
         const resolvedTableName = resolveTableNameForCall(tableName, void 0);
         const payload = {
           table_name: resolvedTableName,
           select: options.select
         };
         if (options.where !== void 0) {
-          payload.where = options.where;
+          payload.where = normalizeFindManyAstWhere(options.where);
         }
         const astOrder = toFindManyAstOrder(executionState.order);
         if (astOrder !== void 0) {
@@ -4608,22 +5350,25 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
           limit: executionState.limit,
           order: executionState.order
         });
-        return executeWithQueryTrace(
-          tracer,
-          {
-            operation: "select",
-            endpoint: "/gateway/fetch",
-            table: resolvedTableName,
-            sql,
-            payload
-          },
-          async () => {
-            const response = await client.fetchGateway(
+        return executeExperimentalRead(
+          experimental,
+          () => executeWithQueryTrace(
+            tracer,
+            {
+              operation: "select",
+              endpoint: "/gateway/fetch",
+              table: resolvedTableName,
+              sql,
               payload
-            );
-            return formatGatewayResult(response, { table: resolvedTableName, operation: "select" });
-          },
-          callsite
+            },
+            async () => {
+              const response = await client.fetchGateway(
+                payload
+              );
+              return formatGatewayResult(response, { table: resolvedTableName, operation: "select" });
+            },
+            callsite
+          )
         );
       }
       return runSelect(
@@ -4871,7 +5616,7 @@ function createTableBuilder(tableName, client, formatGatewayResult, tracer, expe
   });
   return builder;
 }
-function createQueryBuilder(client, formatGatewayResult, tracer) {
+function createQueryBuilder(client, formatGatewayResult, experimental, tracer) {
   return async function query(query, options) {
     const normalizedQuery = query.trim();
     if (!normalizedQuery) {
@@ -4879,35 +5624,50 @@ function createQueryBuilder(client, formatGatewayResult, tracer) {
     }
     const payload = { query: normalizedQuery };
     const callsite = captureTraceCallsite(tracer);
-    return executeWithQueryTrace(
-      tracer,
-      {
-        operation: "query",
-        endpoint: "/gateway/query",
-        sql: normalizedQuery,
-        payload,
-        options
-      },
-      async () => {
-        const response = await client.queryGateway(payload, options);
-        return formatGatewayResult(response, { operation: "query" });
-      },
-      callsite
+    return executeExperimentalRead(
+      experimental,
+      () => executeWithQueryTrace(
+        tracer,
+        {
+          operation: "query",
+          endpoint: "/gateway/query",
+          sql: normalizedQuery,
+          payload,
+          options
+        },
+        async () => {
+          const response = await client.queryGateway(payload, options);
+          return formatGatewayResult(response, { operation: "query" });
+        },
+        callsite
+      )
     );
   };
 }
 function createClientFromConfig(config) {
+  const gatewayHeaders = {
+    ...config.headers ?? {}
+  };
+  if (config.auth?.bearerToken && gatewayHeaders["X-Athena-Auth-Bearer-Token"] === void 0 && gatewayHeaders["x-athena-auth-bearer-token"] === void 0) {
+    gatewayHeaders["X-Athena-Auth-Bearer-Token"] = config.auth.bearerToken;
+  }
   const gateway = createAthenaGatewayClient({
     baseUrl: config.baseUrl,
     apiKey: config.apiKey,
     client: config.client,
     backend: config.backend,
-    headers: config.headers
+    headers: gatewayHeaders
   });
   const formatGatewayResult = createResultFormatter();
   const queryTracer = createQueryTracer(config.experimental);
   const auth = createAuthClient(config.auth);
-  const from = (table) => createTableBuilder(table, gateway, formatGatewayResult, queryTracer, config.experimental);
+  const from = (table, options) => createTableBuilder(
+    resolveTableNameForCall(table, options?.schema),
+    gateway,
+    formatGatewayResult,
+    queryTracer,
+    config.experimental
+  );
   const rpc = (fn, args, options) => {
     const normalizedFn = fn.trim();
     if (!normalizedFn) {
@@ -4923,13 +5683,14 @@ function createClientFromConfig(config) {
       captureTraceCallsite(queryTracer)
     );
   };
-  const query = createQueryBuilder(gateway, formatGatewayResult, queryTracer);
+  const query = createQueryBuilder(gateway, formatGatewayResult, config.experimental, queryTracer);
   const db = createDbModule({ from, rpc, query });
   return {
     from,
     db,
     rpc,
     query,
+    verifyConnection: gateway.verifyConnection,
     auth: auth.auth
   };
 }